本文由一缘原创整理，系统梳理 RESTful API 设计的核心原则与实战技巧，适合所有后端/全栈开发者。

RESTful API 设计最佳实践

高质量的 API 是现代后端和前后端分离架构的基石。

1. 资源建模

• 资源用名词复数表示，如 /users、/posts
• 子资源用嵌套路径，如 /users/123/posts

2. HTTP 方法与语义

• GET：获取资源
• POST：创建资源
• PUT：整体更新
• PATCH：部分更新
• DELETE：删除资源

3. 状态码与响应规范

1. HTTP 状态码（协议层）

• 200 OK：成功
• 201 Created：创建成功
• 204 No Content：删除成功
• 400 Bad Request：参数错误
• 401 Unauthorized：未认证
• 403 Forbidden：无权限
• 404 Not Found：资源不存在
• 500 Internal Server Error：服务器错误

HTTP 状态码用于表达请求在协议层的处理结果，建议合理使用。

2. 业务 code（业务层）

响应体中的 code 字段用于表达业务层的处理结果，不应与 HTTP 状态码重合，而是用于区分具体业务场景：

• code: 0 —— 业务处理成功
• 其他 code —— 业务错误（如验证码错误、token 过期、权限不足等）

示例：业务成功

{
  "code": 0,
  "data": { "id": 1, "name": "Tom" },
  "msg": "success"
}

示例：业务错误（如验证码错误）

{
  "code": 1001,
  "msg": "验证码错误"
}

示例：token 过期

{
  "code": 1002,
  "msg": "token 已过期"
}

建议将常见业务错误码统一管理，便于前后端协作和国际化。

4. 幂等性与安全性

• GET/PUT/DELETE 应幂等，POST 通常不幂等
• 避免副作用操作用 GET
• 幂等实现：如幂等 key、幂等 token

5. 版本管理

• 推荐 URL 版本号，如 /api/v1/users
• 或用 Accept header：Accept: application/vnd.myapp.v1+json

6. 分页、过滤与排序

• 分页参数：/users?page=2&size=10
• 过滤参数：/users?role=admin
• 排序参数：/users?sort=created_at,desc

7. 安全认证与授权

• 推荐 JWT/OAuth2 方案
• 认证信息放 header：Authorization: Bearer <token>
• 敏感操作需权限校验

8. 错误处理与国际化

• 错误响应结构统一
• 支持多语言 msg

{
  "code": 1001,
  "msg": "用户名或密码错误",
  "msg_en": "Invalid username or password"
}

9. 实战案例：用户管理 API 设计

GET    /api/v1/users           # 获取用户列表
POST   /api/v1/users           # 创建用户
GET    /api/v1/users/{id}      # 获取用户详情
PUT    /api/v1/users/{id}      # 更新用户
DELETE /api/v1/users/{id}      # 删除用户

请求示例：

POST /api/v1/users
Content-Type: application/json
{
  "name": "Tom",
  "email": "tom@example.com"
}

响应示例：

{
  "code": 0,
  "data": { "id": 1, "name": "Tom", "email": "tom@example.com" },
  "msg": "success"
}

10. API 文档与自动化测试

• 推荐 OpenAPI/Swagger 规范
• 自动生成文档与 Mock
• 用 Postman/Insomnia/pytest 等自动化测试

结语

RESTful API 设计是后端工程师的必备技能，规范的 API 能极大提升团队协作与系统可维护性。欢迎留言交流更多 API 设计经验！