RESTful API 设计规范#

#概述

REST（Representational State Transfer）是一种软件架构风格，RESTful API 是基于 REST 原则设计的 Web API。它使用标准的 HTTP 方法，以资源为中心，实现客户端与服务器的无状态交互。

#核心原则

#1. 统一接口 (Uniform Interface)

• 资源标识：每个资源有唯一的 URI
• 资源操作：通过标准 HTTP 方法操作资源
• 自描述消息：消息包含足够的信息让接收方处理
• 超媒体驱动：API 响应包含相关资源的链接

#2. 无状态 (Stateless)

• 每个请求包含处理所需的所有信息
• 服务器不保存客户端状态
• 会话状态由客户端维护

#3. 可缓存 (Cacheable)

• 响应明确标识是否可缓存
• 合理使用缓存提高性能
• 客户端可以重用缓存响应

#4. 分层系统 (Layered System)

• 客户端不知道是否直接连接最终服务器
• 中间层可以提高可扩展性和安全性
• 负载均衡、缓存、安全层透明

#5. 按需代码 (Code on Demand，可选)

• 服务器可以传输可执行代码
• 扩展客户端功能
• 不是 REST 架构的必需约束

#资源设计

#1. 资源命名

# 好的命名
/users
/users/{id}/orders
/products/{id}/reviews

# 避免的命名
/getAllUsers
/createNewUser
/deleteUserById/{id}

#2. URI 设计规范

• 使用名词，而不是动词
• 使用小写字母
• 使用连字符 - 分隔单词
• 避免文件扩展名
• 版本化 API

#3. 资源关系

# 一对一关系
/users/{userId}/profile

# 一对多关系  
/users/{userId}/orders
/users/{userId}/orders/{orderId}

# 多对多关系
/users/{userId}/roles
/roles/{roleId}/users

#HTTP 方法使用

#1. GET - 获取资源

GET /api/v1/users
GET /api/v1/users/{id}
GET /api/v1/users?page=1&limit=20&sort=name

#2. POST - 创建资源

POST /api/v1/users
Content-Type: application/json

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

#3. PUT - 更新完整资源

PUT /api/v1/users/{id}
Content-Type: application/json

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

#4. PATCH - 部分更新资源

PATCH /api/v1/users/{id}
Content-Type: application/json

{
  "age": 31
}

#5. DELETE - 删除资源

DELETE /api/v1/users/{id}

#6. HEAD - 获取响应头

HEAD /api/v1/users/{id}

#7. OPTIONS - 查询支持的方法

OPTIONS /api/v1/users

#响应设计

#1. 状态码规范

# 成功响应
200 OK - GET、PUT、PATCH 成功
201 Created - POST 成功，资源已创建
204 No Content - DELETE 成功，无返回内容

# 客户端错误
400 Bad Request - 请求参数错误
401 Unauthorized - 未认证
403 Forbidden - 无权限
404 Not Found - 资源不存在
409 Conflict - 资源冲突

# 服务器错误
500 Internal Server Error - 服务器内部错误
503 Service Unavailable - 服务不可用

#2. 响应格式

{
  "status": "success",
  "data": {
    "id": 1,
    "name": "张三",
    "email": "zhangsan@example.com"
  },
  "meta": {
    "timestamp": "2026-03-12T14:30:00Z",
    "version": "v1"
  }
}

#3. 错误响应

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "邮箱格式不正确",
  "details": {
    "field": "email",
    "reason": "必须为有效的邮箱地址"
  },
  "meta": {
    "timestamp": "2026-03-12T14:30:00Z",
    "requestId": "req_123456"
  }
}

#分页与过滤

#1. 分页参数

GET /api/v1/users?page=2&limit=20&sort=name&order=asc

#2. 分页响应

{
  "status": "success",
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "pages": 8,
    "hasNext": true,
    "hasPrev": true
  },
  "links": {
    "self": "/api/v1/users?page=2&limit=20",
    "first": "/api/v1/users?page=1&limit=20",
    "prev": "/api/v1/users?page=1&limit=20",
    "next": "/api/v1/users?page=3&limit=20",
    "last": "/api/v1/users?page=8&limit=20"
  }
}

#3. 过滤与搜索

# 精确匹配
GET /api/v1/users?status=active

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

# 模糊搜索
GET /api/v1/users?q=张三

# 多条件
GET /api/v1/users?status=active&role=admin&sort=createdAt&order=desc

#版本管理

#1. URI 版本化

# 路径版本
/api/v1/users
/api/v2/users

# 查询参数版本（不推荐）
/api/users?version=1

#2. 头部版本

GET /api/users
Accept: application/vnd.example.v1+json

#3. 版本策略

• 保持向后兼容
• 弃用旧版本时提供足够过渡期
• 文档化版本变更

#安全设计

#1. 认证

# Bearer Token
Authorization: Bearer {token}

# API Key
X-API-Key: {api_key}

#2. 授权

• 基于角色的访问控制（RBAC）
• 基于资源的访问控制
• 细粒度权限控制

#3. 速率限制

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1617032400

#4. CORS 配置

// Express.js 示例
app.use(cors({
  origin: ['https://example.com'],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  maxAge: 86400 // 24小时
}));

#文档与测试

#1. API 文档工具

• OpenAPI/Swagger：标准 API 描述格式
• Postman：API 测试与文档
• Redoc：OpenAPI 文档生成器

#2. OpenAPI 示例

openapi: 3.0.0
info:
  title: 用户管理 API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

#3. 测试策略

• 单元测试：验证业务逻辑
• 集成测试：验证 API 端点
• 性能测试：验证响应时间
• 安全测试：验证安全漏洞

#最佳实践

#1. 设计原则

• 保持简单直观
• 遵循约定优于配置
• 提供清晰的错误信息
• 支持内容协商

#2. 性能优化

• 启用 HTTP 缓存
• 使用 ETag 和 Last-Modified
• 实现分页和懒加载
• 压缩响应数据

#3. 监控与日志

• 记录所有 API 请求
• 监控响应时间和错误率
• 设置告警阈值
• 分析 API 使用模式

#常见反模式

#1. 避免的操作

# ❌ 错误：使用动词
/getAllUsers
/createUser
/updateUser/{id}

# ✅ 正确：使用名词和 HTTP 方法
GET /users
POST /users  
PUT /users/{id}

#2. 避免过度设计

• 不要过早优化
• 避免过度抽象
• 保持 API 简单可用

#总结

设计良好的 RESTful API 需要遵循统一接口、无状态、可缓存等核心原则。合理的资源设计、正确的 HTTP 方法使用、清晰的响应格式和严格的安全控制是构建高质量 API 的关键。

创建时间：2026-03-12 分类：前端网络 标签：RESTful, API设计, 网络协议, 后端开发