REST API le RemObjects SDK: endpóintí JSON a leaganú go soiléir agus a dhífhabhtú (Delphi sleachta cód foinse)

Cén fáth a chinneann „REST API le RemObjects SDK“ go minic ar na imeallacha sa chleachtas

Ní bhíonn rath ar REST API le RemObjects SDK de ghnáth ag an tseirbhís «Hello World», ach sna pointí ina mbuaileann oibriú, córais oidhreachta agus comhtháthú: leaganú gan stad, iompar earráide comhsheasmhach thar gach pointe deiridh, debugging in-athfhiolmhar i slabhraí proxy agus an cumas iarratais a chomhghaolú go soiléir i gcás fadhb.

Tugann RemObjects SDK a lán bonneagair chuige: seirbhísí, formáidí teachtaireachta, serialú, óstáil (m.sh. mar Windows- agus Linux-Services nó taobh thiar de IIS/Reverse Proxy) agus pointí sainithe le haghaidh láimhseáil earráidí go lárnach. I bhfothracháin bogearraí gnó atá fásaithe is minic áfach nach bhfuil conradh curtha i bhfeidhm go leanúnach: Cén réimsí JSON atá seasta? Conas a léirímid earráidí? Conas a aithnímid iarratas arís má chuaigh sé trí Load Balancer, TLS-Termination agus il-sraitheanna backend?

Taispeánann an cur chuige seo (lena n-áirítear sleachta ó Delphi) líne chobhasta do RemObjects SDK: leaganú conarthaí JSON, Correlation-ID (Request-ID le haghaidh rianú) a éileamh, Exceptions a aistriú go státas HTTP agus go réada earráide JSON agus debugging agus oibriú a seachaint a chur i gcoinne a chéile. Ina theannta sin, dírímid ar chásanna imeallacha a tharlaíonn go minic i dtimpeallachtaí beo: threading ar an bhfreastalaí, rochtain ar bhunachar sonraí le athsholáthar BDE agus nasc dúchais, headair proxy, timeouts agus payloads cliant «salach».

Cinneadh ailtireachta: leaganú trí Cineál Meán (Media Type) seachas URL

Déantar leaganú ar go leor APIanna trí rianacha mar /v1/. Tá sé praiticiúil, ach i gcomhtháthú fadtéarmach (m.sh. ceangailtí ERP/DMS/CRM) cruthaíonn sé go minic dúbailtí URL, rianaí dúbailte, tástálacha dúbailte agus an cheist «Cén leagan atá á úsáid againn i ndáiríre?» i lámhleabhair oibriúcháin.

Is rogha eile leaganú trí an Cineál Meán (Content Negotiation). Seolann an cliant m.sh. Accept: application/vnd.company.order+json;v=2. Léann an freastalaí an leagan go dírithe agus oireann sé iompar an chonartha/DTO dá réir. Oibríonn sé seo i slabhraí proxy agus cache má chuirtear na ceannteidil go cruinn ar aghaidh. Do riaracháin is éigeantach go bhféachfar air freisin: is féidir iarratas a atsholáthar le Curl/Postman gan athrú ar na URLanna.

Níl RemObjects SDK «REST-puristisch», ach fráma seirbhíse praiticiúil. Sin é an fáth go bhfuil an rogha Cineál Meán úsáideach: is féidir leat pointí deiridh seasta a choinneáil agus conarthaí a fhorbairt ar aghaidh. Tá sé tábhachtach an leagan i gcónaí a léirmhíniú, cinneadh lárnach a dhéanamh in aon áit amháin agus an toradh a chur isteach i gcomhthéacs do sheirbhís.

Cathain a theipeann an leagan Accept-Header?

I bpráxis tá trí phointe briste tipiciúla atá le plé roimh ré:

