REST API ar RemObjects SDK: JSON galapunktu skaidra versiju pārvaldība un atkļūdošana (Delphi koda fragments)

Kāpēc „REST API ar RemObjects SDK” praksē bieži nosaka iznākumu robežsituācijās

REST API ar RemObjects SDK reti tiek uzvarēta vai zaudēta pie “Hello World” servisa; izšķirošas ir tās vietas, kur saskaras ekspluatācija, mantotās sistēmas un integrācija: versiju pārvaldība bez apstāšanās, konsekvents kļūdu uzvedums visos galapunktos, reproducējama atkļūdošana proxy ķēdēs un spēja problēmu gadījumā viennozīmīgi korelēt pieprasījumus.

RemObjects SDK nodrošina daudz infrastruktūras: servisus, ziņojumu formātus, serializāciju, hostingu (piem., kā Windows- un Linux-servisi vai aiz IIS/Reverse Proxy) un definētas vietas, kur centralizēti apstrādāt kļūdas. Tomēr izaudzētās biznesa programmatūras vidēs bieži trūkst konsekventa līguma: kuri JSON lauki ir stabilie? Kā mēs signalizējam kļūdas? Kā mēs atkārtoti identificējam pieprasījumu, ja tas ir gājis cauri Load Balancer, TLS-terminācijai un vairākām backend kārtām?

Nākamais piegājiens (ar iekļautiem Delphi-fragmentiem) demonstrē robustu līniju RemObjects SDK: JSON līgumu versiju pārvaldība, Correlation-ID (pieprasījuma ID izsekošanai) uzspiešana, Exceptions tulkošana uz HTTP statusiem un JSON kļūdu objektiem, vienlaikus neizcevējot atkļūdošanu pret ekspluatāciju. Papildus apskatām maldzinājumus, kas reālās vidēs regulāri parādās: servera threading, datu bāzes piekļuve ar BDE-aizvietošanu ar natīvu savienojumu, proxy headeri, timeouts un “netīras” klientu payloads.

Arhitektūras lēmums: versiju pārvaldība caur medija tipu, nevis URL

Daudzas API versē, izmantojot ceļus kā /v1/. Tas ir pragmatiski, taču ilgāk strādājošās integrācijās (piem., ERP/DMS/CRM savienojumos) tas bieži noved pie URL dublikācijām, dublētām maršrutēšanām, dublētiem testiem un jautājuma “kuru versiju mēs īsti izmantojam?” darbības rokasgrāmatās.

Alternatīva ir versiju pārvaldība caur medija tipu (satura vienošanās). Klients sūta, piemēram, Accept: application/vnd.company.order+json;v=2. Servers deterministiski nolasa versiju un pielāgo contract/DTO uzvedību. Tas strādā proxy un kešēšanas ķēdēs, ja headeri tiek tīri nodoti tālāk. Administratoriem tas arī ir labi pārbaudāms: pieprasījumu var reproducēt ar Curl/Postman, neatšķirot URL.

RemObjects SDK nav „REST-puristisks”, bet pragmatisks servisa ietvars. Tieši tāpēc medija tipu variants ir lietderīgs: jūs varat saglabāt stabilus galapunktus un tomēr attīstīt līgumus. Svarīgi ir tas, ka jūs versiju vienmēr izvērtējat, centrāli pieņemat lēmumu un rezultātu pārnesat uz sava servisa kontekstu.

Kad Accept-Header variants kļūst problemātisks?

Praksē ir trīs tipiskas lūzuma vietas, kuras būtu risināt iepriekš:

• Proxy politikas: daži Reverse Proxy/WAF noteikumi normalizē vai filtrē Accept headerus. Tad jūsu API klusībā atkārtoti nokļūst uz noklusējuma uzvedumu. Risinājums: skaidri pārbaudīt proxy noteikumus, nepieciešamības gadījumā pāriet uz X-Api-Version kā rezervi.
• Klientbibliotēkas: daži HTTP klienti uzstāda savus Accept headerus un pārraksta vērtības. Risinājums: atbalstīt kontrakta versiju arī kā izvēles query-parametru (tikai kā fallback) vai servera pusē toleranti parsēt Accept headeru.
• Kešēšana: Ja tiek izmantota atbildes kešēšana, kešam jāmainās atkarībā no Accept (Vary: Accept), citādi tas piegādās versiju 1 Version-2 klientiem. Risinājums: apzināti uzstādīt Vary vai atslēgt kešēšanu API līmenī.

