RESTful API 设计最佳实践指南

好的 API 设计让前端开发事半功倍。分享一套经过实战检验的 RESTful API 设计规范。

1. 资源命名规范

使用名词，不用动词：

✅ GET /users
✅ POST /users
❌ GET /getUsers
❌ POST /createUser

使用复数形式：

✅ /users
✅ /articles
❌ /user
❌ /article

层级关系用斜杠：

✅ /users/123/articles
✅ /articles/456/comments

2. HTTP 方法语义

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

3. 状态码使用

2xx 成功：

• 200 OK：通用成功
• 201 Created：创建成功
• 204 No Content：成功但无返回体

4xx 客户端错误：

• 400 Bad Request：参数错误
• 401 Unauthorized：未认证
• 403 Forbidden：无权限
• 404 Not Found：资源不存在
• 422 Unprocessable Entity：数据验证失败

5xx 服务器错误：

• 500 Internal Server Error：服务器错误

4. 响应格式统一

// 成功响应
{
  "code": 0,
  "data": { ... },
  "message": "success"
}

// 错误响应
{
  "code": 40001,
  "data": null,
  "message": "参数错误",
  "errors": [
    { "field": "email", "message": "邮箱格式不正确" }
  ]
}

5. 分页设计

Query 参数：

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

响应包含分页信息：

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

6. 过滤、排序、字段选择

# 过滤
GET /users?status=active&role=admin

# 排序
GET /users?sort=-created_at  # 降序
GET /users?sort=name         # 升序

# 字段选择
GET /users?fields=id,name,email

7. 版本控制

URL 版本（推荐）：

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

Header 版本：

Accept: application/vnd.myapi.v1+json

8. 认证与授权

推荐 JWT：

Authorization: Bearer <token>

敏感操作需要二次验证：

POST /users/123/delete
X-Verify-Code: 123456

9. 速率限制

在响应头中告知限制：

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

10. 文档化

使用 OpenAPI/Swagger：

/users:
  get:
    summary: 获取用户列表
    parameters:
      - name: page
        in: query
        schema:
          type: integer
    responses:
      200:
        description: 成功

结语

好的 API 设计是自解释的。遵循这些规范，让你的 API 易用、易维护、易扩展！

---

你设计 API 时踩过什么坑？评论区聊聊！