api-design

API 设计模式（API Design Patterns）

用于设计一致且开发者友好的 REST API 的约定与最佳实践。

何时激活（When to Activate）

• 设计新的 API 端点（Endpoint）
• 审查现有的 API 合约
• 添加分页、过滤或排序功能
• 为 API 实现错误处理
• 规划 API 版本化策略
• 构建公开或面向合作伙伴的 API

资源设计（Resource Design）

URL 结构

# 资源应为名词、复数、小写、短横线命名法（kebab-case）
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# 关系的子资源
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# 不符合 CRUD 的操作（谨慎使用动词）
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh

命名规则

# 推荐（GOOD）
/api/v1/team-members          # 多词资源使用短横线命名法（kebab-case）
/api/v1/orders?status=active  # 使用查询参数进行过滤
/api/v1/users/123/orders      # 嵌套资源表示归属关系

# 错误（BAD）
/api/v1/getUsers              # URL 中包含动词
/api/v1/user                  # 使用单数（应使用复数）
/api/v1/team_members          # URL 中使用蛇形命名法（snake_case）
/api/v1/users/123/getOrders   # 嵌套资源中包含动词

HTTP 方法与状态码（HTTP Methods and Status Codes）

方法语义

方法	幂等性（Idempotent）	安全性（Safe）	用途
GET	是	是	获取资源
POST	否	否	创建资源，触发操作
PUT	是	否	完整替换资源
PATCH	否*	否	部分更新资源
DELETE	是	否	删除资源

*通过正确的实现，PATCH 也可以设计为幂等。

状态码参考

# 成功（Success）
200 OK                    — GET, PUT, PATCH（包含响应体）
201 Created               — POST（需包含 Location 响应头）
204 No Content            — DELETE, PUT（不含响应体）

# 客户端错误（Client Errors）
400 Bad Request           — 校验失败，JSON 格式错误
401 Unauthorized          — 缺失或无效的身份验证
403 Forbidden             — 已验证身份但未获得授权
404 Not Found             — 资源不存在
409 Conflict              — 重复条目，状态冲突
422 Unprocessable Entity  — 语义错误（JSON 正确但数据非法）
429 Too Many Requests     — 超出速率限制

# 服务端错误（Server Errors）
500 Internal Server Error — 意外错误（绝不要暴露详细堆栈）
502 Bad Gateway           — 上游服务失败
503 Service Unavailable   — 暂时性过载，需包含 Retry-After

常见错误

# 错误：所有响应都返回 200
{ "status": 200, "success": false, "error": "Not found" }

# 推荐：语义化地使用 HTTP 状态码
HTTP/1.1 404 Not Found
{ "error": { "code": "not_found", "message": "User not found" } }

# 错误：校验错误返回 500
# 推荐：返回 400 或 422 并提供字段级详情

# 错误：创建资源返回 200
# 推荐：返回 201 并附带 Location 响应头
HTTP/1.1 201 Created
Location: /api/v1/users/abc-123