API 设计 Prompt：从需求到 RESTful API 规范

用法

描述你的功能需求，AI 生成完整的 API 设计文档。

Prompt

你是一个资深后端架构师。请根据以下需求，设计 RESTful API。

## 需求描述

{{描述你要实现什么功能，比如"用户注册登录、文章 CRUD、评论系统"}}

## 已有约束

- 框架：{{Express / FastAPI / Go Gin / Spring Boot}}
- 认证方式：{{JWT / Session / API Key}}
- 数据库：{{PostgreSQL / MySQL / MongoDB}}

## 要求

1. 遵循 RESTful 规范（资源名复数、HTTP 方法语义正确）
2. 统一的响应格式（成功/失败）
3. 合理的状态码（不要全用 200）
4. 分页、排序、筛选的 query 参数规范
5. 错误响应包含 error code + message + details
6. 标注哪些接口需要认证

## 输出格式

### API 概览
| 方法 | 路径 | 描述 | 认证 |
|---|---|---|---|

### 详细设计

对每个接口：
- 路径参数 / Query 参数 / Body 字段（含类型和校验规则）
- 请求示例
- 响应示例（成功 + 错误）
- 状态码列表

### 统一规范
- 响应格式
- 错误码定义
- 分页格式

设计原则提醒

• GET 不改数据，POST 创建，PUT 全量更新，PATCH 部分更新，DELETE 删除
• 资源名用复数（/users 不是 /user）
• 嵌套关系最多 2 层（/users/:id/posts 合理，/users/:id/posts/:id/comments/:id 太深）
• 分页用 offset+limit 或 cursor（大数据量用 cursor）
• 时间字段用 ISO 8601（不要用时间戳）

另外五条 AI 默认不会做、但你必须要求的：

• 幂等性：POST 天然不幂等。涉及创建订单 / 发消息这类操作时，要求 AI 标注哪些接口需要支持 Idempotency-Key，以及重复提交时的返回语义。
• 错误码要可机读：{ "msg": "error" } 对人类都难用，对调用方更是没法分支处理。要求 code 字段用稳定的大写枚举（USER_NOT_FOUND），message 才面向人。
• 版本策略先定：URL 前缀（/v1/）还是 Header？不要两者都用。要求 AI 在概览里一句话写清版本策略，别让它在第 20 个接口上才想起来。
• 限流与配额：公开 API 必须写清限流维度（按 IP / 按用户 / 按 key）与 429 时的 Retry-After。AI 默认不会提这件事。
• 字段命名一致性：同一概念在所有接口里用同一个名字（user_id 不要一会儿 userId 一会儿 uid）。让 AI 在「统一规范」一节给出一份字段命名表。

关于认证方式的一条现实提醒：如果这套 API 未来要被 AI Agent 调用（而不是只有自家前端），在设计阶段就把「机器可读的接口描述」考虑进去——一份维护良好的 OpenAPI 文档，就是 Agent 通过 Function Calling 调用你接口的依据。字段名与描述的可读性，从此不只是人的事。

为什么有效

• 先约束后生成：把框架、认证、数据库三个变量钉死，AI 不会在「要不要上 GraphQL」「用不用 JWT」这类分叉上跑偏。
• 输出格式即验收标准：要求表格 + 请求/响应示例，等于给了一份可以直接进评审会的稿子，而不是一段散文。
• 显式列状态码：大多数 AI 默认全返回 200，把「不要全用 200」写进 prompt 是最低成本的质量闸门。
• 要求「标注哪些接口需要认证」：这一条顺带解决了一个隐蔽问题——AI 在批量生成 20 个接口时，很容易漏掉其中两三个需要鉴权的。让它逐条标出来，你扫一眼表格就能发现遗漏。

验收：设计稿过不过关

1. 挑一个错误路径走一遍：随便选一个 404 或 409，看它的响应体是否符合「统一规范」里定义的错误格式。AI 最常见的失误是前两三个接口写得很规范，后面的错误响应开始自由发挥。
2. 检查分页参数是否在每个列表接口上一致：offset/limit 不要在某个接口上变成 page/size。
3. 检查有没有「动词式路径」漏网：全文搜一遍 /get /create /update，出现即打回。
4. 确认创建接口的返回：是返回完整资源对象，还是只返回 id？同一个 API 里必须统一，AI 经常两种混着来。

进阶（自动化）

把生成的 OpenAPI 直接落到仓库，让接口变更可 diff：

# 用 AI 生成 openapi.yaml 后，校验 + 生成 mock server
npx @redocly/cli lint openapi.yaml
npx @stoplight/prism mock openapi.yaml --port 4010

然后把 openapi.yaml 接进 CI：breaking change 直接 fail，比人工 review 靠谱。

反例（AI 默认会写的烂版本）

默认输出：/getUserInfo、/api/v1/getUserList——动词式路径 + 全 200 + 错误只有 { "msg": "error" }。

加了 prompt 之后：GET /users、GET /users?offset=0&limit=20&sort=-created_at；错误返回 { "error": { "code": "USER_NOT_FOUND", "message": "...", "details": {} } }，并标注哪些接口带 Authorization。

延伸阅读

• SQL 查询生成 Prompt · 技术文档生成 Prompt — 设计完接口后建表、写文档
• 技术方案评估 Prompt — REST/GraphQL 选型先评估再设计
• 什么是 RAG · Function Calling — 给 AI 应用设计 API 时的常见模式