RESTful API 设计指南

REST 核心原则

REST (Representational State Transfer) 是一种架构风格，强调资源导向和无状态通信。

设计原则

1. 使用资源命名

✅ 好：/users, /articles, /comments ❌ 差：/getUsers, /createArticle

2. 正确使用 HTTP 方法

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

3. 状态码规范

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

版本控制

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

响应格式

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

分页和过滤

GET /users?page=1&limit=20&sort=created_at&order=desc
GET /articles?category=tech&status=published

安全考虑

1. 使用 HTTPS
2. 实现认证授权（JWT/OAuth2）
3. 限制请求频率
4. 输入验证和过滤

优雅 API 设计，让集成更简单！