Protokoll-erstes Design

Was ist Protocol-first

Protocol-first ist ein Ansatz, bei dem ein Interaktionsvertrag zwischen Komponenten (Services, Kunden, externe Partner) vor der Implementierung entworfen und festgelegt wird. Code, Speicher, Infrastruktur und Dokumentation unterliegen einem Vertrag und werden daraus automatisch generiert und nicht umgekehrt.

Im Gegensatz zu „code-first“, wo die API nur ein Nebenprodukt des Codes ist, macht Protocol-first das Protokoll zum primären Artefakt: Es besitzt Domänenkonzepte, Datenmodelle, Status, Fehler, Semantik der Idempotenz, SLO/SLI und sogar Versionsrichtlinien.

Warum es notwendig ist

Konsistenz und Vorhersehbarkeit der Schnittstellen im gesamten Unternehmen.
Schnelles Onboarding (automatische Generierung von SDKs/Stabs/Clients, einheitliche Fehler und Codes).
Robuste Entwicklung (Interoperabilität der Systeme, Vertragstests, klare Versionsrichtlinien).
Produktschwerpunkt: Wir besprechen das Verhalten, SLA und UX der Integration, bevor wir den Code schreiben.
Automatisierung: CI/CD sammelt Artefakte (Clients, Server-Stubs, Validatoren) aus einer einzigen Quelle der Wahrheit.
Sicherheit und Compliance: Rechte, PII-Maskierung, Retentionsrichtlinien sind im Vertrag verankert.

Kern des Ansatzes

1. Single Source of Truth (SSOT) - Maschinenlesbare Spezifikationen:

REST: OpenAPI/JSON Schema.
Events und Streaming: AsyncAPI, Avro/JSON Schema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: SDL + Richtlinien/Richtlinien.
2. Absprachen vor der Umsetzung: Domain-Glossar, Fehlercodes, Semantik der Idempotenz, Deadlines, Retrays, Deduplizierung.
3. Autogenerierung: Client/Server-Stacks, Typen, SDKs, Vertragstests, moki, Postman-Sammlungen, Terraform/OpenAPI Gateway-config.
4. Governance: Linters/Policies (Namensgebung, Paginierung, Filter, Fehler), Review via API-Gilde, Change-Advisory für Major-Versionen.
5. Kompatibilität: strenge „additive-only“ -Prüfung von Diffamierungen, semantische Versionierung, kanarische/consumer-getriebene Tests.
6. Beobachtbarkeit auf Vertragsebene: Korrelations-IDs, Fehlermodelle, Verzögerungsbudgets sind im Protokoll festgehalten.

Wie der Prozess aussieht (Skelett)

1. Initiation: Produktbrief → User Journeys → API/Protocol PRD (Ressourcen/Methoden/Events, SLA/SLO, Fehler, Limits).
2. Modellierung: Spezifikationsentwurf (OpenAPI/AsyncAPI/Proto) + Datenschemata, Begriffswörterbuch.
3. Verträge und UX-Integration: Nutzlastbeispiele, Fehlerverträge, Statuskarten, Versionsregeln.
4. Revue und Governance: Linters/Standards, Diskussion über Domain-Invarianten, Lock-in MGC (Mindestgarantievertrag).
5. Autogenerierung von Artefakten: SDKs, Stacks, Test-Fixtures, Infrastruktur-Stubs (Gateways, IAM-Scopes).
6. Durchführung und Vertragstests: Anbieter und Verbraucher werden im CI einer Kompatibilitätsprüfung unterzogen.
7. Beobachtbarkeit und SLO: Nachverfolgung nach correlation-id, Fehlerkatalog, Retray-/Timeout-Budgets.
8. Releases und Evolution: additive-first, deprecation policy, canary, A/B capability flags.

Protokolle und Interaktionsstile

REST/HTTP

Standards: Ressourcenmodell, 'GET/POST/PATCH/DELETE', Pagination (Cursor), Filter, Sortierung.
Felder und Schemata: JSON Schema, Formate ('date-time', 'uuid'), Invarianten (regex/enum/min-max).
Fehler: einheitliches Format ('type', 'code', 'title', 'detail', 'trace _ id'), Mapping auf HTTP-Stacks.
Änderungskontrolle: ETag/If-Match, idempotente Schlüssel für POST, explizite Semantik 409/422.

