---
name: interface-contract
when: '接口文档, API文档, 接口契约, Swagger, 接口定义, 接口规范, 字段定义, 接口评审'
scope:
  - backend
products:
  - '*'
id: ka-pattern-interface-contract
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 接口文档
  - API文档
  - 接口契约
  - Swagger
  - 接口定义
  - 接口规范
  - 字段定义
  - 接口评审
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 每个接口必须有完整定义：路径、方法、认证、请求、响应、错误码
- 页面交互与接口必须有映射表确保一一对应
- 每个接口至少定义：校验失败、权限不足、业务异常、资源不存在四种错误
- 所有枚举字段必须列出完整值集和含义，禁止无枚举定义的 type/status/flag 字段
- 每个接口必须显式声明幂等性和认证属性
- 接口契约中鉴权要求必须能回链到角色与权限模型
- 接口文档必须与代码同步更新，禁止文档与实现不一致
- 破坏性变更必须通过版本号隔离（如 /v1/ → /v2/），保证旧客户端兼容
- 接口响应时间必须有 SLA 约定（如 P99 < 500ms），超时触发告警
- 接口必须定义错误码体系（业务错误码 + HTTP 状态码），客户端可区分处理
- 接口变更必须通知所有消费方，并给予充足的迁移时间

## 验收项
- [AC-01] 接口文档包含完整定义（路径/方法/认证/请求/响应/错误）
- [AC-02] 页面交互与接口有映射表
- [AC-03] 枚举字段有完整值集定义
- [AC-04] 接口声明了幂等性和认证属性
- [AC-05] 文档与代码同步
- [AC-06] 破坏性变更版本隔离
- [AC-07] 有 SLA 约定和监控
- [AC-08] 错误码体系完整
