API 接口设计说明

接口设计一旦定下来，前端、后端、测试都按它对表，**改起来成本极高**。最常见的惨案是：返回格式前后不一致、错误码各写各的、分页参数每个接口都不同。

提前花十分钟把接口文档定清楚，能省掉后面几天的联调扯皮。这份文档也是前后端并行开发的基础——前端可以照着文档先用 Mock 数据开发。

这条提示词适合：新功能开发、前后端协作、小程序对接后端、内部服务接口。

你是后端架构师。请设计以下功能的 API 接口：

功能需求：{功能} 技术栈：{技术栈} 调用方：{调用方}

要求： 1. 给出完整的接口列表（路径 / 方法 / 用途一句话） 2. 每个接口详细说明：请求参数（名称/类型/必填/说明）、返回结构（带字段注释） 3. 统一返回格式（成功与失败的结构），并给出具体的示例 JSON 4. 设计完整的错误码表（码值 / 含义 / 触发条件 / 建议处理方式） 5. 说明鉴权方式（token 放哪里、如何校验） 6. 说明分页、排序、筛选的统一约定 7. 指出这套接口设计中最容易出问题的地方（如并发、幂等、越权） 8. 给出 2-3 个实际调用示例（含请求和响应） ```

• **功能**：把功能点列清楚。"收藏夹"要展开成"添加收藏、删除收藏、查列表、查是否已收藏"
• **技术栈**：决定写法和约定。Express 用中间件鉴权，云函数没有传统路由，写法完全不同
• **调用方**：小程序 / Web / 第三方。**调用方的限制要说明**——小程序有 request 并发上限，第三方要限流

【接口列表】
GET    /api/favorites          查询收藏列表
POST   /api/favorites          添加收藏
DELETE /api/favorites/:id      删除收藏
GET    /api/favorites/check    查询某条是否已收藏

【统一返回格式】 // 成功 { "code": 0, "message": "ok", "data": { ... } }

// 失败 { "code": 40001, "message": "参数缺失：itemId 不能为空", "data": null }

【POST /api/favorites】 请求： { "itemId": "abc123", // string, 必填, 被收藏项的唯一标识 "itemType": "tool", // string, 必填, 取值 tool | skill | prompt "remark": "" // string, 选填, 用户备注, 最长 50 字 }

响应： { "code": 0, "message": "ok", "data": { "id": "fav_8f2a...", // 收藏记录 ID "createdAt": "2026-09-30T12:00:00Z" } }

【错误码表】 0 成功 — 直接使用返回数据 40001 参数错误 必填项缺失或格式非法 提示用户具体哪个字段出错 40100 未登录 token 缺失或过期 跳转登录页 40300 越权 操作了不属于自己的数据 不提示细节，返回通用错误 40900 重复收藏 同一项已收藏 前端切换为"已收藏"状态，不发错误提示 42900 请求过频 超过限流阈值 提示稍后重试 50000 服务异常 未捕获的服务端错误 提示"服务繁忙"，并上报日志

【鉴权】 Header: Authorization: Bearer <token> 中间件校验 → 解析出 userId → 挂到 req.user 所有涉及用户数据的接口，必须校验资源归属，避免越权

【分页约定】 请求：?page=1&pageSize=20 响应：{ list: [...], total: 128, page: 1, pageSize: 20, hasMore: true } ```

【易出问题的地方】 1. **越权**——删除接口只校验 token 有效，没校验这条数据属不属于当前用户。必须加 `where userId = req.user.id` 2. **重复收藏**——用户连点两次就插入两条。靠数据库唯一索引兜底，冲突时返回 40900 而不是 50000 3. **分页深度**——page 很大时 skip 性能急剧下降。数据量大时改用游标分页 ```

• **要更简单**：加"合并相近接口，减少请求次数，适合小程序一次性加载"
• **要更规范**：加"严格遵循 RESTful 规范，用标准 HTTP 状态码 + 语义化路径"
• **要带版本**：加"路径包含版本号 /v1，并说明版本升级时的兼容策略"
• **要有 Mock 数据**：加"为每个接口生成一份 Mock 响应示例，供前端先行开发"
• **要 OpenAPI**：加"额外输出 OpenAPI 3.0 格式的接口描述文件"
• **要考虑安全**：加"补充限流、防重放、敏感字段脱敏的具体方案"

**Q：接口联调时老是报错但不知道为什么？** A：因为**错误码没定清楚**。加"每个错误码都要能明确指向问题原因，禁止用 50000 兜底一切"。

**Q：改接口导致老客户端崩溃？** A：**新增字段可以，删除和改类型不行**。加"字段只增不删，废弃字段保留并标注 deprecated，而不是直接移除"。

**Q：前端需要的字段要单独再调一次接口？** A：设计时就要想清楚**列表页需要哪些字段一次性给全**，避免"点进详情页还要再请求一次"。加"列表接口返回的字段要足够渲染列表和跳转，不需要二次请求"。