• Polasaithe Proxy: Déanann roinnt Reverse Proxies/rialacha WAF Accept-Header a ghnáthú nó a scagadh. Ansin fillfidh d’API go ciúin ar an réamhshocrú. Réiteach: seiceáil rialacha proxy go sainráite; i gcásanna áirithe, bain úsáid as X-Api-Version mar réiteach cúltaca.
• Leabharlanna Cliant: Socraíonn roinnt cliaint HTTP Accept-Header féin agus scríobhann siad thar na luachanna. Réiteach: tacú le leagan an chonartha mar pharaiméadar ceiste roghnach freisin (mar fháillteach cúltaca amháin), nó an Accept-Header a pharsáil go toilteanach ar thaobh an fhreastalaí.

Sleachta ó fhoinse: Request-Context, Correlation-ID, Version agus Error-Mapping

Tá an cód gearrtha go cúramach ionas gur féidir é a ionchorprú i tionscadail freastalaí RemObjects atá ann cheana: sraithead beag comhthéacs, parser don leagan API (as Accept), meicníocht Correlation-ID agus Exception-Mapping lárnach. Coincheapa:

• Correlation-ID: ID uathúil in aghaidh gach iarratais, a thaispeántar arís sa fhreagra agus a luaitear i logaí.
• Exception-Mapping: Aistriú earráidí inmheánacha Delphi chuig réada earráide seasta, inbhainistithe ag an gcliant (lena n-áirítear stádas HTTP).
• Contract-Version: Leagan den chonradh JSON a rialálann an iompraíocht agus na réimsí.

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;
// Mar shampla: 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;
// Sa táirgeadh, gan sonraí inmheánacha, gan SQL, gan cosáin.
// Do Debug/Stage is féidir é a leathnú tríd an gcumraíocht.
begin
  if E is EApiError then
    Exit(E.Message);

  if E is EArgumentException then
    Exit('Paraiméadair neamhbhailí.');

  Exit('Earráid inmheánach.');
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.

Cuspóir: Comhthéacs iarratais seasmhach in ionad „go háit éigin i threadlocal“

Roinntear an snippet go comhgairmiúil: TApiContext is é an stát íosta atá uait a rith tríd. Sa RemObjects SDK rithíonn go leor ar bhonn chomhthéacs freastalaí/chainéil. I dtionscadail héiteirgeanacha (m.sh. snáitheanna oibre breise, DB-Queue, poist chúlra) bíonn sé minic níos iontaofa an comhthéacs a chur tríd go sainráiteach seachas ag brath ar threadlocals foláraithe, toisc go léiríonn sé comhoibriú agus athruithe comhthéacs níos soiléire.

Coinníollacha teorann: Tá an leagan leis an Accept-Header ag brath ar do Reverse Proxy (nginx, IIS ARR, Traefik) an header a chur ar aghaidh gan athrú. I roinnt timpeallachtaí scagtar nó comhcheanglaítear Accept-Headeranna „neamhghnácha”.

Rioscaí: Tá an leaganóireacht trí Accept chomh maith le do thástálacha. Má úsáideann cliaint leabharlanna a sháraíonn Accept, féadfaidh an API titim ar ais chuig an réamhshocrú. Tá fallback réamhshocraithe oiriúnach do chliaint legacy, ach ní mór é a dhéanamh le feiceáil i monatóireacht (m.sh. log-fhabhair «Version defaulted»).

Éagsúlachtaí: Má roghnaíonn tú leaganóireacht trí X-Api-Version: tá an parser mar an gcéanna, ach tagann an eolas ó header eile. Ó thaobh geataí (gateways) de bíonn sé uaireanta níos éasca é sin a rialú.

Ionghabháil i RemObjects SDK: Correlation-ID agus Exception-Mapping ag tosach an tseirbhíse

Tarlaíonn an éifeacht iomlán nuair a chuireann tú an mheicnic i bhfeidhm go comhsheasmhach ar imeall do fhreastalaí: léigh an oiread sin ó na headeranna ag tosnú an iarratais, agus aistrigh eisceachtaí isteach i freagra seasmhach ag an mbealach amach. Ag brath ar an óstáil (m.sh. RO-HTTP-Server, IIS-Hosting, seirbhísí féin-óstáilte Windows-/ Windows- agus Linux-Services) difríonn na pointí hook sonracha; fanann an prionsabal mar an gcéanna: tóg an Context, glaoigh an loighic ghnó, mapaigh eisceachtaí go lárnach.

