编程开发 编辑复核
API 契约设计与边界
从用户任务、资源模型和兼容性约束设计清晰的请求、响应、错误和版本契约。
PROMPT WORKBENCH
复制后替换变量
保留结构，先填真实信息，再把结果交给模型运行。
你是一名API 设计评审员。请设计一个可被前后端共同实现和测试的 API 契约，保留安全、权限、分页、幂等和错误边界。
先区分已知事实、合理假设和待核验信息；没有依据的内容写“待验证”，不要为了完整而猜测。
请按以下结构输出：
1. 资源、用户任务和权限边界
2. 请求参数、响应字段和示例
3. 校验、错误码、重试和幂等规则
4. 分页、排序、过滤和版本兼容
5. 验收用例、日志字段和未决问题
输入变量：
- 用户任务（{{job}}）：描述用户要完成的业务动作。
- 已有接口（{{existing_api}}）：提供旧接口、字段和调用方约束。
- 数据模型（{{data_model}}）：说明资源字段、状态和关系。
- 安全要求（{{security}}）：说明认证、授权、速率和敏感字段。
约束：保留用户的真实语气和业务边界；把事实、推断与建议分开；涉及日期、价格、版本、法规或安全的内容写明来源和采集时间。HOW TO USE
使用说明
- 先与调用方确认字段和错误语义，再写 OpenAPI 或实现。
- 契约变更需要添加兼容性测试和迁移窗口。
WHEN IT FITS
适用判断
适合这些情况
- 接口还在设计阶段，可以自由调整结构。
- 需要先和调用方对齐语义，再动手实现。
- 要把边界情况（分页、排序、错误）一次想清楚。
换个做法更好
- 接口已经上线：用《API 契约设计与兼容性检查》评估改动风险。
- 接口只是内部临时调用：设计成本高于收益。
- 已有明确的行业规范可循：照着规范做比重新设计好。
FAILURE MODES
常见翻车与修正
- 设计得很通用，加了一堆用不上的可选参数。
通用性是后续负担。要求每个字段都说明当前的实际使用场景，说不出的删掉。
- 错误处理只写了「返回错误码」，没有具体设计。
要求列出所有错误场景、对应的状态码、错误体结构和调用方的处理建议。
- 分页、排序、幂等这些边界问题没考虑。
在输入里明确要求覆盖：分页方式、排序稳定性、重复请求的幂等保证、并发修改的冲突处理。
ACCEPTANCE
怎么判断输出合格
- 每个字段都有当前的实际使用场景，没有预留的空字段。
- 错误场景、状态码和错误体结构都定义清楚。
- 分页、排序、幂等和并发冲突都有明确方案。
- 给出了完整的请求响应示例，调用方能直接对照。
SAFETY BOUNDARY
使用边界
- 公开接口一旦发布就很难改，字段命名和结构在定稿前多花时间，比上线后兼容成本低得多。
- 模型不了解你的鉴权和限流体系，安全相关的设计要由熟悉现有架构的人确认。