API 设计边界
接口是协作契约。
设计时先问边界，再堆字段——边界清楚，联调夜会短很多。
1. 设计前三问
- 这个接口负责什么？ 核心资源/用例是什么
- 不负责什么？ 哪些事应归别的模块
- 失败时调用方下一步是什么？ 重试、改参数、还是申请权限
写不清三问，先不要开工实现。
2. 资源与操作
- 路径表达资源，方法表达动作（REST 场景）
- 避免一个接口既查询、又编排长流程、还偷偷改无关表
- 管理端与用户端入口若权限模型不同，不要混用同一套「隐式假定」
3. 错误语义
| 类型 | 期望 |
|---|---|
| 参数问题 | 明确字段与原因，可修复后重试 |
| 权限问题 | 与「资源不存在」策略一致且安全；不泄露敏感存在性（按产品约定） |
| 业务拒绝 | 稳定错误码/文案，可被调用方分支处理 |
| 系统故障 | 可追踪（请求 ID）；可说明是否可重试 |
避免「一律 500」或「成功里塞失败」。
4. 幂等与重试
- 写操作默认考虑超时重试（客户端、网关、人工）
- 支付、库存、加款等路径：幂等键覆盖所有入口（含管理端）
- 超时 ≠ 失败；需要查询补偿时写清查询接口
5. 版本与兼容
- 破坏性变更走新版本或显式兼容期
- 废弃字段：文档标明废弃时间与替代方案
- 枚举扩展：调用方应容忍未知枚举（向前兼容）
6. 契约优先（推荐）
- 先冻结/评审草案（路径、字段、错误）
- 再实现
- 示例请求/响应随文档更新
- 变更走评审，调用方可知
7. 评审检查表
- 三问写清
- 权限模型明确
- 错误可分支
- 幂等/重试策略明确
- 分页/过滤/排序有上限
- 敏感字段不落日志
- 与 完成定义 中 API 项一致
标准化 API 服务说明另见 RESTful API 开发服务。