API验证策略

为什么需要转学

API的变化速度快于客户端。转化允许在没有积分故障的情况下释放幻影和编辑错误，设置更改的仪式，并使进化可预测。关键：默认的加法更改,主要只用于切片,自动兼容性检查和深思熟虑的日落策略。

基本原则

1.增量第一：新的可选字段/方法/事件-ok；删除和改变意义是专业。
2.MGC（最低保修合同）稳定；富集-通过capabilities/'?include='。
3.Tolerant reader：客户会忽略未知字段,并正确地体验enum扩展。
4.Semantic Versioning: `MAJOR.MINOR.PATCH'用于工件，SDK和事件。
5.Automate： schema-diff、linters和CDC测试阻止断裂变化。

在何处存储版本（寻址机制）

REST/HTTP

URI版本：'/v1/orders' →简单地路由，在网关中方便。减-"掩盖"表示的演变。
介质/标题：'接受：application/vnd。example.orders.v1+json'-精确的格式控制；更难借用。
Query版本：'?api-version=1'-对A/B很方便,但很容易在腰包/logs中丢失。
建议：主要线路的URI+feature/capability flags和次要扩展的content-Nacacisation。

gRPC / Protobuf

软件包/服务："package payments。v1;服务PaymentsV1；'是显式行。
标签编号不变；已删除的标签不能重新使用。
新领域是"选择性"；突破→新的".v2"。

GraphQL

URL中没有显式专业的方案。通过@deprecated和迁移窗口演变；"真正"的专业是新的终端电路。
控制complexity/depth是合同的一部分。

Event-driven (Kafka/NATS/Pulsar)

事件名称：'payment。authorized.v1'是类型中的版本。
具有兼容性模式（BACKWARD/FORWARD/FULL）的电路注册表（Avro/JSON 计划/Protobuf）。
Major →过渡时期的双演员"v1"和"v2"。

版本模型和更改策略

Semantic Versioning

MAJOR-破解更改：删除/重命名字段,更改分期密钥,不同的状态含义,收紧验证。
MINOR-可加性：新的可选字段/端点/事件，tolerant-reader中的新烯素值。
PATCH-不更改合同和语义的修补程序。

Deprecation & Sunset

在HTTP中，标题为"Sunset"，"Deprecation"；在事件中-单独的'.deprecation.notice`.

标记过时（"Deprecated：true"，"@deprecated"），发布日落日期，替代品和迁移海德。
运行使用遥测以做出删除决定。

Version Style策略

REST

在/v1 ，/v2上的主要线。
MINOR：方案扩展，'？fields='，'？include='；安全的enum扩展。
ETag/If-Match和等效开机自检以实现无切片一致性。
错误是稳定的格式（"类型"，"代码"，"trace_id"）。

gRPC

介绍新的服务/方法： 'PaymentsV2.Capture`.

错误状态和最后期限语义是合同的一部分；更改→新方法/服务。
流媒体：商定消息顺序，不要换成次要。

GraphQL

自由添加字段和类型；删除-通过'@deprecated'+迁移窗口；大型重新设计→新方案（'/graphql-v2'）。
内窥镜和描述是客户迁移的必经之路。

Events

Core vs enriched：核心稳定，富集生活在附近，分开旋转。
分期密钥在主要线路内不变。
主要迁移是"dual-emit"+投影/消费者的迁移。

Negotation和能力标志

Capabilities：客户端发送"X-Capabilities：risk_score,price_v2'；服务器以高级视图响应。
部分响应的Prefer（HTTP）和"hints"。
在套接字/流中-带有支持扩展列表的手写消息。

大版本发布无痛苦

1.RFC/ADR：为什么需要一个主要的风险矩阵。
2.双跑：并行启动"v1"和"v2"（双重事件发布，两条网关路线，交通镜像）。
3.迁移适配器：用于重型客户的代理/转换器"v1↔v2"。
4.金丝雀：按客户组/拓扑/标签在gateway。
5.日落计划：日期，通讯，展位，测试数据，使用监控。

平台和基础设施的作用

Gateway/Service Mesh API： 按版本、标题、路径进行路由；rate-limit и auth per-version.

CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).

Schema Registry＆Catalog：具有诽谤历史的孢子/方案的真相来源。

Observability： 该版本必须包含在logi/traces/mindics.

版本测试

公关中的Schema-diff：阻断。
Consumer-Driven Contracts：对提供商进行实际消费者合同审查。
金色样本：版本的参考响应。
E2E-Canary：比较版本p95/p99，错误和时间间隔。
Replay for event：投影在v2上重新定位,没有差异。

数据和数据库迁移

对于REST/gRPC：DB迁移是通过expand-and-ontract进行协调的（添加专栏→开始写作→切换阅读→旧版）。
对于事件：双配音和用户迁移；有时-对新投影重新播放日志。
不要做"大爆炸"--用回滚击中步骤。

与安全的关系

逐个版本：v1/v2的单个OIDC-scopes/角色。
秘密/令牌是合同的一部分；他们的变化=主要。
PII/PCI-不必要地扩展付费负载；新字段-特权最小。

反模式

Swagger-wash：更新了规范,服务器没有（反之亦然）。
重新使用protobuf标签是一种安静的数据破坏。
没有专业的enum意义改变。
全球"/v2""为了化妆品"：没有断裂事实的版本。
忘了日落/使用指标：无法安全地删除旧版本。
一个用于不同专业的一般拓扑：顺序和键的混合。

发行前的支票清单

• 更改是加法的，或者准备了单独的大线。
• Linters和schema-diff绿色（破裂不会脱落）。
• 更新了SDK/示例/文档以及兼容性脚注。
• 在客户端中启用tolerant reader；enum-fallback测试。
• 对于专业-双跑计划，适配器，金丝雀，日落日期和通讯。
• Metrics/logs/traces包含一个版本并对其进行细分。
• 有一个摊位和一个金色套件来比较v1↔v2。
• 对于事件-BACKWARD/FULL模式下的电路注册表,分期密钥保持不变。

模式示例

REST (URI + negotiation)

路线： '/api/v2/orders/{id}'

Заголовок: `Prefer: include=items,customer`, `X-Capabilities: risk_score`

Deprecation: `Sunset: 2026-06-30`, `Link: ;rel="alternate"`

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

Events

`payment.captured.v2'（内核）和'payment。enriched.v2'（详细信息）。
制片人的过渡期是"v1"和"v2"。

FAQ

什么时候确切需要'/v2'？
当不变式/语义发生变化时，删除字段/方法，更改标识符格式，分期密钥，SLA/计时器，以使客户端崩溃。

可以在REST中没有明确版本生活吗?

仅适用于小型系统。对于外部积分-更明显的专业线。

保留过时版本的时间是多少?

取决于生态系统。对于外部合作伙伴，通常需要6-12个月的早期通知和金丝雀。

事件转换与API有何不同?

事件是唯一的；新语义=新类型".v2"和dual-emit。分期付款的关键是合同的一部分。

结果

转化策略是一个过程和工具：默认的加法演变，清晰的大线，能力失调，双奔跑和日落。加上自动兼容性检查、使用遥测和文档纪律-而且您的API将快速发展，没有"夜间迁移"和客户意外下降。