RESTful API 设计规范：从入门到最佳实践

REST 核心原则

REST（Representational State Transfer）是一种架构风格，核心是资源导向和无状态通信。

URL 设计规范

使用名词，不用动词

# ✅ 好
GET /users
POST /users
GET /users/123
PUT /users/123
DELETE /users/123

# ❌ 差
GET /getUsers
POST /createUser
POST /deleteUser/123

使用复数名词

# ✅ 好
/api/users
/api/articles

# ❌ 差
/api/user
/api/article

嵌套资源

GET /users/123/articles      # 用户的所有文章
GET /users/123/articles/456  # 用户的特定文章

HTTP 方法语义

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

状态码规范

成功响应

• 200 OK：GET/PUT/PATCH 成功
• 201 Created：POST 创建成功
• 204 No Content：DELETE 成功

客户端错误

• 400 Bad Request：请求参数错误
• 401 Unauthorized：未认证
• 403 Forbidden：无权限
• 404 Not Found：资源不存在
• 422 Unprocessable Entity：数据验证失败

服务端错误

• 500 Internal Server Error：服务器错误
• 503 Service Unavailable：服务不可用

响应格式

成功响应

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

错误响应

{
  "code": 400,
  "data": null,
  "message": "参数验证失败",
  "errors": [
    {"field": "email", "message": "邮箱格式不正确"}
  ]
}

版本控制

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

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

分页设计

GET /articles?page=2&limit=20

响应：

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

过滤、排序、搜索

# 过滤
GET /articles?status=published&category=tech

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

# 搜索
GET /articles?q=python 教程

# 字段选择
GET /articles?fields=id,title,created_at

安全最佳实践

1. 始终使用 HTTPS
2. 认证授权：JWT/OAuth2
3. 限流：防止滥用
4. 输入验证：防止注入攻击
5. 敏感数据脱敏：密码、token 不返回

文档化

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

openapi: 3.0.0
info:
  title: 用户 API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表

总结

遵循 RESTful 规范能让 API 更直观、易维护、易扩展。好的 API 设计是优秀后端工程的标志！