RESTful API 设计指南：打造优雅的接口规范

REST 核心原则

REST（Representational State Transfer）是一种架构风格，核心思想是将资源通过 URL 定位，使用 HTTP 方法操作。

URL 设计规范

✅ 正确做法

GET    /users          # 获取用户列表
GET    /users/123      # 获取 ID 为 123 的用户
POST   /users          # 创建新用户
PUT    /users/123      # 更新用户（全量）
PATCH  /users/123      # 更新用户（部分）
DELETE /users/123      # 删除用户
GET    /users/123/orders  # 获取用户的订单

❌ 避免的做法

GET    /getUsers       # 动词不应出现在 URL 中
POST   /deleteUser     # 使用 HTTP 方法表达操作
GET    /user?id=123    # 资源应用路径参数

HTTP 状态码使用

状态码	含义	使用场景
200	OK	成功获取/更新
201	Created	资源创建成功
204	No Content	成功但无返回内容
400	Bad Request	请求参数错误
401	Unauthorized	未认证
403	Forbidden	无权限
404	Not Found	资源不存在
409	Conflict	资源冲突
422	Unprocessable Entity	数据验证失败
429	Too Many Requests	请求频率超限
500	Internal Server Error	服务器错误

响应格式规范

成功响应

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

列表响应（带分页）

{
  "code": 0,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}

错误响应

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

版本控制

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

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

过滤、排序、分页

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

# 排序
GET /users?sort=-created_at,name

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

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

认证与授权

JWT Token 认证

Authorization: Bearer <jwt_token>

API Key 认证

X-API-Key: your_api_key

限流策略

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

文档化

使用 OpenAPI/Swagger 规范：

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        200:
          description: 成功

安全最佳实践

1. 始终使用 HTTPS
2. 输入验证：服务端验证所有输入
3. 敏感数据脱敏：密码、token 不返回
4. CORS 配置：限制允许的源
5. 日志记录：记录所有请求但不记录敏感信息

结语

优秀的 API 设计让开发者愉悦，降低集成成本。遵循 REST 规范，保持一致性，提供清晰文档，是打造好 API 的关键。