RESTful API 设计规范：从入门到实战

什么是 RESTful API？

REST（Representational State Transfer）是一种架构风格，核心思想：

• 资源导向：一切皆资源（用户、订单、文章）
• 无状态：每次请求包含完整信息
• 统一接口：用 HTTP 方法操作资源
• 可缓存：响应可缓存提升性能

核心设计原则

1. 使用名词，不用动词

❌ 错误：

/getUser
/createUser
/deleteUser

✅ 正确：

GET    /users
POST   /users
DELETE /users/{id}

资源用复数名词，表示集合。

2. HTTP 方法语义化

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

幂等性：多次执行结果相同。

3. 资源嵌套要适度

❌ 过度嵌套：

/users/123/orders/456/items/789

✅ 扁平化：

/users/123/orders
/orders/456/items
/items/789

或者用查询参数：

/orders?userId=123
/items?orderId=456

4. 过滤、排序、分页

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

# 排序
GET /users?sort=-createdAt  # 降序
GET /users?sort=name        # 升序

# 分页
GET /users?page=2&limit=20

# 字段选择
GET /users?fields=id,name,email

5. 版本控制

URL 版本（推荐）：

/api/v1/users
/api/v2/users

Header 版本：

Accept: application/vnd.api.v1+json

响应设计规范

成功响应

GET 单个资源：

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

GET 资源列表：

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

POST 创建资源：

{
  "data": {
    "id": "123",
    "createdAt": "2024-01-01T00:00:00Z"
  },
  "message": "创建成功"
}

错误响应

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

HTTP 状态码：

• 200：成功
• 201：创建成功
• 400：请求错误
• 401：未授权
• 403：禁止访问
• 404：资源不存在
• 422：参数验证失败
• 500：服务器错误

实战案例：博客系统 API

用户相关

# 注册用户
POST /api/v1/users
{
  "username": "zhangsan",
  "email": "zhangsan@example.com",
  "password": "secure123"
}

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

# 更新用户
PATCH /api/v1/users/123
{
  "bio": "全栈开发者"
}

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

文章相关

# 创建文章
POST /api/v1/articles
{
  "title": "我的第一篇文章",
  "content": "...",
  "tags": ["技术", "分享"]
}

# 获取文章列表
GET /api/v1/articles?authorId=123&status=published

# 获取单篇文章
GET /api/v1/articles/456

# 更新文章
PUT /api/v1/articles/456
{
  "title": "更新后的标题",
  "content": "..."
}

# 删除文章
DELETE /api/v1/articles/456

评论相关

# 添加评论
POST /api/v1/articles/456/comments
{
  "content": "写得很好！"
}

# 获取评论列表
GET /api/v1/articles/456/comments?page=1&limit=10

安全最佳实践

1. 认证与授权

# 使用 JWT
Authorization: Bearer <token>

# 或 API Key
X-API-Key: your-api-key

2. 速率限制

# 响应头告知限制
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

3. 输入验证

• 永远不要信任客户端输入
• 服务端验证所有参数
• 使用白名单而非黑名单

4. HTTPS 必须

生产环境必须使用 HTTPS，防止中间人攻击。

文档化

工具推荐：

• Swagger/OpenAPI
• Postman
• Redoc

文档应包含：

• 接口描述
• 请求参数
• 响应示例
• 错误码说明
• 认证方式

性能优化

1. 启用缓存：ETag、Last-Modified
2. 压缩响应：Gzip、Brotli
3. 按需返回字段：?fields=id,name
4. 异步处理：耗时操作返回任务 ID
5. CDN 加速：静态资源走 CDN

常见错误

❌ 在 URL 中使用动词 ❌ 混用多种响应格式 ❌ 错误码不统一 ❌ 没有版本控制 ❌ 文档滞后于代码

结语

好的 API 设计让开发者愉悦，坏的设计让人崩溃。遵循 RESTful 原则，保持一致性，你的 API 会被更多人喜爱。

---

你在 API 设计中遇到过什么坑？欢迎分享！