Avota fragments: Pieprasījuma konteksts, Correlation-ID, Versija un izņēmumu kartēšana

Kods ir apzināti veidots tā, lai to var iekļaut esošajos RemObjects-Serverprojektos: neliels konteksta slānis, parseris API versijas nolasīšanai (no Accept), Correlation-ID mehānisms un centrāla izņēmumu kartēšana. Termini:

• Correlation-ID: Unikāla ID katram pieprasījumam, kas parādās atbildē un uz kuru atsaucas žurnāli.
• Exception-Mapping: Iekšējo Delphi-izņēmumu pārtulkošana uz stabilām, klientam apstrādājamām kļūdu struktūrām (ieskaitot HTTP statusu).
• Contract-Version: JSON līguma versija, kas nosaka uzvedību un laukus.

unit Api.Infrastructure;

interface

uses
  System.SysUtils, System.Classes, System.StrUtils, System.Generics.Collections,
  System.JSON;

type
  EApiError = class(Exception)
  private
    FHttpStatus: Integer;
    FCode: string;
    FCorrelationId: string;
  public
    constructor Create(const AHttpStatus: Integer; const ACode, AMessage, ACorrelationId: string);
    property HttpStatus: Integer read FHttpStatus;
    property Code: string read FCode;
    property CorrelationId: string read FCorrelationId;
  end;

  TApiContext = record
    CorrelationId: string;
    ContractVersion: Integer;
    RemoteIp: string;
    UserAgent: string;
    class function New: TApiContext; static;
  end;

  TApiVersion = record
    class function FromAcceptHeader(const AAccept: string; const ADefault: Integer = 1): Integer; static;
  end;

  TApiErrorMapper = class
  public
    class function ToErrorJson(const E: Exception; const ACorrId: string): TJSONObject; static;
    class function ToHttpStatus(const E: Exception): Integer; static;
    class function SafeMessage(const E: Exception): string; static;
  end;

implementation

{ EApiError }

constructor EApiError.Create(const AHttpStatus: Integer; const ACode, AMessage, ACorrelationId: string);
begin
  inherited Create(AMessage);
  FHttpStatus := AHttpStatus;
  FCode := ACode;
  FCorrelationId := ACorrelationId;
end;

{ TApiContext }

class function TApiContext.New: TApiContext;
begin
  Result.CorrelationId := '';
  Result.ContractVersion := 1;
  Result.RemoteIp := '';
  Result.UserAgent := '';
end;

{ TApiVersion }

class function TApiVersion.FromAcceptHeader(const AAccept: string; const ADefault: Integer): Integer;
// Erwartet z.B.: application/vnd.company.order+json;v=2
var
  Parts: TArray<string>;
  P: string;
  V: string;
  I: Integer;
begin
  Result := ADefault;
  if AAccept.Trim.IsEmpty then
    Exit;

  Parts := AAccept.Split([';', ',']);
  for P in Parts do
  begin
    V := Trim(P);
    if StartsText('v=', V) then
    begin
      if TryStrToInt(Copy(V, 3, MaxInt), I) and (I > 0) and (I < 100) then
        Exit(I);
    end;
  end;
end;

{ TApiErrorMapper }

class function TApiErrorMapper.SafeMessage(const E: Exception): string;
// Im Betrieb keine internen Details, keine SQL, keine Pfade.
// Für Debug/Stage kann man das über Konfiguration erweitern.
begin
  if E is EApiError then
    Exit(E.Message);

  if E is EArgumentException then
    Exit('Ungültige Parameter.');

  Exit('Interner Fehler.');
end;

class function TApiErrorMapper.ToHttpStatus(const E: Exception): Integer;
begin
  if E is EApiError then
    Exit(EApiError(E).HttpStatus);

  if E is EArgumentException then
    Exit(400);

  Exit(500);
end;

class function TApiErrorMapper.ToErrorJson(const E: Exception; const ACorrId: string): TJSONObject;
var
  Code: string;
  Status: Integer;
  Msg: string;
