RESTful API 设计最佳实践：20 条黄金法则

好的 API 设计让开发者愉悦，糟糕的 API 让人抓狂。本文总结 20 条经过验证的设计法则。

一、URL 设计规范

1. 使用名词，不用动词

✅ /users ❌ /getUsers

2. 复数形式

✅ /users/123 ❌ /user/123

3. 小写字母，连字符分隔

✅ /user-profiles ❌ /userProfiles ❌ /USER_PROFILES

4. 避免深层嵌套

✅ /users/123/orders ❌ /users/123/orders/456/items/789

超过 3 层考虑扁平化：/orders/456/items

5. 资源过滤用查询参数

✅ /users?role=admin&status=active ❌ /users/role/admin/status/active

二、HTTP 方法语义

6. 正确使用 HTTP 动词

方法	用途	幂等
GET	获取资源	是
POST	创建资源	否
PUT	全量更新	是
PATCH	部分更新	是
DELETE	删除资源	是

7. GET 不能修改状态

GET 请求必须安全，不能有副作用。

三、状态码使用

8. 返回合适的状态码

200 OK          # 成功
201 Created     # 创建成功
204 No Content  # 删除成功（无返回体）
400 Bad Request # 参数错误
401 Unauthorized # 未认证
403 Forbidden   # 无权限
404 Not Found   # 资源不存在
409 Conflict    # 资源冲突
422 Unprocessable # 验证失败
429 Too Many Requests # 限流
500 Internal Server Error # 服务器错误

9. 不要都用 200

错误情况返回对应状态码，便于客户端处理。

四、响应格式

10. 统一响应结构

{
  "success": true,
  "data": {...},
  "message": "操作成功",
  "timestamp": 1703275200
}

错误响应：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "参数验证失败",
    "details": [...]
  }
}

11. 使用标准时间格式

✅ 2024-01-15T10:30:00Z (ISO 8601) ❌ 2024/01/15 10:30:00

12. 字段命名一致

全用 camelCase 或 snake_case，不要混用。

五、分页与过滤

13. 标准分页参数

/users?page=1&limit=20
/users?offset=0&limit=20

返回元数据：

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

14. 支持字段选择

/users?fields=id,name,email

减少不必要的数据传输。

15. 支持排序

/users?sort=created_at&order=desc

六、版本控制

16. API 必须版本化

方式 1（推荐）：URL 路径

/api/v1/users
/api/v2/users

方式 2：HTTP Header

Accept: application/vnd.api.v1+json

七、安全与性能

17. 必须使用 HTTPS

生产环境禁止 HTTP。

18. 实现速率限制

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1703275200

19. 支持 CORS

明确配置允许的源、方法、头部。

20. 敏感数据脱敏

// ✅ 好
{"phone": "138****1234"}

// ❌ 差
{"phone": "13800131234", "password": "..."}

额外建议

• 提供 API 文档（Swagger/OpenAPI）
• 实现 HATEOAS（可选）
• 使用 ETag 支持缓存
• 记录 API 访问日志
• 监控 API 性能指标

好的 API 是产品的重要组成部分，值得用心设计！