RESTful API 设计规范：从入门到企业级实践

REST 核心原则

REST（Representational State Transfer）是一种架构风格，核心原则：

1. 资源导向：一切皆资源，用 URI 标识
2. 无状态：每次请求包含完整信息
3. 统一接口：用 HTTP 方法表达操作
4. 可缓存：响应可缓存提升性能
5. 分层系统：客户端不关心服务端架构

URI 设计规范

1. 使用名词，不用动词

# ❌ 错误
GET /getUsers
POST /createUser
PUT /updateUser/123

# ✅ 正确
GET /users
POST /users
PUT /users/123

2. 复数形式

# ✅ 统一用复数
GET /users
GET /users/123/posts
GET /posts/456/comments

3. 嵌套资源适度

# ✅ 合理嵌套（2 层以内）
GET /users/123/posts

# ❌ 过深嵌套
GET /users/123/posts/456/comments/789/replies

# ✅ 扁平化
GET /comments?post_id=456

4. 小写字母，连字符分隔

# ✅ 推荐
GET /user-profiles
GET /order-items

# ❌ 避免
GET /UserProfiles
GET /order_items

HTTP 方法语义

方法	用途	幂等	安全
GET	查询资源	✅	✅
POST	创建资源	❌	❌
PUT	全量更新	✅	❌
PATCH	部分更新	❌	❌
DELETE	删除资源	✅	❌

状态码规范

成功响应

200 OK          # 成功（GET, PUT, PATCH）
201 Created     # 创建成功（POST）
204 No Content  # 成功但无返回（DELETE）

客户端错误

400 Bad Request      # 请求参数错误
401 Unauthorized     # 未认证
403 Forbidden        # 无权限
404 Not Found        # 资源不存在
409 Conflict         # 资源冲突
422 Unprocessable    # 语义错误
429 Too Many Requests # 请求限流

服务端错误

500 Internal Server Error  # 服务器错误
502 Bad Gateway           # 上游错误
503 Service Unavailable   # 服务不可用

响应格式

统一响应结构

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "John"
  },
  "timestamp": 1710912000
}

错误响应

{
  "code": 40001,
  "message": "参数验证失败",
  "errors": [
    {"field": "email", "message": "邮箱格式错误"},
    {"field": "password", "message": "密码长度不足"}
  ]
}

分页响应

{
  "code": 0,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 150,
      "total_pages": 8
    }
  }
}

版本管理

URI 版本（推荐）

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

请求头版本

GET /users
Accept: application/vnd.myapi.v1+json

过滤、排序、分页

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

# 排序
GET /users?sort=created_at&order=desc

# 分页
GET /users?page=2&page_size=20

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

安全最佳实践

1. 始终使用 HTTPS
2. 认证用 Token（JWT/OAuth2）
3. 敏感操作需要二次验证
4. 实现请求限流
5. 记录审计日志
6. 输入验证和输出编码

API 文档

使用 OpenAPI/Swagger 规范：

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        200:
          description: 成功

总结

好的 API 设计让前后端协作更顺畅，遵循规范，让你的 API 更专业、更易用。