Primul proiect de protocol

Ce este Protocolul - primul

Protocolul - primul este o abordare în care un contract de interacțiune între componente (servicii, clienți, parteneri externi) este proiectat și fixat înainte de implementare. Codul, stocarea, infrastructura și documentația fac obiectul contractului și sunt generate automat din acesta și nu invers.

Spre deosebire de cod-primul, în cazul în care API este doar un produs secundar al codului, Protocolul-primul face protocolul un artefact primar: acesta deține concepte de domeniu, modele de date, statusuri, erori, semantica idempotenta, SLO/SLI, și chiar politica versiunii.

De ce ai nevoie de ea?

Coerența și predictibilitatea interfețelor din întreaga organizație.
Onboarding rapid (autogenerare SDK/stabil/client, erori uniforme și coduri).
Evoluție fiabilă (compatibilitatea sistemelor, contractele de testare, politica clară de versiune).
Focus produs: Discutați comportamentul, integrarea SLA și UX înainte de scrierea codului.
Automatizare: CI/CD colectează artefacte (clienți, cotoare de server, validatoare) dintr-o singură sursă de adevăr.
Securitate și conformitate: drepturile, mascarea PII, politicile de păstrare sunt consacrate în contract.

Abordarea de bază

1. Single Source of Truth (SSOT) - specificații care pot fi citite de mașină:

REST: OpenAPI/JSON Schema.
Evenimente și streaming: AsyncAPI, Avro/JSON Schema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: directive/politici SDL +.
2. Aranjamente pre-implementare: glosar de domenii, coduri de eroare, semantică idempotență, termene limită, retribuții, deduplicare.
3. Autogenerare: clienți/servere, tipuri, SDK-uri, contracte de testare, moks, colecții Postman, Terraform/OpenAPI Gateway config.
4. Guvernanță: lintere/politici (denumire, paginare, filtre, erori), revizuire prin intermediul breslei API, change-advisory pentru versiuni majore.
5. Compatibilitate: verificarea strictă a difuzoarelor „numai pentru aditivi”, a versiunilor semantice, a testelor canare/conduse de consumatori.
6. Observabilitate la nivel de contract: ID-urile de corelare, modelele de eroare, bugetele de întârziere sunt specificate în protocol.

Cum arată procesul (schelet)

1. Inițiere: scurtmetrajul produsului → călătoriile utilizatorilor → API/Protocol PRD (resurse/metode/evenimente, SLA/SLO, erori, limite).
2. Modelare: proiect de specificație (OpenAPI/AsyncAPI/Proto) + scheme de date, dicționar de termeni.
3. Contracte și integrări UX: exemple de sarcină utilă, contracte de eroare, hărți de stare, reguli de versionare.
4. Revizuire și guvernanță: lintere/standarde, discuții despre invarianții domeniului, blocare MGC (contract de garanție minimă).
5. Generarea automată a artefactelor: SDK-uri, înjunghieri, remedieri de testare, butuci de infrastructură (Gateway-uri, scopuri IAM).
6. Teste de implementare și contract: Furnizorul și consumatorii sunt supuși unor controale de compatibilitate în CI.
7. Observabilitate și SLO: urmărirea id-ului de corelare, catalogul de erori, bugetele retray/timeout.
8. Eliberări și evoluție: aditiv-first, politică de respingere, canar, steaguri de capacitate A/B.

Protocoale și stiluri de interacțiune

REST/HTTP

Standarde: model de resurse, 'GET/POST/PATCH/DELETE', paginare (cursor), filtre, sortare.
Domenii și scheme: JSON Schema, formate („data-time”, „uuid”), invarianți (regex/enum/min-max).
Erori: format unic ('type', 'code', 'title', 'detail', 'trace _ id'), mapare la stive HTTP.
Controlul schimbării: ETag/If-Match, chei idempotente pentru POST, semantică explicită 409/422.

gRPC/RPC

Protobuf: numerotarea etichetelor stabile, 'opțional', refuzarea reutilizării câmpurilor șterse.
Termene și priorități în contract; statusuri stabile (OK, INVALID_ARGUMENT, FAILED_PRECONDITION etc.).
Streaming: specificația comenzii mesajului, backpressure, remorci finale.

Event-driven (Kafka/NATS/SNS/SQS)

AsyncAPI: teme/canale, chei de partiționare, convenții cheie de eliminare a duplicatelor, retenții, semantică exact o dată "vs" cel puțin o dată "

Eveniment de bază și îmbogățire: sarcină utilă și extensii minime separate; versiunea 'event _ type '/' schema _ version'.
Idempotency: 'event _ id',' producer _ id', policy on retrays and deduplication.

GraphQL

SDL ca contract, directive pentru depreciere, limite de adâncime și complexitate, contract de coduri de eroare/extensii.

Integrarea cu principiile arhitecturale

Inverse Pyramid/Critical Path First: în caietul de sarcini, evidențiați MGC (minim obligatoriu), extensii - prin "? include = '/capabilities.
Drumuri pavate: un set de șabloane de specificații gata făcute (plată, KYC, audit, căutare, fișiere) + lintere.
API Gateways & Service Mesh: politici bazate pe contracte (limite de rată, scopuri auth, retries, întrerupătoare de circuit).

Versioning și evoluție

• Minor = doar câmpuri/canale aditive.
• Major = modificări de rupere (ștergeri, redenumire, schimbarea semanticii).
• Politica de respingere: ferestre de sprijin, antete 'Apus de soare', evenimente de notificare.
• Contracte bazate pe consumatori (CDC): verificarea faptului că API-ul actual satisface consumatori specifici.
• Schema directory: Schema Registry/Artifact Registry cu reguli de istorie și compatibilitate (BACKWARD/FORWARD/FULL).

