RESTful API 设计规范：写出优雅的接口

什么是 RESTful？

REST（Representational State Transfer）是一种架构风格，核心是资源和HTTP 方法的映射。

核心原则

1. 资源命名

# ✅ 好：使用名词，复数形式
GET /api/users
GET /api/users/123
GET /api/users/123/posts

# ❌ 差：使用动词
GET /api/getUsers
POST /api/createUser

2. HTTP 方法语义

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

3. 状态码使用

# 成功
200 OK          # 通用成功
201 Created     # 创建成功
204 No Content  # 删除成功（无返回体）

# 客户端错误
400 Bad Request     # 参数错误
401 Unauthorized    # 未认证
403 Forbidden       # 无权限
404 Not Found       # 资源不存在
409 Conflict        # 资源冲突
422 Unprocessable   # 数据验证失败

# 服务端错误
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable

请求/响应设计

请求示例

POST /api/users
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "张三",
  "email": "zhangsan@example.com",
  "age": 25
}

响应格式

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com",
    "createdAt": "2026-03-20T10:00:00Z"
  }
}

错误响应

{
  "code": 400,
  "message": "参数验证失败",
  "errors": [
    {"field": "email", "message": "邮箱格式不正确"},
    {"field": "age", "message": "年龄必须大于 0"}
  ]
}

分页设计

查询参数

GET /api/users?page=1&pageSize=20&sortBy=createdAt&order=desc

响应格式

{
  "code": 200,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 150,
      "totalPages": 8
    }
  }
}

过滤和排序

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

# 范围查询
GET /api/orders?createdAt[gte]=2026-01-01&createdAt[lte]=2026-03-20

# 模糊搜索
GET /api/users?name[like]=张

# 排序
GET /api/users?sortBy=age&order=asc

版本控制

# URL 版本（推荐）
GET /api/v1/users
GET /api/v2/users

# 或 Header 版本
Accept: application/vnd.api.v1+json

安全最佳实践

1. 认证和授权

# 使用 JWT Token
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

2. 速率限制

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1679313600

3. 敏感数据

• 密码永远不要返回
• 使用 HTTPS
• 敏感操作需要二次验证

文档化

使用 OpenAPI/Swagger：

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

完整示例

# 创建用户
POST /api/v1/users
{
  "name": "李四",
  "email": "lisi@example.com"
}

# 获取用户
GET /api/v1/users/123

# 更新用户
PATCH /api/v1/users/123
{
  "name": "李四更新"
}

# 删除用户
DELETE /api/v1/users/123

# 获取用户的文章
GET /api/v1/users/123/posts?page=1&pageSize=10

总结

好的 API 设计 = 清晰的资源命名 + 正确的 HTTP 语义 + 一致的响应格式 + 完善的文档

记住：API 是产品，不是实现细节！🎯