design-api

API 设计技能

自由度：混合。 资源模型、错误结构，以及 REST 与 GraphQL 的选择 [自由度高]；设计前文档／架构／Grep 检查 [自由度低 — 严格按步骤执行]。

设计简洁、一致且便于开发者使用的 API。

推理方式

1. 调研 — 现有文档、架构和类似端点
2. 建模 — 资源、关系，以及 REST 与 GraphQL 的选择
3. 契约 — 路径、状态码、错误结构、身份验证、分页
4. 检查 — 命名符合此代码库的规范；没有重复端点

示例

调研： orders 有 user_id；没有 GET /users/:id/orders；客户端使用 useQuery。 建模： 订单是用户的嵌套资源，而不是 /getUserOrders RPC。 契约： GET /users/:id/orders → { data, meta }；统一使用 { error: { code, message, details } }。 检查： 使用复数 kebab-case；列表需分页；仅状态码表中列出的 401/404/422。

汇报前自我检查

• 说明了设计前检查 — 已明确检查文档、架构和类似端点
• 错误结构统一 — 每种失败都使用 { error: { code, message, details } }
• 列表需分页 — 不提供无界的 GET /resources
• 找对负责人 — 实际复现的 4xx/5xx 问题 → debug-fe-be-integration；产品范围仍不明确 → design-prd

设计前检查 [自由度低 — 严格按步骤执行]

设计任何 API 之前：

1. 检查现有 API 文档

• 正在运行的后端文档路由（/api-docs、/docs、/swagger、/openapi.json）
• 代码库的 API README 或命名规范文档（在 docs/ 和 src/api/ 下 Grep 搜索 naming）

2. 验证数据库架构

使用 Supabase MCP 了解现有数据结构：

SELECT column_name, data_type, is_nullable
FROM information_schema.columns WHERE table_name = 'your_table';

还要检查枚举值（enum_range）和外键（information_schema.table_constraints）： references/examples.md §设计前架构探查。

3. 检查现有端点

使用 Grep 搜索已实现的类似端点：

Grep: "router.get|router.post" to find existing route patterns
Grep: "useQuery|useMutation" to find existing frontend integrations

4. 验证声明（必需）

开始设计前，说明：

"Pre-design check:
- Existing API docs reviewed: [YES/NO]
- Database schema verified: [tables/enums checked]
- Similar endpoints found: [list or none]
- Naming conventions confirmed: [YES/NO]"

---

REST API 设计 [自由度高]

URL 结构

GET /resources # List
GET /resources/:id # Get one
POST /resources # Create
PUT /resources/:id # Replace
PATCH /resources/:id # Update
DELETE /resources/:id # Delete

命名约定

应使用	不应使用
/users	/getUsers、/user-list
/users/:id	/user/:id、/users/get/:id
/users/:id/orders	/getUserOrders
复数名词	动词、单数
kebab-case	camelCase、snake_case

示例

GET /users # List users
GET /users/123 # Get user 123
GET /users/123/orders # User's orders
GET /users/123/orders/456 # Specific order
POST /users/123/orders # Create order for user

---

请求／响应格式 [自由度低 — 使用此格式]

• 请求正文 — 扁平 JSON，键使用 camelCase，不加封装。
• 成功响应 — 单个资源使用 { "data": { ... } }；列表使用 { "data": [...], "meta": { total, page, perPage, totalPages } }。
• 错误响应 — 全部统一使用 { "error": { "code", "message", "details" } }；code 可供机器读取，details 是按字段列出的列表。

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

请求体、单个资源和列表响应的完整内容：references/examples.md §请求体至 §列表响应。

---

HTTP 状态码 [自由度低 — 使用此表]

成功（2xx）

代码	使用场景
200 OK	GET、PUT、PATCH 成功
201 Created	POST 创建了新资源
204 No Content	DELETE 成功，不返回正文

客户端错误（4xx）

代码	使用场景
400 Bad Request	请求正文无效
401 Unauthorized	未通过身份验证
403 Forbidden	已通过身份验证，但无权执行操作
404 Not Found	资源不存在
409 Conflict	资源冲突（重复）
422 Unprocessable	验证失败
429 Too Many	请求频率受限

服务端错误（5xx）

代码	使用场景
500 Internal Error	意外的服务端错误
502 Bad Gateway	上游服务失败
503 Unavailable	服务暂时不可用

---

查询参数

• 筛选 — ?role=admin&status=active，日期范围可用 ?createdAfter=2024-01-01。
• 排序 — ?sort=name；前缀 - 表示降序；多个字段以逗号分隔（?sort=role,-name）。
• 分页 — 默认使用 ?page=2&perPage=20；对于大型列表或实时列表，使用 ?cursor=abc123；绝不返回无界列表。
• 字段选择 — ?fields=id,name,email；通过 ?include=orders,profile 包含关联数据。

各项示例 URL：references/examples.md §查询参数。

---

版本控制

默认方式：URL 路径（GET /v1/users、GET /v2/users）。另一种方式是使用标头版本控制 （Accept: application/vnd.api+json;version=2）： references/examples.md §版本控制。

---

身份验证

默认方式：Authorization: Bearer <token>。对于服务器到服务器的调用方，另一种方式是通过 X-API-Key 标头（或 ?apiKey=）传递 API 密钥：references/examples.md §身份验证。

---

常见模式

• 批量操作 — 使用 { create: [...], update: [...], delete: [ids] } 调用 POST /users/bulk。
• 搜索 — 当条件超出查询字符串的承载范围时，使用 { query, filters, sort } 调用 POST /users/search。
• 操作（非 CRUD） — 在名词下创建动词子资源：POST /orders/123/cancel、POST /users/123/verify-email、POST /payments/123/refund。

批量操作和搜索的请求体：references/examples.md §批量操作、§搜索。

---

API 设计检查清单 [LOW freedom — do not skip]

一致性

• 命名约定一致
• 响应格式一致
• 错误格式一致
• 分页方式一致

易用性

• URL 直观
• 文档清晰
• 错误消息有意义
• 默认值合理

安全性

• 必须进行身份验证
• 检查授权
• 验证输入
• 限流

性能

• 列表使用分页
• 支持字段选择
• 查询高效
• 设置缓存标头

---

文档模板

每个端点应包含：标题、一行用途说明、**Endpoint:**、**Authentication:**、请求体表格（字段、类型、必填、说明）、带 JSON 示例的响应状态，以及错误列表。完整模板：references/examples.md §文档模板。