begin
  Status := ToHttpStatus(E);
  Msg := SafeMessage(E);

  if E is EApiError then
    Code := EApiError(E).Code
  else if E is EArgumentException then
    Code := 'bad_request'
  else
    Code := 'internal_error';

  Result := TJSONObject.Create;
  Result.AddPair('error', TJSONObject.Create
    .AddPair('code', Code)
    .AddPair('message', Msg)
    .AddPair('httpStatus', TJSONNumber.Create(Status))
    .AddPair('correlationId', ACorrId));
end;

end.

Mērķis: Stabils pieprasījuma konteksts, nevis „kaut kur threadlocal”

Šis piemērs apzināti atdala: TApiContext ir minimālais stāvoklis, ko vēlaties nodot tālāk. RemObjects SDK lielā daļa loģikas balstās uz servera/kanāla kontekstu. Heterogēnos projektos (piem., papildu worker pavedieni, DB-rinda, fonprocesi) eksplicīta konteksta nodošana bieži ir robustāka par implicītiem Threadlocals, jo tā padara paralēlismu un konteksta pārslēgšanos redzamāku.

Priekšnosacījumi: Accept-hedera variants pieņem, ka jūsu reverse proxy (nginx, IIS ARR, Traefik) šo headeru pārsūta nemainītu. Dažās vidēs “neparastie” Accept-header tiek filtrēti vai apvienoti.

Riska punkti: Versiju vadība caur Accept ir tik laba, cik jūsu testi. Ja klienti izmanto bibliotēkas, kas pārraksta Accept, API var pēkšņi atgriezties pie noklusējuma. Legacy klientiem noklusējuma fallback ir lietderīgs, taču tam jābūt redzamam monitoringa līmenī (piem., žurnāla brīdinājums „Version defaulted”).

Varianti: Ja dodat priekšroku versiju vadībai caur X-Api-Version: parsers ir identisks, mainās tikai avots — cits header. No gateway skatu punkta tas dažkārt ir vieglāk kontrolējams.

Integrācija RemObjects SDK: Correlation-ID un izņēmumu mapešana pie servisa ieejas

Reālā ietekme rodas, ja šo mehāniku konsekventi pielieto jūsu servera perifērijā: vienreiz pie pieprasījuma ieejas nolasīt no hederiem, vienreiz pie izņēmuma iziešanas pārtulkot stabilā atbildē. Atkarībā no hostinga (piem., RO-HTTP-Server, IIS-Hosting, pašpārvaldīts Windows-/ Windows- un Linux-services) konkrētie hook punkti atšķirsies; princips paliek nemainīgs: uzbūvēt Context, izsaukt biznesa loģiku, centrāli mapēt Exceptions.

RemObjects projektos bieži strādā tieši pie katras servisa metodes. Sākotnēji tas labi mērogojas, taču ekspluatācijā parasti problēmas: katra metode būvē loggingu un kļūdu apstrādi atšķirīgi. Tīrs šķērsslānis ir Service-Basis vai Dispatcher, kas standartizē šo uzvedību.

Praktiskais process (apzināti īsi un implementācijai tuvi)

1. Nolasīt Correlation-ID no pieprasījuma hedera X-Correlation-ID; ja tā nav, ģenerēt servera pusē (piem., GUID).
2. Nolasīt contract-versiju no Accept (vai no X-Api-Version).
3. Reģistrēt pieprasījuma sākumu: metode, ceļš, Correlation-ID, remote IP, sākt ilguma mērījumu.
4. Izpildīt biznesa loģiku; DB piekļuves, cik iespējams, ietvert transakcijās.
5. Noķert izņēmumus: noteikt HTTP statusu, izveidot JSON kļūdas objektu, iestatīt response-hederu X-Correlation-ID.
6. Reģistrēt pieprasījuma beigas: statuss, ilgums, ja nepieciešams — kļūdas kods.

Threading serverī: Kāpēc Correlation-ID bez konteksta disciplīnas kļūst bezvērtīga

Bieža Delphi malā gadījuma situācija: servisa metode aktivizē asīnhronu darbu (piem., atskaišu ģenerēšana, imports, push uz DMS). Tad sākotnējais request-thread vairs nav tas, kas vēlāk ieraksta log rindas. Ja Correlation-ID ir zināma tikai “sākumā”, izsekojamība izjūk.

Pragmatiska vadlīnija: viss, kas nenotiek stingri request-thread ietvaros, saņem Context eksplicīti nodotu. Pat ja tas nozīmē garākas parametru sarakstus, tas atmaksājas. Alternatīva ir skaidri definēts konteksta objekts, kas apzināti tiek nodots workeriem (nevis globālas mainīgās vai slēptie singletons).

