協議第一設計

什麼是Protocol-first

協議首先是一種方法，其中在實現之前設計和捕獲組件（服務，客戶端，外部合作夥伴）之間的交互合同。代碼、存儲、基礎架構和文檔受合同約束並自動生成,反之亦然。

與「代碼第一」（API僅是代碼的副產品）不同，協議第一使協議成為主要工件：它擁有域概念，數據模型，狀態，錯誤，等位語義，SLO/SLI甚至版本策略。

為什麼需要它

跨組織接口的一致性和可預測性。
快速爬行（SDK/stabs/客戶端自動發生，單一錯誤和代碼）。
可靠的演變（方案兼容性，合同測試，明確的版本策略）。
產品重點：在編寫代碼之前討論行為、SLA和UX集成。
自動化：CI/CD從單一真相來源收集文物（客戶端，服務器存根，驗證器）。
安全性和合規性：權利，PII掩蓋，回避政策在合同中規定。

方法核心

1.單一真理源（SSOT）-機器可讀規範：

REST: OpenAPI/JSON Schema.

事件和流媒體：AsyncAPI，Avro/JSON Schema。

RPC: Protobuf (gRPC), Thrift, Smithy.

GraphQL： SDL+指令/策略。
2.實施前安排：域詞匯表、錯誤代碼、等效性語義、截止日期、轉發、重復數據消除。
3.自動生成：客戶端/服務器穩定,類型,SDK,合同測試,moki, Postman Collection, Terraform/OpenAPI Gateway config。
4.Governance： linters/policy（名稱、分頁、過濾器、錯誤）,通過API行會進行審查,主要版本的更改咨詢。
5.兼容性：嚴格「僅添加」誹謗驗證,語義驗證,金絲雀/消費者驅動測試。
6.合同級別的可觀察性：相關ID，錯誤模型，延遲預算在協議中規定。

過程的外觀（骨架）

1.啟動：產品簡介→用戶新聞→ API/Protocol PRD（資源/方法/事件，SLA/SLO，錯誤，限制）。
2.建模：規範草稿（OpenAPI/AsyncAPI/Proto）+數據圖，術語詞典。
3.合同和UX集成：有效載荷示例，錯誤合同，狀態圖，轉換規則。

4.Review and governance： linters/standards,討論域不變量,鎖定MGC（最低保修合同）.

5.工件自動發生：SDK, stabs, test fixtures,基礎架構存根（Gateways, IAM scopes）。
6.實施和合同測試：供應商和消費者通過CI兼容性測試。
7.可觀察性和SLO：通過correlation id，error catalog，retrais/taymout預算進行跟蹤。

8.發行和演變： additive-first, deprecation policy, canary, A/B capability flags.

協議和交互樣式

REST/HTTP

標準：資源模型，「GET/POST/PATCH/DELETE」，分區（cursor），過濾器，排序。
字段和方案：JSON方案，格式（「日期」，「uuid」），不變式（regex/enum/min-max）。
錯誤：單一格式（「類型」，「代碼」，「標題」，「詳細信息」，「trace_id」），在HTTP堆棧上映射。
更改控制：ETag/If-Match，POST的等效密鑰，409/422的明確語義。

gRPC/RPC

Protobuf：穩定的標簽編號，「選項」，禁止重新使用已刪除的字段。
Deadlines和合同中的優先事項；穩定狀態（OK, INVALID_ARGUMENT, FAILED_PRECONDITION,等等）。
Streaming：消息順序規範,回傳,最終預告片。

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

AsyncAPI：主題/提要，派對密鑰，重復數據消除密鑰約定，撤回，語義「至少一次」。
事件核心和豐富：共享最小的付費和擴展；轉化為「event_type」/「schema_version」。
相似性：「event_id」，「producer_id」，回避策略和重復數據消除。

GraphQL

SDL作為合同、減排指令、深度和復雜性限制、錯誤合同（錯誤代碼/擴展）。

與體系結構原理集成

Inverse Pyramid/Critical Path First：在規範中分配MGC（強制性最低限度）,擴展通過'?include='/capabilities。

Paved Roads： 一組現成的規範模板（payment, KYC, audit, search, files）+linters.

Gateways＆Service Mesh API：基於合同的策略（限額制，自測量，retries，電路斷路器）。

轉化與進化

Semantic Versioning:

