RESTful API 设计最佳实践

好的 API 设计让前后端协作更顺畅。分享一套经过实战验证的设计规范。

核心原则

1. 资源导向

API 围绕资源设计，使用名词而非动词：

✅ /users          # 用户列表
✅ /users/123      # 特定用户
❌ /getUsers       # 避免动词
❌ /getUserById    # 避免动词

2. 使用 HTTP 方法

方法	用途	示例
GET	获取资源	GET /users
POST	创建资源	POST /users
PUT	更新资源（全量）	PUT /users/123
PATCH	更新资源（部分）	PATCH /users/123
DELETE	删除资源	DELETE /users/123

3. 状态码规范

200 OK          # 成功
201 Created     # 创建成功
204 No Content  # 删除成功（无返回）
400 Bad Request # 请求参数错误
401 Unauthorized # 未认证
403 Forbidden   # 无权限
404 Not Found   # 资源不存在
422 Unprocessable # 数据验证失败
500 Server Error # 服务器错误

URL 设计规范

版本控制

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

复数名词

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

嵌套资源

# 获取用户的所有文章
GET /users/123/articles

# 获取文章的评论
GET /articles/456/comments

过滤、排序、分页

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

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

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

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

响应格式

成功响应

{
  "code": 200,
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhang@example.com"
  },
  "message": "success"
}

列表响应

{
  "code": 200,
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "limit": 20
  }
}

错误响应

{
  "code": 400,
  "message": "参数验证失败",
  "errors": [
    {"field": "email", "message": "邮箱格式错误"}
  ]
}

认证授权

JWT Token

# 请求头
Authorization: Bearer <token>

刷新机制

# 访问令牌过期时间：15 分钟
# 刷新令牌过期时间：7 天
POST /auth/refresh
{
  "refresh_token": "xxx"
}

文档规范

使用 OpenAPI/Swagger 自动生成文档：

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

安全建议

1. 始终使用 HTTPS
2. 限制请求频率（防刷）
3. 输入验证（防注入）
4. 敏感数据脱敏（密码、token）
5. CORS 配置（跨域控制）

实战检查清单

• URL 使用名词复数
• HTTP 方法语义正确
• 状态码规范
• 响应格式统一
• 错误信息清晰
• 认证机制完善
• 文档完整
• 有版本控制

好的 API 设计是优秀产品的基石，值得用心打磨！