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 不会在「要不要上 GraphQL」「用不用 JWT」这类分叉上跑偏。
• 输出格式即验收标准：要求表格 + 请求/响应示例，等于给了一份可以直接进评审会的稿子，而不是一段散文。
• 显式列状态码：大多数 AI 默认全返回 200，把「不要全用 200」写进 prompt 是最低成本的质量闸门。

进阶（自动化）

把生成的 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 时的常见模式