RESTful API 设计规范：从入门到精通

核心原则

REST（Representational State Transfer）是一种架构风格，核心是资源的概念。

URL 设计规范

使用名词，不用动词

✅ 好：GET /users ❌ 坏：GET /getUsers

使用复数名词

✅ 好：/users, /articles, /comments ❌ 坏：/user, /article, /comment

资源层级关系

GET /users/123/articles      # 用户 123 的文章
GET /users/123/articles/456  # 用户 123 的第 456 篇文章

HTTP 方法语义

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

状态码使用

2xx 成功

• 200 OK：通用成功
• 201 Created：资源创建成功
• 204 No Content：成功但无返回内容

4xx 客户端错误

• 400 Bad Request：请求参数错误
• 401 Unauthorized：未认证
• 403 Forbidden：无权限
• 404 Not Found：资源不存在
• 429 Too Many Requests：请求超限

5xx 服务端错误

• 500 Internal Server Error：服务器内部错误
• 502 Bad Gateway：网关错误
• 503 Service Unavailable：服务不可用

响应格式规范

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "示例"
  },
  "timestamp": 1711598400
}

分页设计

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

响应：

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

版本控制

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

遵循这些规范，你的 API 会更专业、更易用！