协议第一设计

什么是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和沙盒的"草稿"版本,但不要错过林特机和基本兼容性规则。

底线

协议第一设计使合同成为体系结构的中心：协调行为，固定电路，自动生成和测试，加法演变。结果，我们获得了可预测的集成，高开发速度以及系统对规模和团队变化的抵抗力。