I dtionscadail RemObjects oibrítear go minic go díreach ar gach modh seirbhíse. Oireann sé sin go maith ag an tús, ach bogann sé i dtreo corráin le linn ré an oibriúcháin: tógann gach modh logáil agus láimhseáil earráidí go difriúil. Is gearrscár soiléir bun-seirbhís seirbhíse nó dispatcher a thugann caighdeánú ar an gcaoi sin.

Próiseas praiticiúil (go gairid agus gar don chur i bhfeidhm)

1. Léigh an Correlation-ID ón Request-Header X-Correlation-ID; má tá sé in easnamh, gintear é ar an taobh freastalaí (m.sh. GUID).
2. Léigh an Contract-Version ón Accept (nó ón X-Api-Version).
3. Logáil tús an iarratais: modh, cosán, Correlation-ID, IP iargúlta, tosú tomhais ama.
4. Rith an loighic ghnó; pacáil rochtainí DB, más féidir, i ngnóthais i dtríthoisc.
5. Gabh eisceachtaí: socraigh an stát HTTP cuí, cruthaigh réad earráide JSON, socraigh an Response-Header X-Correlation-ID.
6. Logáil deireadh an iarratais: stát, fad, agus, más infheidhme, cód earráide.

Snáitheáil ar an freastalaí: Cén fáth nach bhfuil Correlation-ID fiúntach gan disciplín comhthéacs

Saincheist choitianta i Delphi: spreagann modh an tseirbhíse obair neamhthráthúil (m.sh. gineadóir tuarascála, allmhairiú, push isteach i DMS). Ansin ní hé an snáithe iarratais bhunaidh an ceann a scríobhann na línte logála níos déanaí. Má tá an Correlation-ID ar eolas «ag an tús amháin» amháin, briseann an inchreidsheacht ar leanúnachas na gcásanna.

Rialachán phraiticiúil: tabhair an Context ar shonraí go soiléir do gach rud nach bhfanann go docht ar an snáithe iarratais. Cé go bhféachann sé mar liosta paraiméadar níos faide, íocann sé siar ó thaobh intuarganachta. Mar mhalairt is féidir oibriú le réad comhthéacs sonraithe go soiléir a sheoltar chuig oibrithe (seachas athróg domhanda nó singiltní foláraithe).

Pointí tipiciúla ina mbíonn sé ag imeacht i seirbhísí RemObjects/Delphi:

• DB-Connections pro Thread: DB-Connections in aghaidh snáithe ní mhalartaítear go huathoibríoch go sábháilte idir snáitheanna. Is minic go mbíonn Connection-Pool nó ceangal ceannaithe in aghaidh snáithe níos réasúnaí ná „ceangal domhanda amháin“.
• Transaktionsgrenzen: Má tá roinnt céimeanna laistigh d’iarratas a bhaineann lena chéile, caithfidh an transaíocht fanacht laistigh den aonad lóighciúil chéanna. Níor chóir go leanfadh obair asíncrónach ar aghaidh sa transaíocht chéanna go hearráidí.
• Cancellation: Nuair a ghearrann an cliant (m.sh. Proxy timeout, brabhsálaí dúnta), is minic a leanann an freastalaí ar aghaidh. Machnaigh go cúramach an bhfuil ciall leis an obair chúlra i ndálaí den sórt sin.

Rochtain sonraí agus cóid earráide: Níl 409 ‚mar 500‘

I dtionscadail chomhtháthaithe tá mappáil earráide glan i bhfad níos mó ná cosmaideach. Socraíonn sé an bhféadfadh an córas eile (ERP-Connector, ETL-Job, Portáil chustaiméara) freagairt i gceart. Seo roinnt treoracha praiticiúla a chuirfidh le cobhsaíocht i dtimpeallachtaí Delphi/RemObjects:

