Projekt pierwszy protokołu

Co to jest protokół pierwszy

Protokół pierwszy jest podejściem, w którym umowa o interakcję między komponentami (usługami, klientami, partnerami zewnętrznymi) jest projektowana i ustalana przed wdrożeniem. Kod, przechowywanie, infrastruktura i dokumentacja podlegają umowie i są automatycznie generowane z niej, a nie na odwrót.

W przeciwieństwie do kodu-first, gdzie API jest tylko produktem ubocznym kodu, Protocol-first sprawia, że protokół jest podstawowym artefaktem: posiada koncepcje domeny, modele danych, statusy, błędy, semantykę idempotencji, SLO/SLI, a nawet politykę wersji.

Dlaczego go potrzebujesz?

Spójność i przewidywalność interfejsów w całej organizacji.
Szybki pokład (SDK/stabilna/klient autogeneracja, jednolite błędy i kody).
Wiarygodne zmiany (zgodność systemów, umowy testowe, jasna polityka wersji).
Product Focus: Przedyskutuj zachowanie, integrację SLA i UX przed napisaniem kodu.
Automatyzacja: CI/CD zbiera artefakty (klienci, stuby serwera, walidatory) z jednego źródła prawdy.
Bezpieczeństwo i zgodność: prawa, maskowanie PII, polityka zatrzymywania są zapisane w umowie.

Podejście podstawowe

1. Pojedyncze źródło prawdy (SSOT) - specyfikacja do odczytu maszynowego:

ODPOCZYNEK: OpenAPI/JSON Schemat.
Wydarzenia i streaming: AsyncAPI, Avro/JSON Schema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: dyrektywy/polityki SDL +.
2. Ustalenia wstępne: słownik domeny, kody błędów, semantyka idempotencji, terminy, przekładki, deduplikacja.
3. Autogeneracja: klienci/serwer stubs, typy, SDK, umowy testowe, moks, kolekcje listonosza, Terraform/OpenAPI Gateway config.
4. Zarządzanie: linters/policies (naming, pagination, filters, errors), review via API guild, change-advisory for major versions.
5. Kompatybilność: ścisła weryfikacja dyfuzji „wyłącznie dodatków”, wersionizacji semantycznej, testów kanaryjskich/konsumenckich.
6. Obserwowalność na poziomie kontraktu: identyfikatory korelacji, modele błędów, budżety opóźnień są zapisywane w protokole.

Jak wygląda proces (szkielet)

1. Inicjacja: krótki produkt → podróże użytkownika → API/Protokół PRD (zasoby/metody/wydarzenia, SLA/SLO, błędy, limity).
2. Modelowanie: projekt specyfikacji (OpenAPI/AsyncAPI/Proto) + schematy danych, słownik terminów.
3. Umowy i integracje UX: przykłady ładowania, kontrakty na błędy, mapy stanu, zasady wersji.
4. Przegląd i zarządzanie: lintersy/standardy, dyskusja na temat niezmiennych domen, zamek MGC (minimalna umowa gwarancyjna).
5. Automatyczna generacja artefaktów: SDK, pchnięcia, mocowania testowe, zakładki infrastrukturalne (bramy, zakresy IAM).
6. Testy wdrożeniowe i kontraktowe: Dostawca i konsumenci są poddawani kontroli zgodności w CI.
7. Obserwowalność i SLO: odwzorowanie korelacji-id, katalog błędów, budżety retrasy/timeout.
8. Wydania i ewolucja: dodatek pierwszy, polityka odrzucenia, flagi kanaryjskie, A/B zdolności.

Protokoły i style interakcji

REST/HTTP

