RESTful API 设计原则与实战

REST 核心原则

1. 资源导向

• 使用名词表示资源：/users, /articles
• 避免动词：❌ /getUsers ✅ /users
• 复数形式保持一致

2. HTTP 方法语义

GET    /users          # 获取列表
GET    /users/123      # 获取单个资源
POST   /users          # 创建资源
PUT    /users/123      # 完整更新
PATCH  /users/123      # 部分更新
DELETE /users/123      # 删除资源

3. 状态码正确使用

• 200 OK：成功
• 201 Created：创建成功
• 400 Bad Request：请求错误
• 401 Unauthorized：未授权
• 404 Not Found：资源不存在
• 500 Internal Server Error：服务器错误

实用设计技巧

过滤、排序、分页

GET /articles?category=tech&page=1&limit=20&sort=-createdAt

版本控制

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

响应格式统一

{
  "success": true,
  "data": {...},
  "message": "操作成功"
}

安全考虑

• 使用 HTTPS
• 实现认证授权（JWT/OAuth2）
• 速率限制
• 输入验证

好的 API 设计让集成更简单，维护更轻松。