• 400 Bad Request: Fíorú, paraiméadair in easnamh/neamhbhailí, JSON nach féidir a pharsáil. Tábhachtach: ba chóir don fhreagra fanacht seasmhach, fiú má tá an corp briste.
• 401/403: Scarfaidh tú aithint ó cheadúnas. Ciallaíonn 401 “aithne níl ann/nádéanta” agus ciallaíonn 403 “aithne ceart, ach tá an gníomh toirmiscthe”.
• 404: Níl an acmhainn ann. Bí cúramach le slándáil: ní gá i gcónaí a nochtadh an bhfuil acmhainn ann.
• 409 Conflict: Coinbhleacht ghnóúil (m.sh. coinbhleacht leaganacha, “ní cheadaíonn stádas an gníomh seo”, sárú eochair uathúil má tá sé ábhartha go trádála).
• 422 Unprocessable Content: Má tá an sintacs ceart ach go theipeann ar fhíorú gnóúil (ní úsáideann gach foireann 422, ach go minic bíonn sé níos soiléire ná 400).
• 500: Gach rud nach féidir leat a rangaú go cruinn — lena n-áirítear DB down, Timeout, Unhandled Exception.

Leideanna sonrach do Delphi: Tiocfaidh go leor earráidí bunachar sonraí mar Exceptions ghinearálta. Tá sé fiúntach sa chiseal rochtana sonraí a sheiceáil go sonrach le haghaidh cásanna ar eolas agus iad a thiontú isteach i EApiError. Tábhachtach: ná greamaigh slisní SQL ná ainmneacha tábla/colún inmheánacha isteach i teachtaireacht chuig an gcliant. Ba cheart na sonraí sin a logáil — ní i gFreagra an API iad.

Cleas Debugála: earráidí inathghiniúna trí „Contract Snapshot“

Neamhghnách, ach an-úsáideach san oibríocht: sábháil i gcás earráidí (nó go dírithe do Correlation-IDs áirithe) “snapshot” de cheanntásca iarratais + corp iarratais i gcomhad spool dífhabhtaithe. Ní hé seo logging buan (cosaint sonraí / toirt), ach uirlis rialaithe chun cásanna deacra a athchruthú i dteannta táirgeachta.

Tábhachtach: Níor chóir don snapshot riamh ceanntásca Auth, Tokens nó sonraí pearsanta a choimeád gan scagadh. Sa chleachtas ciallaíonn sé sin: redaction (maiscáil) agus gníomhachtú ach trí Feature-Flag nó Whitelist (m.sh. do Correlation-IDs sonrachta amháin agus le fuinneog ama ghairid).

Cur i bhfeidhm glan sa chleachtas: Maiscáil seachas eisiamh

I gcomhtháthuithe dáiríre is minic gur iad na réimsí “criticiúla” iad siúd a theastaíonn chun dífhabhtú (m.sh. aitheantóirí). In ionad iad a bhaint go simplí, is fearr iad a mhaiscáil: ionadú páirteach tokenanna, coimeád ach an fearannán d’aon seoladh ríomhphoist, IBAN ach na huimhreacha deireanacha. Coinníonn sé sin an cás inathghiniúnach gan sonraí iomarcacha a scaipeadh ar an gcóras comhad. Ba cheart don snapshot a bheith lipéadaithe go soiléir mar ealaín dífhabhtaithe agus a bheith le tréimhse coinneála shonraithe.

Sábháilteacht agus Oibríocht: Aistriú Header, Slabhraí Proxy agus Timeouts

Ní chríochnaíonn REST API go minic díreach ag an gcliant. Is gnách go mbíonn slabhraí Reverse Proxy, TLS-Termination, WAF nó API-Gateway i gceist. Ó sin tagann roinnt gnéithe praiticiúla:

• Remote IP: Ná bí ag brath go dall ar X-Forwarded-For. Glac le luachanna ó proxies iontaofa amháin; mura bhfuil muinín agat, bain úsáid as an IP soicéad díreach. I lámhleabhair oibríochta ba chóir a bheith soiléir cé na hops atá “trusted”.
• Timeouts: Má tá timeout 30 soicind ag an proxy ach go gcaitheann do backend 2 nóiméad, cruthaíonn tú Ghost-Requests. Socraigh timeouts go comhsheasmhach trasna na slabhra agus cinntigh rogha soiléir: request sínchrónach nó patrún postála (202 Accepted + endpoint stádais).
• Correlation-ID: Cuir an Correlation-ID sna response-headers ionas gur féidir le riarthóirí í a cheangal idir logs agus an taobh cliant. Má úsáideann gateway féin-IDs iarratais: logáil agus mapáil an dá ID.
• Fehlertexte: Sa táirgeadh, gan sonraí inmheánacha a nochtadh. Sonraí dífhabhtaithe ach go smachtithe (Stage/Feature-Flag) agus, má tá amhras ann, coinnigh iad sa log amháin.

Suirbhé: Cén fáth a bhféadfadh RemObjects SDK a bheith i bhfabhar anseo

I ngealltanais Delphi tógálacha, tógann daoine REST-Server go minic le framworkanna níos éadroime (m.sh. routers HTTP minimalacha). Spreagann RemObjects SDK a láidreachtaí nuair atá ailtireacht ilshrúnna agat nó nuair is gá í:

• Teorainneacha Seirbhíse Soiléir: Tá na modhanna seirbhíse sainithe go hoscailte agus tá conarthaí in-eagrúint le haghaidh versionála.
• Iompórtálacha agus Sraithiú: Is féidir leat JSON a úsáid, ach freisin formáidí teachtaireachta eile (ag brath ar an setup), gan an loighic ghnó a mheascadh.
• Oibríocht: Tá roghanna hosting agus comhéadan le seirbhísí Windows- agus Linux-Services ináplanáilte, lena n-áirítear rollouts glan.

Cuireann an cur chuige léirithe na codanna sin leis a mbíonn easpa orthu go minic sa ghnáthshaol: rudaí earráide aonchineálacha, versionáil indéantaitheach agus logging corrlithe. Go háirithe i gcás bogearraí gnó saincheaptha le timthriallta fada saoil, sábhálann sé ama ar nuashonruithe agus ar chomhtháthú córais seachtracha.

Conclúid: An fiú an iarracht — agus cá háit a theipeann an cur chuige?

Tá an luach ag teacht má tá do chomhéadan REST ní hamháin “ag obair”, ach inbhainistithe go seasmhach: conarthaí JSON seasta, versionáil gan url-chaos, earráidí intuigthe agus dífhabhtú gan imreoir imníoch. Sa chás sin tá an cur chuige le Context, Correlation-ID agus Exception-Mapping lárnach i RemObjects SDK láidir.

Teorainneacha úsáide: Má tá tú ag rith ach aon endpoint aonair, gearrshaolach, gan comhpháirtithe comhtháthaithe, is féidir le Media-Type-Versionierung bheith mar overengineering. Ní dhéanann Snapshot-Logging ciall ach má chuireann tú Redaction agus gníomhachtú i bhfeidhm go disciplínte. Agus: má dhéanann do shraith proxy optimú nó baintear headers, caithfidh tú an bonneagar a cheartú ar dtús — murach sin beidh tú ag dífhabhtú an shraithe mícheart.

Má tá tú ag nua-aoisiú seilfe Delphi-server nó má tá gá le réiteach bogearraí dlúthphróisis a iontráil go glaine i ERP/DMS/CRM, is minic iad na meicníochtaí seo an difríocht idir “ag rith sa tástáil” agus “ag rith sa táirgeadh”.

Sa chomhthéacs ghairmiúil imríonn freisin Delphi REST-API agus REST-Server agus Remobjects Sdk Delphi ról tábhachtach, nuair is gá go n-oibreoidh comhtháthúcháin, sreafaí sonraí agus forbairt leanúnach go glan le chéile.

Pléigh tionscadal nó tionscnamh nuachóirithe le Net-Base.