Tipiskie kritiskie punkti RemObjects-/Delphi serveros:

• DB savienojumi katram pavedienam: BDE-Ablosung mit nativer Anbindung-Verbindungen nav automātiski droši dalāmas starp pavedieniem. Connection-Pool vai viena savienojuma piešķiršana katram pavedienam bieži ir saprātīgāka nekā „globāla Connection“.
• Transakciju robežas: Ja pieprasījumā ir vairāki soļi, kas pieder kopā, transakcijai jāpaliek tajā pašā loģiskajā vienībā. Asinhrons darbs nedrīkst „nejauši“ turpināties tajā pašā transakcijā.
• Atcelšana: Ja klients pārtrauc savienojumu (proxy laika pārsniegums, pārlūka aizvēršana), serveris bieži turpina darboties. Apsveriet, vai fona darbs šādā gadījumā joprojām ir lietderīgs.

Datu piekļuve un kļūdu kodi: 409 ist nicht „auch ein 500“

Integrācijas projektos tīra kļūdu kartēšana nav tikai kosmētika. Tā nosaka, vai pretējā puse (ERP-Connector, ETL-Job, Klientu portāls) var pareizi reaģēt. Daži praktiski vadlīniju punkti, kas sevi ir pierādījuši Delphi/RemObjects vidēs:

• 400 Bad Request: Validācija, trūkstoši/nepareizi parametri, JSON neparsējams. Svarīgi: atbildei jābūt stabilai, pat ja Body ir bojāts.
• 401/403: Atšķiriet autentifikāciju no autorizācijas. 401 nozīmē „nav/derīga identitāte“, 403 „identitāte ok, bet aizliegts“.
• 404: Resurss neeksistē. Drošības apsvērumu dēļ ne vienmēr jāatklāj, vai kaut kas pastāv.
• 409 Conflict: Biznesa loģikas konflikts (piem., versiju konflikts, „statuss neļauj šo darbību“, unikālas atslēgas pārkāpums, ja tas ir nozīmīgs no biznesa viedokļa).
• 422 Unprocessable Content: Ja sintakse ir kārtībā, bet biznesa validācija neiztur (ne visi komandas izmanto 422, bet tas bieži ir skaidrāks nekā 400).
• 500: Viss, ko jūs nevarat skaidri klasificēt. Tam pieder arī „DB down“, „Timeout“, „Unhandled Exception“.

Delphi-specifisks paņēmiens: daudz DB kļūdu parādās kā ģeneriskas Exceptions. Ir vērts datu piekļuves slānī mērķtiecīgi pārbaudīt zināmas situācijas un pārvērst tās EApiError. Svarīgi: neiekļaujiet SQL fragmentus vai iekšējos tabulu/kolonnu nosaukumus klienta ziņojumā. Šīs detaļas pieder žurnālam, ne atbildei.

Debugging-paņēmiens: reproducējamas kļūdas ar „Contract Snapshot“

Neparasti, bet ekspluatācijā ārkārtīgi noderīgi: saglabājiet kļūdu gadījumā (vai mērķtiecīgi konkrētām Correlation-IDs) vienu „snapshot“ no Request-Headern + Request-Body Debug-Spool failā. Tas nav pastāvīgs žurnēšana (datu aizsardzība/apjoma apsvērumi), bet kontrolēts instruments, lai reproducētu grūti atkārtojamas situācijas tuvu ražošanas vidēm.

Svarīgi: Snapshot nekad nedrīkst nekontrolēti saglabāt Auth-Header, Tokenus vai personas datus. Praktiski tas nozīmē: redaction (maskēšana) un aktivēšana tikai caur feature-flag vai baltā saraksta mehānismu (piem., tikai konkrētām Correlation-IDs, īsi laika logi).

Tīra īstenošana praksē: maskēšana, ne izņemšana

Reālās integrācijās tieši „kritiskie“ lauki bieži ir tie, kas nepieciešami debugošanai (piem., identifikatori). Vietā vispārējai izņemšanai labāk ir maskēšana: tokenus daļēji aizstāt, e-pastā paturēt tikai domēnu, IBAN saglabāt tikai pēdējos ciparus. Tādējādi incidents paliek reproducējams, neradot liekus datus failu sistēmā. Papildus Snapshot jāatzīmē skaidri kā debug artefakts un tam jābūt ar definētu glabāšanas termiņu.

