---
name: api-design
when: 'API设计, 接口设计, 新建接口, 接口定义, RESTful, API规范, 接口契约, 请求参数, 响应格式'
scope:
  - backend
products:
  - '*'
id: ka-pattern-api-design
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - API设计
  - 接口设计
  - 新建接口
  - 接口定义
  - RESTful
  - API规范
  - 接口契约
  - 请求参数
  - 响应格式
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 业务输入参数超过 3 个必须封装为 Request 对象，禁止平铺离散 query/path/body 参数
- 业务输出超过 1 个返回值必须封装为 Response 对象，禁止多个并列标量字段或 Map 作为正式契约
- 列表查询必须定义：过滤条件、分页参数、排序规则、默认排序
- 批量接口必须定义：每批上限、部分成功策略、失败详情返回格式
- 删除操作必须明确声明：软删除/硬删除/级联删除/逻辑失效、可恢复性、前置校验、关联数据影响
- 需要幂等或去重的接口必须显式定义幂等键或去重规则
- 导出复用列表筛选条件时必须显式声明，列表和导出不得使用不同筛选语义
- API 必须包含版本号路径前缀（如 /api/v1/），破坏性变更递增主版本号
- 写接口必须有幂等设计（使用 Idempotency-Key 或业务唯一键），防止重复提交
- API 必须实现限流保护（Rate Limiting），响应头包含剩余配额信息
- 接口文档必须使用 OpenAPI/Swagger 自动生成，禁止手工维护独立文档
- 批量操作接口必须限制单次数量（如 ≤ 100），防止超时和资源耗尽

## 验收项
- [AC-01] 多参数接口使用 Request/Response 对象封装
- [AC-02] 列表接口有分页和排序定义
- [AC-03] 批量接口有上限和部分成功策略
- [AC-04] 删除接口声明了删除语义和可恢复性
- [AC-05] API 有版本号前缀
- [AC-06] 写接口幂等设计
- [AC-07] 有限流保护
- [AC-08] 文档自动生成
