RESTful API 设计原则与常见误区

设计一套清晰、一致、易于使用的 API，是后端开发者的核心技能。REST 架构风格虽然已有 20 多年历史，但实践中仍然存在大量误区。

资源命名规范

REST 的核心是「资源」。URL 应该表示资源，而非动作：

# ✅ 好的设计
GET    /api/users          # 获取用户列表
GET    /api/users/42       # 获取单个用户
POST   /api/users          # 创建用户
PUT    /api/users/42       # 更新用户
DELETE /api/users/42       # 删除用户

# ❌ 不好的设计
GET    /api/getUsers
POST   /api/createUser
POST   /api/deleteUser/42

HTTP 方法语义

• GET：读取资源，幂等且安全
• POST：创建资源，非幂等
• PUT：完整替换资源，幂等
• PATCH：部分更新资源
• DELETE：删除资源，幂等

状态码的正确使用

• 200 OK — 请求成功
• 201 Created — 资源创建成功
• 204 No Content — 删除成功，无返回体
• 400 Bad Request — 客户端请求参数错误
• 401 Unauthorized — 未认证
• 403 Forbidden — 无权限
• 404 Not Found — 资源不存在
• 422 Unprocessable Entity — 语义正确但无法处理
• 429 Too Many Requests — 请求频率超限
• 500 Internal Server Error — 服务端错误

分页与过滤

GET /api/articles?page=2&limit=20&sort=-createdAt&tag=typescript

# 响应
{
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  }
}

常见误区

1. 在 URL 中使用动词：REST 用 HTTP 方法表达动作，URL 只表示资源
2. 返回 200 但 body 中包含错误信息：应使用正确的 HTTP 状态码
3. 过度嵌套：/users/1/posts/2/comments/3 不如 /comments/3
4. 忽略版本管理：使用 URL 前缀（/v1/）或 Header 做版本控制
5. 不一致的响应格式：统一 envelope 结构，包含 data、error、meta 字段

「好的 API 设计就像好的 UX 设计——用户（开发者）不应该需要阅读文档就能猜出怎么用。」