Standardy: model zasobów, 'GET/POST/PATCH/DELETE', paginacja (kursor), filtry, sortowanie.
Pola i schematy: Schemat JSON, formaty („data-time”, „uuid”), niezmienne (regex/enum/min-max).
Błędy: pojedynczy format ("typ", "kod", "tytuł", "detal", "trace _ id'), mapowanie na stosy HTTP.
Zmiana kontroli: ETag/If-Match, idempotent keys for POST, explicit semantics 409/422.

gRPC/RPC

Protobuf: stabilne numerowanie znaczników, „opcjonalne”, odmawiające ponownego użycia usuniętych pól.
Terminy i priorytety w umowie; stabilne statusy (OK, INVALID_ARGUMENT, FAILED_PRECONDITION itp.).
Streaming: specyfikacja zamówienia wiadomości, ciśnienie wsteczne, przyczepy końcowe.

Napędzane zdarzeniami (Kafka/NATS/SNS/SQS)

AsyncAPI: tematy/kanały, klucze podziału, konwencje klucza deduplicacji, retencje, dokładnie raz semantyka „vs' co najmniej raz”

Zdarzenie rdzenia i wzbogacenie: oddzielny minimalny ładunek użytkowy i rozszerzenia; wersja 'event _ type '/' schema _ version'.
Idempotencja: 'event _ id',' producer _ id', polityka dotycząca przekwalifikowania i deduplikowania.

GraphQL

SDL jako umowa, dyrektywy dotyczące deprecate, ograniczenia głębokości i złożoności, kody błędów/umowy przedłużenia.

Integracja z zasadami architektonicznymi

Odwrotna piramida/ścieżka krytyczna Najpierw: w specyfikacji należy podkreślić MGC (obowiązkowe minimum), rozszerzenia - poprzez '? include = '/capabilities.
Utwardzone drogi: zestaw gotowych szablonów specyfikacji (płatność, KYC, audyt, wyszukiwanie, pliki) + linterzy.
API Gateways & Service Mesh: zasady oparte na umowie (limity stawek, zakresy auth, ponowne próby, wyłączniki).

Wersioning i ewolucja

• Minor = tylko pola/kanały addytywne.
• Major = zmiany łamania (delecje, zmiana nazwy, zmiana semantyki).
• Zasady odrzucania: obsługa okien, nagłówki „Zachód słońca”, zdarzenia zgłoszeniowe.
• Umowy konsumenckie (CDC): Sprawdzenie, czy obecne API spełnia wymagania konkretnych konsumentów.
• Schema directory: Schema Registry/Artifact Registry z historią i zasadami kompatybilności (BACKWARD/FORWARD/FULL).

Bezpieczeństwo i zgodność

Uwierzytelnianie/autoryzacja w ramach umowy (OAuth2/OIDC zakresy, mTLS, JWT).
PII/PCI: maskowanie, formaty tokenizacji, pola ze specjalnymi trybami przechowywania/TTL.
Polityka audytu: wymagane atrybuty ("podmiot", "podmiot", "działanie", "wystąpił _ at", "trace _ id').
Limity: nagłówki limitów stawek, kwoty, rozmiary wiadomości, terminy.

Obserwowalność kontraktu

Korelacja/żądanie-ID: wymagane w specyfikacji.
Katalog błędów - ustalona lista kodów i SLA do rozwiązania.
SLI/SLO: opóźnienie p50/p95, odsetek udanych odpowiedzi, odsetek kompatybilnych zdarzeń, odsetek powtórzeń idempotentnych.

Testowanie i jakość

Testy kontraktowe (dostawca i konsument), schemat różni się w CI, generowanie serwerów makietowych.
Złote próbki: przykłady zapytań/odpowiedzi, oprawy dla e2e.
Wtrysk chaosu/opóźnienia: kontrola czasowa/retray, degradacja rozszerzeń przy oszczędzaniu MGC.

Przykładowe szablony domeny

Płatność (REST + Wydarzenia)

'POST/payments' → '201 Created' z 'payment _ id',' status = authorized '.
Płatność za zdarzenie. autoryzowany. v1 '(бра):' {payment_id, kwota, waluta, metoda, occurred_at} '.
Płatność rozszerzająca. wzbogacony. v1 ': wskaźnik ryzyka, geo, odcisk palca urządzenia.
Błędy: '422' (walidacja), '402' (wymagana płatność), '409' (duplikat).
SLA: zezwolenie ≤ 800 ms p95; zdarzenie jądra ≤ 2c lag p95.

KYC (kolejki gRPC +)

RPC 'Start Verification (user_id)' → 'operation _ id'.
Wydarzenia postępu w temacie 'kyc. status. v1 "(" OCZEKUJĄCE "→" ZATWIERDZONE/ODRZUCONE ").
Umowa określa pola PII, okres trwałości, maskowanie, kody awaryjne.

Audyt (tylko w przypadku zdarzenia)

'audit. zarejestrowane. v1 '(бра):' actor ',' subject ',' action ',' occurred _ at ',' trace _ id'.
Wzbogacenie: IP, urządzenie, geo - osobne zdarzenie/gwint, nie blokuje jądra.

Narzędzia i automatyzacja (przybliżony stos)

Сбека: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтера: Spectral, OpenAPI Diff, Buf (protobuf), Konfluent SR kontroli zgodności.
Менеравий: OpenAPI Generator, Buf/Protoc, GraphQL Codegen, AsyncAPI Generator.
Brama: Kong/Apigee/Azure/GCP GW, wysłannik.
Теста: Pact/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
Rejestracja: Git-directory of schemes + Schema Registry/Artifact Registry.
Dokumentacja: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

Anty-wzory

Kod pierwszy przez przypadek: „MVP najpierw na kontrolerach”, specyfikacja po fakcie, rozbieżność między dokumentacją a zachowaniem.
Swagger-wash: formalny OpenAPI bez prawdziwych zasad (błędy, limity, SLA, wersje).
Zerwanie kompatybilności: usunięte pole/zmieniony typ bez głównej wersji; ponowne użycie znaczników protobufu.
„Gruba” odpowiedź bez paginacji/filtrów; brak idempotencji.
Zabezpieczenie pozaumowne: auth/Scopes są opisane w wiki, ale nie w specyfikacji.

Związek z organizacją procesów

API Guild: powiernicy standardów, zmiany recenzji, szkolenia.
Dokumentacja projektowa: dla każdego API - PRD, ADR (rozwiązania), SLA, matryca ryzyka.
Zarządzanie zmianą: proces RFC, notatki do wydania, przewodniki migracji, odchylenie-linia czasu.
Utwardzone szablony i drogi: generatory ram serwisowych ze specyfikacji (szkielet obsługi, walidacja, rejestrowanie).

Listy kontrolne

Przed rozpoczęciem

• Istnieje PRD i słownik domeny.
• Wybrany styl (REST/gRPC/Event/GraphQL) i format schematu.
• MGC, błędy, SLA/SLO, zdefiniowane zasady idempotence.

W trakcie opracowywania

• Specyfikacja przechodzi liniowce i przegląd.
• Automatyczna generacja SDK/stabilna/Fixture jest skonfigurowana.
• Testy kontraktowe (CDC) są uwzględnione w CI; bloki schematu-diff niezgodne ze wspólnym rynkiem zmiany.

Przed zwolnieniem

• Dokumentacja integratora z przykładami i kodami błędów.
• Kontraktowo obserwowalne: korelacja-id, katalog błędów, deski rozdzielcze SLI.
• Deklaruje się politykę weryfikacyjną i deprecację.

NAJCZĘŚCIEJ ZADAWANE PYTANIA

W jaki sposób protokół po raz pierwszy różni się od interfejsu API?
Często używa się terminów zamiennie. W tym artykule w ramach Protokołu-first podkreślamy rygor umowy i zakres wszystkich stylów (REST/RPC/Events/GraphQL), w tym SLA, bezpieczeństwo i obserwowalność.

Czy to spowolni rozwój?
Start może być trochę dłuższy, ale potem wygrywamy na integracjach, stabilności i równoległych prędkościach rozwoju (auto-generacja, stabilne SDK).

Co zrobić z szybkimi eksperymentami?
Użyj „projektu” wersji schematów (projekt), flagi i piaskownice, ale nie pomijaj linterów i podstawowych zasad kompatybilności.

Razem

Protokół-pierwszy projekt sprawia, że kontrakt jest centrum architektury: koordynujemy zachowanie, naprawiamy schematy, automatyzujemy generowanie i testy, ewoluujemy dodatkowo. Dzięki temu uzyskujemy przewidywalne integracje, dużą prędkość rozwoju i odporność systemów na zmiany skali i poleceń.