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

核心原则

1. 资源导向：URL 表示资源，不是动作
2. 无状态：每次请求包含所有必要信息
3. 统一接口：使用标准 HTTP 方法
4. 可缓存：合理利用缓存机制

URL 设计规范

✅ 正确做法

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

❌ 错误做法

GET    /getUsers
POST   /createUser
POST   /deleteUser
GET    /getUserById?id=123

HTTP 状态码使用

状态码	含义	使用场景
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	Server Error	服务器内部错误

响应格式规范

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

列表响应

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

错误响应

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

版本控制

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

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

分页、过滤、排序

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

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

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

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

安全最佳实践

1. HTTPS：生产环境必须使用
2. 认证：JWT/OAuth2
3. 限流：防止滥用
4. 输入验证：防止注入攻击
5. 敏感信息：不在 URL 中传递

遵循这些规范，你的 API 会更专业、更易用！