API 设计模式

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

何时启用

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

资源设计

URL 结构

# 资源使用名词、复数、小写、短横线连接
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

命名规则

# 良好
/api/v1/team-members          # 多单词资源使用 kebab-case
/api/v1/orders?status=active  # 查询参数用于过滤
/api/v1/users/123/orders      # 嵌套资源表示所有权关系

# 不良
/api/v1/getUsers              # URL 中包含动词
/api/v1/user                  # 使用单数形式（应使用复数）
/api/v1/team_members          # URL 中使用 snake_case
/api/v1/users/123/getOrders   # 嵌套资源路径中包含动词

HTTP 方法和状态码

方法语义

方法	幂等性	安全性	用途
GET	是	是	检索资源
POST	否	否	创建资源，触发操作
PUT	是	否	完全替换资源
PATCH	否*	否	部分更新资源
DELETE	是	否	删除资源

*通过适当的实现，PATCH 可以实现幂等

状态码参考

# 成功
200 OK                    — GET、PUT、PATCH（包含响应体）…