RESTful API 设计最佳实践

REST 核心原则

REST (Representational State Transfer) 是一种架构风格，核心原则包括：

1. 客户端 - 服务器分离
2. 无状态 - 每个请求包含所有必要信息
3. 可缓存 - 响应可被缓存
4. 统一接口 - 使用标准 HTTP 方法

HTTP 方法使用规范

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

URL 设计规范

✅ 正确示例

GET    /users              # 获取用户列表
GET    /users/123          # 获取特定用户
POST   /users              # 创建用户
PUT    /users/123          # 更新用户
DELETE /users/123          # 删除用户
GET    /users/123/orders   # 获取用户的订单

❌ 错误示例

GET    /getUsers
POST   /createUser
GET    /deleteUser/123

状态码使用

状态码	含义	使用场景
200	OK	成功获取或更新
201	Created	资源创建成功
204	No Content	成功但无返回内容
400	Bad Request	请求参数错误
401	Unauthorized	未授权
403	Forbidden	禁止访问
404	Not Found	资源不存在
429	Too Many Requests	请求频率超限
500	Internal Server Error	服务器错误

响应格式规范

{
  "success": true,
  "data": {
    "id": 123,
    "name": "John",
    "email": "john@example.com"
  },
  "message": "操作成功",
  "timestamp": "2026-03-27T07:00:00Z"
}

错误处理

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "参数验证失败",
    "details": [
      {"field": "email", "message": "邮箱格式不正确"}
    ]
  }
}

版本控制

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

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

分页设计

GET /users?page=1&limit=20
GET /users?cursor=abc123&limit=20  # 游标分页

响应：

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "hasNext": true
  }
}

安全考虑

1. 使用 HTTPS
2. 认证授权 - JWT、OAuth 2.0
3. 输入验证 - 防止 SQL 注入、XSS
4. 速率限制 - 防止滥用
5. 敏感数据脱敏

文档化

使用 OpenAPI/Swagger 规范：

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

总结

良好的 API 设计能提升开发效率和用户体验。遵循 REST 规范，保持一致性，是打造优雅接口的关键。