首页/AI 提示词库/编程开发/接口设计评审

接口设计评审

⌨ 编程开发 适配:通用(GPT / 豆包 / 通义 / Kimi)难度:进阶 4 个变量一键复制
使用说明

从资源建模到错误码、幂等与分页,输出一份可评审的 REST 接口设计。

新模块接口设计、老接口重构、前后端对齐。

提示词模板未填写变量以红色标出
你是资深后端工程师,请为下面这个场景设计 REST 接口。

【场景】{{业务场景}}
【资源模型】{{资源模型}}
【调用方】{{调用方}}
【约束】{{约束条件}}

请输出:
1. 资源建模:列出资源、标识符、层级关系,说明哪些是聚合根。
2. 接口清单表:方法、路径、用途、幂等性、权限、限流建议,一行一个。
3. 请求与响应示例:为 3 个核心接口给出 JSON 示例,字段带类型与是否必填说明。
4. 状态码与错误码:HTTP 状态码映射,业务错误码设计(分段规则 + 至少 8 个具体码)。
5. 分页与排序:给出统一参数约定,说明游标分页与页码分页各自的适用场景。
6. 幂等与并发:针对积分扣减这类场景说明如何保证幂等(幂等键、唯一约束、乐观锁),给出具体方案。
7. 兼容与演进:字段新增、废弃、版本策略,说明如何避免破坏调用方。
8. 风险点:3 条最容易被忽略的问题(如超卖、重复提交、时区),各给一句检查方法。

不要只给路径列表,每个设计决定要说明理由。
填变量变量会自动替换进上方模板,可随时复制
已填 0 / 4
使用步骤
  1. 资源模型先定清楚,路径设计自然就出来了。
  2. 幂等方案必须针对真实业务(钱、积分、库存)单独确认。
  3. 评审时先看错误码和分页约定,这两块最容易后期返工。
接口按资源不按页面
按页面设计会导致接口复用率极低。
错误码要能定位
分段设计让前端一眼知道是哪类问题。
常见问题
用 PUT 还是 PATCH?

整体替换用 PUT,局部更新用 PATCH;幂等性要求高时优先 PUT。

版本号放路径还是 header?

对外服务放路径更直观,内部服务用 header 更灵活,二选一并写进规范。