RESTful API 设计最佳实践

REST 核心原则

REST（Representational State Transfer）是一种架构风格，强调资源导向和无状态通信。

URL 设计规范

使用名词而非动词

✅ /users - 获取用户列表 ✅ /users/123 - 获取特定用户 ❌ /getUsers - 避免动词

使用复数形式

✅ /articles ❌ /article

嵌套资源表达层级关系

/users/123/articles - 用户 123 的文章

HTTP 方法语义

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

状态码正确使用

• 200 OK - 成功
• 201 Created - 资源创建成功
• 204 No Content - 成功但无返回内容
• 400 Bad Request - 请求参数错误
• 401 Unauthorized - 未认证
• 403 Forbidden - 无权限
• 404 Not Found - 资源不存在
• 429 Too Many Requests - 请求超限
• 500 Internal Server Error - 服务器错误

版本控制策略

# URL 路径版本化（推荐）
/api/v1/users

# 或请求头版本化
Accept: application/vnd.api.v1+json

响应格式规范

{
  "data": { ... },
  "meta": {
    "page": 1,
    "total": 100
  },
  "errors": []
}

好的 API 设计让集成更简单。