RESTful API 设计规范

URL 命名规范

资源名称使用复数形式

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

使用子资源表达关系

GET /users/123/orders          # 用户的所有订单
GET /users/123/orders/456      # 用户的特定订单
GET /orders/456/items          # 订单的商品明细

筛选、排序与分页

GET /users?status=active&role=admin
GET /users?sort=-created_at    # 负号表示降序
GET /users?page=2&per_page=20
GET /users?offset=20&limit=20

HTTP 方法与语义

方法	语义	幂等	请求体	响应体
GET	查询资源	是	否	资源数据
POST	创建资源	否	创建数据	创建的资源
PUT	全量替换	是	完整资源	更新后的资源
PATCH	部分更新	否	差异数据	更新后的资源
DELETE	删除资源	是	否	空或状态信息

HTTP 状态码

2xx 成功

• 200 OK：请求成功
• 201 Created：资源创建成功，返回 Location 头
• 204 No Content：操作成功无返回体（常用于 DELETE）

3xx 重定向

• 301 Moved Permanently：资源永久迁移
• 304 Not Modified：资源未变更（配合 ETag/If-Modified-Since）

4xx 客户端错误

• 400 Bad Request：请求参数错误
• 401 Unauthorized：未认证
• 403 Forbidden：无权限
• 404 Not Found：资源不存在
• 409 Conflict：资源冲突（如重复创建）
• 422 Unprocessable Entity：校验失败
• 429 Too Many Requests：限流

5xx 服务端错误

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

错误响应格式

统一的错误响应结构：

{
    "error": {
        "code": "USER_NOT_FOUND",
        "message": "用户不存在",
        "details": {
            "userId": "123"
        }
    }
}

版本管理

推荐使用 URL 前缀或 Accept Header：

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

或：

GET /api/users
Accept: application/vnd.example.v1+json

安全性考虑

认证与鉴权

使用 JWT 或 OAuth 2.0 进行认证，Token 放在 Authorization Header：

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

HTTPS

所有 API 必须使用 HTTPS，防止中间人攻击。

速率限制

通过响应头告知客户端限流状态：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1640995200

文档

使用 OpenAPI 3.0 规范描述 API，配合 Swagger UI 或 Redoc 生成文档页面。