> For the complete documentation index, see [llms.txt](https://docs.ecommerce.seb.ee/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecommerce.seb.ee/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/gaires/architektura-ir-pletinumas.md).
# Architektūra ir plėtinumas
Supraskite SDK portų ir adapterių architektūrą ir integruokite pasirinktinius infrastruktūros adapterius.
API kliento SDK sukurtas kaip **heksagoninė (portų ir adapterių) architektūra**. Kiekvienas infrastruktūros elementas, nuo kurio priklauso SDK — HTTP klientas, webhook klausytuvas, JWE šifruotuvas, JSON serializatorius, registratorius — yra už mažos sąsajos ( *portas*) ribų, kuri priklauso SDK taikomajam branduoliui. Komplekte pateikiami įgyvendinimai (*adapteriai*) yra numatytieji, o ne privalomi: bet kurią jų galite pakeisti savo.
Šiame puslapyje paaiškinama, kaip sukonstruotas SDK, kodėl jis sukonstruotas būtent taip ir ką toks sprendimas leidžia daryti. Dėl konkrečios adapterio pakeitimo sintaksės kiekvienoje kalboje žr. [SDK adapterių perrašymas](/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/gaires/sdk-adapteriu-perrasymas.md).
## SDK struktūra
EGW SDK – portų ir adapterių architektūra
Trys sluoksniai, viena priklausomybės kryptis:
* **Taikomasis branduolys** — `EgwClient` fasadą, po vieną API klasę kiekvienam domenui ir užklausos bei atsakymo DTO. Priklauso tik nuo portų.
* **Portai** — penkios mažos sąsajos, per kurias branduolys kreipiasi į išorę. Tai vienintelis SDK kontraktas su infrastruktūra.
* **Adapteriai** — konkretūs portų įgyvendinimai, naudojantys plačiai paplitusias bibliotekas. Šis **bootstrap** sluoksnis (kliento fabriko ir paslaugų teikėjo mechanizmo derinys) konstrukcijos metu nusprendžia, kuris adapteris užpildo kiekvieną portą.
## Penki portai
| Portas | Paskirtis |
| ------------------- | -------------------------------------------------------------------------- |
| API klientas | Išeinantys HTTP kvietimai, OAuth žetonų valdymas |
| API serveris | Įeinančių webhook pranešimų klausytojas |
| Duomenų šifruotuvas | Kortelių duomenų JWE šifravimas |
| Serializatorius | DTO JSON (de)serializavimas |
| Registratorius | Diagnostinis žurnalavimas (neprivalomas; numatytasis variantas be veiksmų) |
Portai sąmoningai siauri — API kliento portas turi du metodus (`perform`, `performWithoutAuth`), o šifruotuvas turi vieną (`encrypt`). Vieno įgyvendinimas yra kelių valandų darbas, o ne projektas.
Kiekvienas portas pateikiamas su numatytuoju adapteriu, sukurtu naudojant konkrečiai platformai skirtą plačiai paplitusią biblioteką. Savo kalbos skiltyje peržiūrėkite sąsajų pavadinimus ir adapterį, kuris užpildo kiekvieną portą:
Java
| Portas | Sąsaja | Numatytasis adapteris |
| ------------------- | ----------------- | --------------------------------------- |
| API klientas | `ApiClient` | `JavaNetHttpClient` (`java.net.http`) |
| API serveris | `ApiServer` | `ComSunNetHttpServer` |
| Duomenų šifruotuvas | `DataEncrypter` | `NimbusDataEncrypter` (Nimbus JOSE+JWT) |
| Serializatorius | `Serializatorius` | `JacksonSerializer` (Jackson) |
| Registratorius | `EgwLogger` | `NoOpEgwLogger` |
PHP
| Portas | Sąsaja | Numatytasis adapteris |
| ------------------- | ------------------------ | ------------------------------------------------- |
| API klientas | `ApiClientInterface` | `GuzzleHttpClient` (Guzzle 7) |
| API serveris | `ApiServerInterface` | `ReactPhpHttpServer` (ReactPHP) |
| Duomenų šifruotuvas | `DataEncrypterInterface` | `WebTokenDataEncrypter` (`web-token/jwt-library`) |
| Serializatorius | `SerializerInterface` | `NativeJsonSerializer` (vietinės `json_*`) |
| Registratorius | `EgwLoggerInterface` | `NoOpEgwLogger` |
C#
| Portas | Sąsaja | Numatytasis adapteris |
| ------------------- | ---------------- | ------------------------------------- |
| API klientas | `IApiClient` | `HttpApiClient` (`HttpClient`) |
| API serveris | `IApiServer` | `HttpListenerApiServer` |
| Duomenų šifruotuvas | `IDataEncrypter` | `JoseDataEncrypter` (`jose-jwt`) |
| Serializatorius | `ISerializer` | `JsonSerializer` (`System.Text.Json`) |
| Registratorius | `IEgwLogger` | `NoOpEgwLogger` |
Node.js / TypeScript
| Portas | Sąsaja | Numatytasis adapteris |
| ------------------- | ----------------- | --------------------------------------------- |
| API klientas | `ApiClient` | `AxiosApiClient` (axios) |
| API serveris | `ApiServer` | `HttpServerApiServer` (`node:http`) |
| Duomenų šifruotuvas | `DataEncrypter` | `JoseDataEncrypter` (`jose`) |
| Serializatorius | `Serializatorius` | `JsonSerializer` (`JSON` + DTO atvaizdavimas) |
| Registratorius | `EgwLogger` | `NoopEgwLogger` |
## Kodėl toks dizainas
Mokėjimų SDK veikia jūsų *jūsų* steke, o ne atvirkščiai. Jūsų backend jau turi HTTP klientą su sureguliuotais laiko limitais, tarpiniais serveriais ir interceptoriais; žurnalavimo karkasą su koreliacijos ID; testavimo aplinką, kuri negali atidaryti tikrų socketų. Monolitinis SDK, kuris pririša savo pasirinkimus, priverčia turėti po du kiekvieno komponento variantus.
Heksagoninis dizainas tai apverčia. Taikomasis branduolys — `EgwClient` fasadą, domeno API klases (`payments()`, `refunds()`, `tokens()`, sesijos API, `notifications()`) ir sugeneruotus DTO — turi mokėjimų logiką ir nieko nežino apie Guzzle, Jackson ar axios. Visos trečiųjų šalių priklausomybės apsiriboja adapterių sluoksniu. Ką tai duoda praktikoje:
* **Gimtoji integracija su steku.** Nukreipkite SDK HTTP srautą per savo klientą, kad jūsų esama laiko limito, tarpinio serverio, TLS ir stebėsenos politika galiotų ir mokėjimų kvietimams.
* **Stebimumas jūsų sąlygomis.** Prijunkite savo žurnalavimo karkasą (SLF4J, PSR-3, Serilog, pino) prie SDK žurnalo porto. Numatytasis variantas yra žurnalo vediklis be veiksmų — SDK tyli, kol nenurodysite jam paskirties vietos.
* **Testuojamumas.** Kiekvieną portą galima užstubinti. Vienetiniame teste galite naudoti visą fasadą ir sugeneruotus DTO su fiktyviu API klientu ir praleidžiančiu šifruotuvu, be tinklo ar imitacinio serverio.
* **Nėra priklausomybės nuo bibliotekų.** Jei į komplektą įtraukta priklausomybė konfliktuoja su jūsų platforma (Jackson versijų konfliktas, Guzzle didžioji versijos migracija), portą įgyvendinate pasirinkta biblioteka ir atsisakote į komplektą įtraukto adapterio — branduoliui tai neturi įtakos.
## Nuoseklumas tarp kalbų
Visi keturi SDK apima tas pačias API operacijas ir laikosi tos pačios architektūros, su tuo pačiu portų rinkiniu, tomis pačiomis fabriko sąvokomis ir veidrodiniais testų rinkiniais. Kiekvienoje kalboje keičiasi tik pavadinimų suteikimo konvencija ir SPI idiomą. Jei integruojate SDK į du stekus — arba migruojate iš vieno į kitą — mentalinis modelis persikelia visas; skiriasi tik perrašymo sintaksė.
## Adapterio pakeitimas
Kiekviena kalba leidžia pateikti savo bet kurio porto įgyvendinimą trimis būdais: perduoti fabrikui paruoštą egzempliorių, užregistruoti teikėją per SDK paslaugų teikėjo sąsajos (SPI) mechanizmą arba išplėsti kliento fabriką. Dėl prioritetų taisyklių ir pavyzdžių kiekvienai kalbai žr. [SDK adapterių perrašymas](/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/gaires/sdk-adapteriu-perrasymas.md).
## Susiję puslapiai
* [SDK adapterių perrašymas](/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/gaires/sdk-adapteriu-perrasymas.md) — kaip kiekvienoje kalboje pakeisti įtaisytą adapterį
* [Apžvalga](/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/apzvalga.md) — kalbų matrica, paketai, alfa būsena
* [Klaidų tvarkymas](/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/gaires/klaidu-valdymas.md) — `ECommException` hierarchija, kurioje dalyvauja jūsų adapteriai
* [Saugumo mechanizmuose](/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/gaires/saugumo-mechanizmai.md) — ką adapteris turi užtikrinti (žetonų valdymą, JWE, žurnalų maskavimą)
* Greitos pradžios kiekvienai kalbai: [Java](/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/greitos-pradzios/java.md) · [PHP](/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/greitos-pradzios/php.md) · [C#](/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/greitos-pradzios/c-.net.md) · [Node.js](/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/greitos-pradzios/node.js-typescript.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.ecommerce.seb.ee/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/gaires/architektura-ir-pletinumas.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
