RESTful API 设计规范与最佳实践

REST 核心原则

1. 资源导向：URL 表示资源
2. 无状态：每次请求包含所有信息
3. 统一接口：使用标准 HTTP 方法

URL 设计规范

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

状态码使用

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

响应格式

{
  "code": 200,
  "data": { "id": 123, "name": "John" },
  "message": "success"
}

版本控制

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

安全考虑

• 使用 HTTPS
• 实现认证授权
• 限制请求频率
• 输入验证和过滤

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