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

核心原则

RESTful API 遵循资源导向的设计哲学，使用标准 HTTP 方法操作资源。

HTTP 方法语义

• GET：获取资源
• POST：创建资源
• PUT：更新资源（全量）
• PATCH：部分更新
• DELETE：删除资源

URL 设计规范

# 好
GET /users/123
POST /users
DELETE /users/123

# 避免
GET /getUser?id=123
POST /deleteUser

状态码使用

• 200：成功
• 201：创建成功
• 400：请求错误
• 401：未授权
• 403：禁止访问
• 404：资源不存在
• 500：服务器错误

响应格式

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

版本控制

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

分页与过滤

GET /users?page=1&limit=20&sort=-created_at

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