RESTful API设计最佳实践指南

路由设计、HTTP状态码、版本控制与完整规范

📅 2026年4月6日 · 阅读约10分钟 · API设计REST后端开发

REST（Representational State Transfer）是Web API设计的事实标准。一个好的RESTful API不仅让前端开发者用起来舒服，还能降低维护成本、提高系统的可扩展性。然而，很多开发者对REST的理解停留在"用JSON返回数据"的层面，忽略了其核心设计原则。本指南将系统性地介绍RESTful API的设计规范和最佳实践。

一、REST核心原则

• 资源导向：一切皆资源，用URL（URI）标识资源，用名词而非动词
• 统一接口：使用标准HTTP方法（GET/POST/PUT/DELETE/PATCH）操作资源
• 无状态：每个请求包含处理所需的所有信息，服务器不保存客户端状态
• 分层系统：客户端不需要知道直接连接的是终端服务器还是中间代理
• 可缓存：响应应明确标识是否可缓存，提高效率

二、URL路由设计

2.1 使用名词复数

✅ 推荐:
GET    /api/users          # 获取用户列表
GET    /api/users/123      # 获取单个用户
POST   /api/users          # 创建用户
PUT    /api/users/123      # 替换用户
DELETE /api/users/123      # 删除用户

❌ 避免:
GET    /api/getUsers
POST   /api/createUser
GET    /api/user/123       # 用单数

2.2 资源嵌套不超过两层

✅ 推荐:
GET /api/users/123/orders          # 用户的订单
GET /api/orders?userId=123         # 更好的替代方案

❌ 避免:
GET /api/users/123/orders/456/items/789/details  # 嵌套过深

2.3 使用查询参数处理过滤、排序和分页

GET /api/users?role=admin&status=active     # 过滤
GET /api/users?sort=-createdAt,name         # 排序（-表示降序）
GET /api/users?page=2&limit=20              # 分页
GET /api/users?fields=id,name,email         # 字段选择
GET /api/users?search=张三                  # 搜索

# 组合使用
GET /api/products?category=electronics&minPrice=100&maxPrice=500&sort=-price&page=1&limit=10

三、HTTP方法正确使用

PUT vs PATCH

# PUT - 客户端必须发送完整的资源
PUT /api/users/123
{
  "name": "张三",
  "email": "zhangsan@example.com",
  "age": 28,
  "role": "admin"
}

# PATCH - 只发送需要修改的字段
PATCH /api/users/123
{
  "age": 29
}

四、HTTP状态码

正确使用状态码是RESTful API的基本功。不要所有响应都返回200。

五、统一响应格式

// 成功响应
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com"
  }
}

// 分页响应
{
  "code": 200,
  "data": {
    "items": [...],
    "pagination": {
      "page": 2,
      "limit": 20,
      "total": 156,
      "totalPages": 8
    }
  }
}

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

六、API版本控制

// 方式一：URL路径版本（推荐）
GET /api/v1/users
GET /api/v2/users

// 方式二：请求头版本
GET /api/users
Accept: application/vnd.myapi.v2+json

// 方式三：查询参数版本
GET /api/users?version=2

七、安全最佳实践

• HTTPS：所有API必须使用HTTPS传输
• 认证：使用JWT或OAuth 2.0进行身份认证
• 限流：实施请求限流防止滥用
• 输入验证：服务端必须验证所有输入，不信任客户端
• CORS：正确配置跨域策略
• 敏感数据：不在URL中传递密码、Token等敏感信息
• HATEOAS：响应中包含相关资源链接，提高API可发现性

八、API文档

好的API文档是团队协作的基础。推荐使用OpenAPI（Swagger）规范编写文档，配合Swagger UI提供交互式文档。自动化文档工具如Springdoc、NestJS Swagger等可以根据代码注解自动生成文档，减少维护成本。