gRPC/RPC

Protobuf: stabile Tag-Nummerierung, 'optional', Verbot der Wiederverwendung gelöschter Felder.
Deadlines und Prioritäten im Vertrag; stabile Zustände (OK, INVALID_ARGUMENT, FAILED_PRECONDITION, etc.).
Streaming: Angabe der Nachrichtenreihenfolge, Backpressure, finale Trailer.

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

AsyncAPI: Themen/Kanäle, Partitionierungsschlüssel, Deduplizierungsschlüsselvereinbarungen, Retentionen, Genau-Einmal-Semantik vs „mindestens einmal“.
Event-Core und Anreicherung: teilen Sie die minimale payload und Erweiterungen; versionieren Sie' event _ type '/' schema _ version'.
Idempotenz: 'event _ id', 'producer _ id', Retraising- und Deduplizierungspolitik.

GraphQL

SDL als Vertrag, Richtlinien für Deprecate, Tiefen- und Komplexitätsgrenzen, Fehlervertrag (error codes/extensions).

Integration mit architektonischen Prinzipien

Inverse Pyramid/Critical Path First: in der Spezifikation MGC (obligatorisches Minimum) hervorheben, Erweiterungen über'? include = '/capabilities.
Paved Roads: eine Reihe vorgefertigter Spezifikationsvorlagen (Payment, KYC, Audit, Search, Files) + Linters.
Gateway & Service Mesh API: Vertragsbasierte Richtlinien (Rate-Limits, Auth-Scopes, Retries, Circuit-Breakers).

Versionierung und Evolution

• Minor = nur additive Felder/Kanäle.
• Major = brechende Änderungen (Löschungen, Umbenennung, Änderung der Semantik).
• Deprecation Policy: Supportfenster, 'Sunset' -Überschriften, Ereignisbenachrichtigungen.
• Consumer-Driven Contracts (CDC): Überprüfen Sie, ob die aktuelle API bestimmte Verbraucher zufrieden stellt.
• Scheme Directory: Registry (Schema Registry/Artifact Registry) mit Historie und Kompatibilitätsregeln (BACKWARD/FORWARD/FULL).

Sicherheit und Compliance

Authentifizierung/Autorisierung als Vertragsbestandteil (OAuth2/OIDC scopes, mTLS, JWT claims).
PII/PCI: Maskierung, Tokenisierungsformate, Felder mit speziellen Speichermodi/TTL.
Überwachungsrichtlinien: erforderliche Attribute ('actor', 'subject', 'action', 'occurred _ at', 'trace _ id').
Limits: Rate Limit Header, Kontingente, Nachrichtengrößen, Deadlines.

Vertragliche Beobachtbarkeit

Correlation/Request-ID: erforderlich in der Spezifikation.
Error Catalog: Eine feste Liste von Codes und SLAs zum Entfernen.
SLI/SLO: p50/p95 Latenz, Anteil erfolgreicher Antworten, Anteil kompatibler Ereignisse, Anteil idempotenter Wiederholungen.

Prüfung und Qualität

Vertragstests (Lieferant ↔ Verbraucher), Schema-Diff in CI, Generierung von Mock-Servern.
Goldene Beispiele: Referenzbeispiele für Anfragen/Antworten, Fiktionen für e2e.
Chaos/Latenzinjektion: Überprüfung von Timeouts/Retrays, Degradierung von Erweiterungen unter Beibehaltung des MGC.

Beispielhafte Domänenvorlagen

Zahlung (REST + Ereignisse)

„POST/payments“ (idempotent key) → „201 Created“ mit „payment _ id“, „status = authorized“.
Das Ereignis' Zahlung. authorized. v1` (ядро): `{ payment_id, amount, currency, method, occurred_at }`.
Erweiterung 'payment. enriched. v1': Risiko-Score, Geo, Device-Fingerprint.
Fehler: '422' (Validierung), '402' (Zahlung erforderlich), '409' (Duplicate).
SLA: Autorisierung ≤ 800ms p95; Kernelereignis ≤ 2c lag p95.

KYC (gRPC + Warteschlangen)

