RESTful API 接口设计规范提示词（资源命名、HTTP 方法与状态码、分页、错误格式、版本管理）
开始设计一组新接口、或者想统一团队接口风格时用：给出业务需求，AI 按 REST 惯例设计资源和路径，统一状态码、分页、过滤、错误返回格式和版本策略，并审查已有接口哪里不一致。
通用大模型 对话模型通用
你是一名 API 设计评审专家。请根据下面的需求设计接口，并输出一份团队可以复用的接口规范。 - 业务需求：[业务需求]（例：会员可以收藏商品、查看收藏列表、取消收藏） - 调用方：[如自家 App 和 Web、第三方合作方] - 技术约束：[技术约束]（例：网关只支持 GET 和 POST、必须兼容旧版 App） - 已有的接口（如果要审查）： [粘贴现有接口列表，没有就写无] 第一部分：接口设计 1. 识别资源：用名词复数表示集合，用层级表示从属关系，层级不超过两层；说明哪些操作不适合硬套资源模型（如「发送验证码」「批量审核」），以及这类操作怎么命名。 2. 列出每个接口：方法 | 路径 | 用途 | 请求参数 | 成功状态码 | 返回示例。 3. 方法语义：GET 不能有副作用；PUT 整体替换、PATCH 部分更新；哪些接口需要支持幂等（说明幂等键的传递方式）。 第二部分：统一规范（写成可以放进团队文档的条目） - 命名：路径用小写加连字符还是下划线、字段用驼峰还是下划线，选一种并保持一致； - 状态码：200、201、204、400、401、403、404、409、422、429、500 各自的使用场景； - 错误返回格式：统一结构，包含机器可读的错误码、给人看的提示、出错字段、请求 ID； - 分页：说明偏移分页和游标分页各自适用的情况，统一参数名和返回结构； - 过滤、排序与字段选择的参数写法； - 时间格式（带时区的 ISO 8601）、金额表示方式（整数分或字符串小数，不用浮点数）； - 版本策略：放在路径还是请求头，什么样的改动算破坏性变更。 第三部分：如果提供了已有接口，逐条指出与规范不一致的地方并给出修改建议，同时说明修改对现有调用方的影响。 约束条件与 REST 惯例冲突时（比如网关只支持 POST），以约束为准，给出折中方案。
高亮处换成你自己的内容：[业务需求]、[如自家 App 和 Web、第三方合作方]、[技术约束]、[粘贴现有接口列表，没有就写无]
ChatGPT Plus 充值
已被复制 0 次
使用说明
怎么填变量：[调用方] 是第三方合作方时，规范要更严格，版本策略和错误码要提前定好，因为对外接口改起来成本极高。[技术约束] 一定要写，很多公司的网关、防火墙或老客户端只支持部分 HTTP 方法。
常见坑：
- 所有接口都返回 HTTP 200，再在返回体里放一个 code 表示成败。这样监控和网关无法通过状态码识别错误。至少要让 4xx、5xx 反映真实情况。
- 金额用浮点数传，0.1 + 0.2 的精度问题会出现在对账里。用整数分或字符串。
- 偏移分页在数据量大或数据频繁新增时，会出现翻页重复或遗漏，信息流类列表适合用游标分页。
追问技巧：设计完成后，追问「根据这份设计生成 OpenAPI 3 描述文件」，可以直接导入接口文档工具和 Mock 服务。和 414 号提示词（从代码生成接口文档）配合使用效果更好。
示例输出
示例，仅供参考（节选）
| 方法 | 路径 | 用途 | 成功状态码 |
|---|---|---|---|
| GET | /v1/favorites?cursor=xxx&limit=20 | 我的收藏列表 | 200 |
| PUT | /v1/favorites/{productId} | 收藏商品（重复收藏不报错，幂等） | 204 |
| DELETE | /v1/favorites/{productId} | 取消收藏 | 204 |
统一错误格式：
json
{
"error": {
"code": "PRODUCT_NOT_FOUND",
"message": "商品不存在或已下架",
"field": "productId",
"requestId": "req_7f3a9c2e"
}
}说明：收藏用 PUT 而不是 POST，因为「收藏某个商品」的结果与执行次数无关，天然幂等。
同款作品
用这条提示词做出来的作品；原作者会因此获得积分
还没有同款，来做第一个。
0 条评论
还没有评论，来抢沙发～