---
name: contract-compatibility
when: '接口变更, API变更, 合同变更, 接口兼容, 向后兼容, 废弃接口, 版本迁移'
scope:
  - backend
products:
  - '*'
id: ka-pattern-contract-compatibility
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 接口变更
  - API变更
  - 合同变更
  - 接口兼容
  - 向后兼容
  - 废弃接口
  - 版本迁移
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- API 契约是前后端对齐的唯一信源，每次变更必须有 diff 记录和版本说明
- 变更必须前向兼容，破坏性变更必须标记 deprecated 并提供至少一个完整版本的过渡期
- 新增必填请求字段、删除字段、改变字段类型、修改路径、改变错误码含义均为破坏性变更，需要废弃流程
- 每次契约变更必须同步更新接口文档和 schema 定义
- 禁止前后端口头约定替代正式契约变更
- 新增可选字段必须设默认值，保证旧客户端兼容
- 枚举类型新增值必须评估对所有消费方的影响
- 删除字段必须分阶段：先标记 @Deprecated → 确认无消费方 → 下版本移除
- 数据库字段变更必须兼容旧代码（先加新字段 → 迁移数据 → 再删旧字段）
- API 路径变更必须保留旧路径并重定向，给予消费方充足迁移时间

## 验收项
- [AC-01] 接口变更有 diff 记录
- [AC-02] 破坏性变更有 deprecated 过渡期
- [AC-03] 文档与 schema 同步更新
- [AC-04] 无口头约定的非正式变更
- [AC-05] 新字段有默认值
- [AC-06] 删除字段分阶段进行
- [AC-07] 数据库变更兼容旧代码