RPC `StartVerification(user_id)` → `operation_id`.
Ereignisse des Fortschritts in der Topic 'kyc. status. v1` (`PENDING` → `APPROVED/REJECTED`).
Der Vertrag schreibt PII-Felder, Speicherdauer, Maskierung, kausale Fehlercodes vor.

Überwachung (nur Ereignis)

`audit. recorded. v1` (ядро): `actor`, `subject`, `action`, `occurred_at`, `trace_id`.
Anreicherung: IP, Device, Geo - separates Ereignis/Thread, blockiert den Kernel nicht.

Tools und Automatisierung (Beispielstack)

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: Spectral, OpenAPI Diff, Buf (protobuf), Confluent SR compatibility checks.
Генерация: OpenAPI Generator, Buf/Protoc, GraphQL Codegen, AsyncAPI Generator.
Gateway: Kong/Apigee/Azure/GCP GW, Envoy.
Тесты: Pact/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
Register: Git-Verzeichnis der Schemata + Schema Registry/Artifact Registry.
Dokumentation: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

Anti-Muster

Code-first by accident: „first MVP on controllers“, Spezifikation von Post-Factual, Diskrepanz zwischen Dokumentation und Verhalten.
Swagger-wash: formale OpenAPI ohne echte Regeln (Fehler, Limits, SLAs, Versionen).
Kompatibilitätsverlust: Feld gelöscht/Typ ohne Hauptversion geändert; Neuverwendung von Protobuf-Tags.
„Dicke“ Antwort ohne Pagination/Filter; Mangel an Idempotenz.
Securities out of contract: auth/Scopes sind im Wiki beschrieben, aber nicht in der Spezifikation.

Beziehung zur Prozessorganisation

API Guild: Treuhänder von Standards, Reviews von Änderungen, Schulungen.
Design Docs: für jede API - PRD, ADR (Lösungen), SLA, Risikomatrix.
Change Management: RFC-Prozess, Release Notes, Migrations-Guides, Deprecation-Timeline.
Paved Road & Templates: Service-Framework-Generatoren aus der Spezifikation (Handler-Skelett, Validierung, Protokollierung).

Checklisten

Vor dem Start

• Es gibt ein PRD und ein Domain Glossar.
• Stil (REST/gRPC/Event/GraphQL) und Schema-Format ausgewählt.
• Definierte MGC, Fehler, SLA/SLO, Idempotenzregeln.

In Entwicklung

• Spezifikation durchläuft Linters und Überprüfung.
• Die Auto-Generierung von SDK/Stabs/Fixturen ist eingerichtet.
• Contract Tests (CDC) sind im CI enthalten. schema-diff blockiert inkompatible Änderungen.

Vor der Veröffentlichung

• Dokumentation für Integratoren mit Beispielen und Fehlercodes.
• Contract observability: correlation-id, error catalog, SLI dashboards.
• Versions- und Deprecationspolitik angekündigt.

FAQ

Wie unterscheidet sich Protocol-first von API-first?
Häufig werden die Begriffe synonym verwendet. In diesem Artikel unter Protocol-first betonen wir die Strenge des Vertrags und die Abdeckung aller Stile (REST/RPC/Events/GraphQL), einschließlich SLA, Sicherheit und Beobachtbarkeit.

Bremst das die Entwicklung?
Der Start kann etwas länger dauern, aber dann profitieren wir von den Integrationen, der Stabilität und den Geschwindigkeiten der parallelen Entwicklung (Autogenerierung, stabile SDKs).

Was tun mit schnellen Experimenten?
Verwenden Sie „Draft“ -Versionen von Schemas (Entwurf), Feature Flags und Sandboxes, überspringen Sie jedoch nicht die Linter- und grundlegenden Kompatibilitätsregeln.

Summe

Das Protocol-First-Design macht den Vertrag zum Zentrum der Architektur: Wir harmonisieren das Verhalten, fixieren Schaltkreise, automatisieren Generierung und Tests, entwickeln additiv. Das Ergebnis sind vorhersehbare Integrationen, eine hohe Entwicklungsgeschwindigkeit und die Widerstandsfähigkeit von Systemen gegenüber Skalen- und Teamänderungen.