RESTful API 设计规范：从入门到精通

REST 核心原则

1. 资源导向：URL 表示资源，不是动作
2. 无状态：每次请求包含完整信息
3. 统一接口：用 HTTP 方法表达操作

URL 设计规范

✅ 正确示例

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

❌ 错误示例

GET    /getUsers
POST   /createUser
POST   /deleteUser/123

HTTP 状态码

状态码	含义	使用场景
200	OK	成功获取/更新
201	Created	资源创建成功
204	No Content	删除成功
400	Bad Request	参数错误
401	Unauthorized	未认证
403	Forbidden	无权限
404	Not Found	资源不存在
500	Server Error	服务器错误

响应格式

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三"
  },
  "timestamp": 1711008000
}

版本控制

URL 版本

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

Header 版本

Accept: application/vnd.api.v1+json

分页设计

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 100,
    "totalPages": 5
  }
}

安全考虑

1. 始终使用 HTTPS
2. 实现速率限制
3. 验证和过滤输入
4. 使用 OAuth2/JWT 认证

文档工具

• Swagger/OpenAPI
• Postman
• Redoc

结语

好的 API 设计让集成变得简单，坏的 API 让开发者痛苦。遵循规范，持续改进。