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

REST 核心原则

REST（Representational State Transfer）是一种架构风格，遵循以下原则：

1. 资源导向：一切皆资源，用 URI 标识
2. 统一接口：使用标准 HTTP 方法
3. 无状态：每次请求包含完整信息
4. 可缓存：响应可被缓存提升性能

HTTP 方法语义

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

URI 设计规范

✅ 好的设计

GET    /users           # 获取用户列表
GET    /users/123       # 获取用户 123
POST   /users           # 创建新用户
PUT    /users/123       # 更新用户 123
DELETE /users/123       # 删除用户 123
GET    /users/123/posts # 获取用户 123 的文章

❌ 避免的设计

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

状态码使用

• 200 OK：请求成功
• 201 Created：资源创建成功
• 204 No Content：成功但无返回内容
• 400 Bad Request：客户端请求错误
• 401 Unauthorized：未认证
• 403 Forbidden：无权限
• 404 Not Found：资源不存在
• 429 Too Many Requests：请求过多
• 500 Internal Server Error：服务器错误

响应格式规范

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "John",
    "email": "john@example.com"
  },
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 100
  }
}

版本控制

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

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

过滤、排序、分页

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

安全最佳实践

1. 始终使用 HTTPS
2. 使用 JWT/OAuth2 认证
3. 实现速率限制
4. 输入验证和过滤
5. 敏感信息不返回

总结

遵循 RESTful 规范，你的 API 会更易理解、易维护、易扩展。一致性是关键！