RESTful API 设计最佳实践

良好的 API 设计能大幅提升前后端协作效率。本文总结 RESTful API 设计中的常见实践。

一、URL 设计原则

使用名词复数

GET    /api/users        # 获取用户列表
GET    /api/users/1      # 获取单个用户
POST   /api/users        # 创建用户
PUT    /api/users/1      # 更新用户
DELETE /api/users/1      # 删除用户

资源嵌套不超过两层

# 推荐
GET /api/users/1/orders

# 避免过深
GET /api/users/1/orders/1/items/1  # 考虑扁平化

二、HTTP 方法语义

方法	用途	幂等性
GET	查询	是
POST	创建	否
PUT	全量更新	是
PATCH	部分更新	是
DELETE	删除	是

三、状态码规范

• 200：成功（GET、PUT、PATCH）
• 201：创建成功（POST）
• 204：成功无返回体（DELETE）
• 400：请求参数错误
• 401：未认证
• 403：无权限
• 404：资源不存在
• 500：服务器错误

四、响应格式统一

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

错误时：

{
  "code": 40001,
  "message": "用户不存在",
  "errors": [
    { "field": "userId", "message": "无效的用户ID" }
  ]
}

五、版本管理

URL 路径版本：/api/v1/users，便于向后兼容和灰度发布。

六、安全建议

• 使用 HTTPS
• 鉴权：JWT 或 OAuth2
• 限流：防止滥用
• 敏感字段脱敏

遵循这些实践，能让 API 更清晰、易维护、易扩展。