Drošība un ekspluatācija: HTTP galveņu nodošana, proksiju ķēdes un laika ierobežojumi

Vairumā gadījumu REST API reti beidzas tieši pie klienta. Parasti veidojas ķēdes no Reverse Proxy, TLS-Termination, WAF vai API-Gateway. No tā izriet praktiski apsvērumi:

• Attālinātā IP: Neuzticieties akli X-Forwarded-For. Pieņemiet to tikai no uzticamiem proksijiem un citādi izmantojiet tiešo socket-IP. Darbības rokasgrāmatās jānorāda, kuri hops ir uzticami.
• Laika ierobežojumi: Ja proksijam ir 30 sekundes, bet jūsu backendam nepieciešamas 2 minūtes, radīsiet spoku pieprasījumus. Noteikt laika ierobežojumus konsekventi pa ķēdi un izlemiet: sinhrons pieprasījums vai job-pattern (202 Accepted + statusa galapunkts).
• Correlation-ID: Ievietojiet Correlation-ID atbildes galvenēs, lai administratori to var sasaistīt starp žurnāliem un klienta pusi. Ja gateway izmanto savas Request-IDs: abu ID žurnālošana un sasaistīšana ir jānodrošina.
• Kļūdu teksti: Produktīvajā režīmā nesniedziet iekšējus datus. Debug-detaļas tikai kontrolēti (stage/feature-flag) un, ja nepieciešams, tikai žurnālā.

Iekārtošana: Kāpēc RemObjects SDK šeit var dot priekšrocību

Delphi-ekosistēmās REST-serverus bieži būvē, izmantojot vieglākus ietvarus (piem., minimālistiskus HTTP maršrutētājus). RemObjects SDK parāda savas stiprās puses, ja jums jau ir vai nepieciešama daudzslāņu arhitektūra:

• Skaidras servisa robežas: servisa metodes ir eksplītas, kontrakti ir versijojami.
• Transporti un serializācija: varat izmantot JSON, bet arī citus ziņojumu formātus (atkarībā no uzstādījuma), neizjaucot biznesa loģiku.
• Ekspluatācija: hostinga iespējas un integrācija esošajos Windows un Linux servisos ir plānojama, ieskaitot pārdomātu izvietošanu.

Parādītā pieeja papildina to ar sastāvdaļām, kas ikdienā bieži trūkst: vienoti kļūdu objekti, deterministiska versiju pārvaldība un korrelējams žurnālošanas mehānisms. Īpaši individuālajai uzņēmuma programmatūrai ar ilgu dzīves ciklu tas ietaupa laiku atjauninājumos un ārējo sistēmu integrācijā.

Secinājums: Vai pūles atmaksājas — un kur pieeja kļūst par pārlieku?

Papildvērtība rodas, ja jūsu REST saskarne ne tikai „funkcionē“, bet ir ilgtermiņā uzturama: stabilas JSON-līgumu definīcijas, versijēšana bez URL haosa, izsekojamas kļūdas un debugēšana bez minēšanas. Tieši šajā jomā pieeja ar Context, Correlation-ID un centralizētu izņēmumu kartēšanu RemObjects SDK ir spēcīga.

Pielietošanas ierobežojumi: Ja jums ir tikai viens īslaicīgs galapunkts bez integrācijas partneriem, Media-Type-versijēšana ātri pārvēršas par overengineering. Arī snapshot-logēšana ir jēdzīga tikai tad, ja disciplinēti ieviešat redaction un aktivāciju. Un: ja jūsu proksiju slānis optimizē vai noņem galvenes, vispirms jānostiprina infrastruktūra, citādi jūs debugojat nepareizo slāni.

Ja modernizējat esošu Delphi serveru ainavu vai nepieciešams tīri integrēt procesam tuvā programmatūras risinājumu ERP/DMS/CRM, tieši šie mehānismi bieži ir atšķirība starp „strādā testā“ un „strādā ekspluatācijā“.

Specializētajā jomā arī Delphi REST-API un REST-Server un Remobjects Sdk Delphi spēlē svarīgu lomu, kad integrācijām, datu plūsmām un tālākai attīstībai jādarbojas saskaņoti.

Pārrunāt projektu vai modernizācijas ieceri ar Net-Base.