RESTful API 设计最佳实践：打造优雅的接口

核心原则

1. 资源导向

API 围绕资源设计，使用名词而非动词：

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

❌ GET /getUsers
❌ POST /createUser
❌ POST /deleteUser

2. 使用正确的 HTTP 方法

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

3. 合理的状态码

// 成功
200 OK          // 请求成功
201 Created     // 资源创建成功
204 No Content  // 成功但无返回内容

// 客户端错误
400 Bad Request      // 请求参数错误
401 Unauthorized     // 未认证
403 Forbidden        // 无权限
404 Not Found        // 资源不存在
409 Conflict         // 资源冲突
422 Unprocessable    // 数据验证失败
429 Too Many Requests // 请求过多

// 服务端错误
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable

URL 设计规范

使用复数名词

✅ /users
✅ /articles
❌ /user
❌ /article

嵌套资源表达关系

GET /users/123/articles      # 用户 123 的文章
GET /users/123/articles/456  # 用户 123 的第 456 篇文章

过滤、排序、分页

GET /users?role=admin&status=active
GET /users?sort=-created_at&page=2&limit=20
GET /users?fields=id,name,email

响应格式设计

统一响应结构

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "John",
    "email": "john@example.com"
  },
  "meta": {
    "timestamp": "2026-03-22T19:30:00Z",
    "requestId": "req_abc123"
  }
}

列表响应

{
  "code": 0,
  "message": "success",
  "data": [
    {"id": 1, "name": "User1"},
    {"id": 2, "name": "User2"}
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

错误响应

{
  "code": 400,
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    },
    {
      "field": "password",
      "message": "Password must be at least 8 characters"
    }
  ]
}

版本控制

URL 版本（推荐）

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

Header 版本

Accept: application/vnd.myapi.v1+json

认证与授权

JWT Token

# 请求头
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Key

# 请求头
X-API-Key: your-api-key-here

安全最佳实践

1. 始终使用 HTTPS
2. 输入验证：服务端验证所有输入
3. 限流：防止滥用
4. 敏感数据脱敏：密码、token 等不返回
5. CORS 配置：限制跨域来源
6. 日志记录：记录关键操作，但不记录敏感信息

文档化

使用 OpenAPI/Swagger

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: 成功

性能优化

1. 分页：避免一次性返回大量数据
2. 字段选择：允许客户端指定返回字段
3. 缓存：使用 ETag、Last-Modified
4. 压缩：启用 Gzip/Brotli
5. CDN：静态资源走 CDN

总结

好的 API 设计让开发者愉悦，坏的 API 设计让人抓狂。遵循这些最佳实践，打造优雅的接口！