API兼容性和更新

1）互操作性基本原则

Additive-first：添加新字段而不破坏旧字段（新可选字段/端点,新的enum值）。
稳定的合同："规范中承诺的东西既有效又有效"；行为记录在桉。
Backward> Forward：向后兼容性优先级；通过tolerant阅读器允许前进。
文档是主要的：唯一的真相来源是注册表中的架构版本（OpenAPI/AsyncAPI/Proto）。
显而易见的演变：破裂-仅通过新的主要版本和迁移指南。

2）变更分类法

2.1兼容（MINOR/PATCH）

添加可选的字段/头部、新的尾部、带有默认值的查询参数。
增加限制（"page_size"，TTL），在不更改代码/语义的情况下澄清错误。
如果客户端忽略了"陌生人"（tolerant-reader）,则添加enum值。

2.2模棱两可（Behavioral）

更改违约，排序顺序，精细的时间表，配额-可以"打破"业务逻辑。需要RFC+公告和金丝雀。

2.3折断（MAJOR）

重命名/删除字段，更改类型/格式，替换错误代码，反向合同/身份验证方案不兼容。

3）考试政策

策略："path versioning"（"/v1"，"/v2"）。
小调/补丁："添加，不要打破"。
过时的标题（dop.）："X-API-Version-Date"，用于温和的渐进式更改。
媒体类型（opz。）: `Accept: application/vnd.acme.v1+json'用于细颗粒。

4）去除和日落

4.1通讯头条

Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"

4.2输出顺序

1.在门户/通讯/SDK发布注释中宣布。
2.警告窗口≥ 90-180天。
3.Dashboard adoption中的状态。
4.在日落之后-410 Gone或"read-only"模式，如果同意的话。

5）迁移和共享版本

过渡时期的双写作/双读取和报告对账。
适配器（临时）：旧付费的网关转换→新方案；适配器的寿命受到限制。
SDK帮助：支持两个版本的版本,带有解密警告（每个过程1次）。
Fich-flags： 在键/tenant列表中包含新的语义。

6）背面和前方兼容性

6.1 Backward（旧客户端↔新服务器）

不要更改类型/强制格式。
新字段-仅可选。
错误-以前的"error_code"、新代码添加、不替换。

6.2 Forward（新客户端↔旧服务器）

通过"OPTIONS"/"/versions"检查能力（机会）。
格雷斯行为：客户必须容忍缺席的犯规。

7）合同和自动检查

注册：保留方案的版本；公关部门→报告"破解/不破解"。
Linter：名称/类型,等效性,分期,稳定代码。
CDC（消费者驱动合同）：供应商的CI（Pact和类似物）中的集成商测试。
盖特：公关在没有"专业大满贯"/RFC的情况下被锁定。

yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml

8）金丝雀发行和回程

金丝雀：10% → 25% → 50% → 100%的流量；SLO恶化时的自动回滚（5xx/latency/429）。
Beta密钥：通过allowlist访问新版本。
释放冻结：在燃烧错误预算时。
接受分析：新版本的流量/客户比例,迁移时间。

9）详细兼容性： 错误，分离，相容性

9.1个错误

不要更改现有脚本中的HTTP状态。
'error_code'-稳定；仅添加新代码。
"application/problem+json"是单一格式。

9.2分离

如果支持旧的"offset/limit"，则切换到cursor/keyset=MINOR。
记录"（updated_at,id）"排序和光标稳定性。

9.3 Idempotency

对于写作-冲突中的"Idempotency-Key"+"409 IDEMP_REPLAY'。
迁移不应改变幂等语义。

10）网关转型（适当时）

Map v1→v2字段，规范错误，转换日期/货币格式。
Guardrails：转换透明且可逻辑；不要隐藏断裂，而是用作限时桥梁。

11）通讯和门户

Changelog с датами (`added/changed/deprecated/removed/fixed`).

版本卡：状态（beta/GA/deprecated），日落日期，指向海德的链接。

通知的Webhooks： 'deprecation。notice`, `version.released`, `plan.change`.

SDK发布注释+门户网站上的横幅。

12）成功指标

Adoption rate v2（按请求/客户端）。
Backward-compat incidents（"折纸"）。
发行前/发行后的Error mix（4xx/5xx/429份额）。
时间到中位数。
支持负载（tikets/ned）。
Cost-to-Serve（每个呼叫的基础架构成本）。

13）模板和示例

13.1版本和删除标题

X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"

13.2版本策略（YAML片段）

yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]

13.3 OpenAPI：兼容字段添加

yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive

14）发行支票清单（MINOR/MAJOR）

MINOR

• DIFF：非突破，linter绿色
• 文档/SDK更新（示例/编解码器）
• 金丝雀+在SLO上自动回滚
• Comm Plan，门户网站页面
• Dashbords adoption和错误

MAJOR

• RFC/ADR、日落日期和窗口≥90 -180天
• v1↔v2桥（gateway）和迁移指南
• 双重写作/阅读和对账
• 具有两个API+警告的SDK
• 具有关键集成商的飞行员

15）实施计划（3次迭代）

1.基础（2周）：

CI中的Registry电路，lint和auto-diff；互操作性政策；标题"Deprecation/Sunset"。

2.托管版本（3-4周）：

金丝雀，幻灯片，SLO-Alerta；版本门户；支持2个分支的SDK版本。

3.自动化和规模（连续）：

CI中的消费者疾病预防控制中心测试，日落趋势预测，自动符号化和提醒。

16）迷你常见问题

可以在没有专业的情况下更改字段类型吗?

没有。甚至"stroka→chislo"都是断裂。输入新字段,旧字段为deprecate。

Enum： 可以添加值吗?

是的，如果客户是tolerant读者。否则-首先是警报和beta。

多少保留旧版本?

到目前为止，adoption是新的≥95％，并且经过了消除窗口。在政策中记录最后期限。

底线

API兼容性是一门学科：additive方法，正式方案和difs，金丝雀版本，清晰的解密和管理的迁移。稳固变更策略，自动化验证和通信，测量适应-您的更新将停止破坏客户，并且演变速度将增长而不会失去可靠性。