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" }