Siguranță și conformitate

Autentificarea/autorizarea ca parte a contractului (scopuri OAuth2/OIDC, mTLS, JWT creanțe).
PII/PCI: mascare, formate de tokenizare, câmpuri cu moduri speciale de stocare/TTL.
Politici de audit: atribute necesare ("actor", "subiect", "acțiune", "a apărut _ la", "trace _ id').
Limite: anteturi de limită a ratei, cote, dimensiuni de mesaje, termene limită.

Observabilitatea contractului

Corelație/Cerere-ID: necesar în caietul de sarcini.
Eroare Catalog - listă fixă de coduri și SLA-uri pentru a rezolva.
SLI/SLO: latență p50/p95, proporția răspunsurilor reușite, proporția evenimentelor compatibile, proporția repetărilor idempotente.

Testarea și calitatea

Testele contractuale (furnizor ↔ consumator), schema diff in CI, generarea de servere mock.
Eșantioane de aur: exemple de referință de cereri/răspunsuri, corpuri pentru e2e.
Injecție de haos/latență: verificare timeout/retray, degradarea extensiilor la salvarea MGC.

Șabloane de domeniu de probă

Plata (REST + Evenimente)

'POST/payments' →' 201 Creat 'cu' payment _ id', 'status = autorizat'.
Plata evenimentului. autorizat. v1 '(ядро):' {payment_id, suma, moneda, metoda, occurred_at} '.
Plata extensiei. îmbogățit. v1 ': rata de risc, geo, amprenta dispozitivului.
Erori: '422' (validare), '402' (plată necesară), '409' (duplicat).
SLA: autorizație ≤ 800ms p95; eveniment kernel ≤ 2c lag p95.

KYC (cozi gRPC +)

RPC 'StartVerification (user_id)' → 'operation _ id'.
Evenimente de progres în topic 'kyc. status. v1 "(" În aşteptare "→" APROBAT/RESPINS ").
Contractul stipulează câmpurile PII, termenul de valabilitate, mascarea, codurile de eșec cauzal.

Audit (numai pentru evenimente)

Audit. înregistrat. v1 „(ядро):” actor „,” subiect „,” acțiune „,” a avut loc _ la „,” trace _ id'.
Îmbogățire: IP, dispozitiv, geo - un eveniment separat/fir, nu blochează nucleul.

Instrumente și automatizări (stivă aproximativă)

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: Spectral, OpenAPI Diff, Buf (protobuf), controale de compatibilitate SR Confluent.
Генерация: OpenAPI Generator, Buf/C, GraphQL Codegen, AsyncAPI Generator.
Gateway: Kong/Apigee/Azure/GCP GW, Trimisul.
Тесты: Pact/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
Registru: Git-director de scheme + Schema Registry/Artifact Registry.
Documentație: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

Anti-modele

Cod-primul de accident: „MVP în primul rând pe controlere”, specificație post-factual, discrepanță între documentație și comportament.
Swagger-wash: un OpenAPI formal fără reguli reale (erori, limite, SLA-uri, versiuni).
Pauză de compatibilitate: câmp eliminat/tip schimbat fără versiune majoră; reutilizarea etichetelor protobuf.
Răspuns „gros” fără paginare/filtre; lipsa idempotenţei.
Securitate off-contract: auth/Scopes sunt descrise în wiki, dar nu în caietul de sarcini.

Relația cu organizarea proceselor

API Guild: administratori de standarde, recenzii de schimbare, instruire.
Design Docs: pentru fiecare API - PRD, ADR (solutii), SLA, matrice de risc.
Managementul schimbării: proces RFC, note de lansare, ghiduri de migrare, deviație-cronologie.
Șabloane și șabloane pavate: generatoare cadru de service din caietul de sarcini (schelet handler, validare, logare).

Liste de verificare

Înainte de a începe

• Există un PRD și un glosar de domenii.
• Stilul selectat (REST/gRPC/Event/GraphQL) și formatul schemei.
• MGCs, erori, SLA/SLOs, reguli de idempotency definite.

În curs de dezvoltare

• Caietul de sarcini trece lintere și revizuire.
• SDK/Stabil/Auto-generare de fixare este configurat.
• Testele contractuale (CDC) sunt incluse în CI; schema-diff blochează schimbările incompatibile.

Înainte de lansare

• Documentație integrator cu exemple și coduri de eroare.
• Observabil contractual: corelație-id, catalog de erori, tablouri de bord SLI.

Politica de versionare și deprecierea sunt declarate.

ÎNTREBĂRI FRECVENTE

Cum Protocol-primul diferă de API-primul?
Adesea termenii sunt folosiți interschimbabil. În acest articol din Protocol - în primul rând, subliniem rigoarea contractului și acoperirea tuturor stilurilor (REST/RPC/Events/GraphQL), inclusiv SLA, siguranța și observabilitatea.

Va încetini această dezvoltare?
Startul poate fi un pic mai lung, dar apoi vom câștiga pe integrări, stabilitate și viteze de dezvoltare paralele (auto-generație, SDK-uri stabile).

Ce să faci cu experimente rapide?
Utilizați versiunile "draft' ale schemelor (draft), steaguri și cutii de nisip, dar nu săriți peste lintere și regulile de compatibilitate de bază.

Total

Primul proiect de protocol face din contract centrul arhitecturii: coordonăm comportamentul, fixăm schemele, automatizăm generarea și testele, evoluăm aditiv. Ca rezultat, obținem integrări previzibile, viteză mare de dezvoltare și rezistență a sistemelor la schimbările de scară și comandă.