Minor=僅加法字段/通道。
Major=斷開更改（刪除，重命名，更改語義）。
Deprecation Policy：支持窗口、「日落」標題、事件通知。
Consumer-Driven Contracts （CDC）：驗證當前的API是否滿足特定消費者的需求。
方案目錄：具有歷史和兼容性規則（BACKWARD/FORWARD/FULL）的註冊表（方案註冊表/手術註冊表）。

安全性和合規性

作為合同一部分的身份驗證/授權（OAuth2/OIDC scopes, mTLS, JWT claims）。
PII/PCI：掩碼、標記格式、特殊存儲模式/TTL字段。
審核策略：強制屬性（「actor」，「subject」，「action」，「occurred_at」，「trace_id」）。
限制：利率極限頭條，配額，消息大小，截止日期。

合同的可觀察性

Correlation/Request-ID：必須在規範中。
錯誤目錄：固定的代碼列表和消除的SLA。
SLI/SLO：p50/p95延誤，成功響應百分比，兼容事件百分比，等效重播百分比。

測試和質量

合同測試（供應商↔消費者），CI中的schema diff，莫克服務器生成。
Golden Samples：查詢/響應的參考示例,e2e的虛構。
Chaos/latency injection：檢查taymout/retra,在保留MGC的同時降解擴展。

示例域模板

付款（REST+事件）

「POST/payments」（等效密鑰）→ 「201 Created」帶有「payment_id」，「status=authorized」。

Payment事件。authorized.v1` (ядро): `{ payment_id, amount, currency, method, occurred_at }`.

擴展付款。enriched.v1'：風險爭奪、地理、設備指紋。
錯誤：「422」（驗證），「402」（付款要求），「409」（duplicate）。
SLA：授權≤ 800ms p95；內核事件≤ 2 s lag p95。

KYC （gRPC+隊列）

RPC `StartVerification(user_id)` → `operation_id`.

Topic'kyc中的進度事件。status.v1` (`PENDING` → `APPROVED/REJECTED`).

合同規定了PII字段，保質期，掩蓋和因果拒絕代碼。

審計（僅限事件）

`audit.recorded.v1` (ядро): `actor`, `subject`, `action`, `occurred_at`, `trace_id`.

豐富：IP，設備，geo-一個單獨的事件/流，不會阻止內核。

工具和自動化（近似堆棧）

Спеки: 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.

註冊表：計劃目標目錄+計劃註冊表/Artifact註冊表。
文檔：Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer。

反模式

Code-first by accident：「首先是控制器上的MVP」，後事實規範，文檔和行為的差異。
Swagger-wash：沒有實際規則（錯誤，限制，SLA，版本）的正式OpenAPI。
取消兼容性：刪除字段/更改類型,沒有主要版本；重新使用protobuf標簽。
「厚」響應沒有分段/過濾器；缺乏相容性。
非合同證券：auth/Scopes在wiki中描述,但不在BOM中描述。

與流程組織的關系

API Guild：標準受托人，變革之聲，培訓。
設計文檔：每個API均為PRD、ADR（解決方案）、SLA、風險矩陣。
更改管理：RFC流程、發布註釋、遷移海德、中斷時間線。
Paved Road＆Templates：來自規範的服務框架發生器（handler骨架，驗證，生成）。

支票清單

啟動前

有PRD和域詞匯表。
選擇樣式（REST/gRPC/事件/GraphQL）和模式格式。
由MGC定義，錯誤，SLA/SLO，冪等規則。

在開發中

規範通過linters和審查。
SDK/stabs/fixtur自動生成已配置。
合同測試（CDC）包含在CI中；schema-diff阻止不兼容的更改。

發布前

具有示例和錯誤代碼的集成商文檔。
合同可觀察性：correlation-id, error catalog, dashbords SLI。
已宣布效忠和棄權政策。

FAQ

協議第一與API第一有何不同?

這些術語通常用作同義詞。在Protocol-first之下的這篇文章中,我們強調合同的嚴格性和所有樣式（REST/RPC/Events/GraphQL）的覆蓋範圍,包括SLA、安全性和可觀察性。

這種發展不會減緩嗎？
啟動時間可能稍長一些，但隨後在並行開發（自動發生，穩定SDK）的積分，穩定性和速度上獲勝。

快速實驗該怎麼辦？
使用圖形（草稿）、feature flags和沙盒的「草稿」版本,但不要錯過林特機和基本兼容性規則。

底線

協議第一設計使合同成為體系結構的中心：協調行為，固定電路，自動生成和測試，加法演變。結果，我們獲得了可預測的集成，高開發速度以及系統對規模和團隊變化的抵抗力。