RESTful API 设计规范：命名、版本、状态码
良好的 API 设计是后端开发的基础。本文介绍 RESTful API 的设计规范。
URL 设计
名词而非动词
✅ GET /api/users
❌ GET /api/getUsers
✅ POST /api/users
❌ POST /api/createUser
复数名词
✅ GET /api/users
❌ GET /api/user
层级关系
GET /api/users/123/orders
GET /api/users/123/orders/456
HTTP 方法
| 方法 | 说明 | 示例 |
|---|---|---|
| GET | 查询 | GET /api/users |
| POST | 创建 | POST /api/users |
| PUT | 全量更新 | PUT /api/users/1 |
| PATCH | 部分更新 | PATCH /api/users/1 |
| DELETE | 删除 | DELETE /api/users/1 |
状态码
| 状态码 | 说明 |
|---|---|
| 200 | 成功 |
| 201 | 创建成功 |
| 204 | 删除成功 |
| 400 | 请求错误 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 未找到 |
| 500 | 服务器错误 |
响应格式
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"name": "张三"
}
}
分页
GET /api/users?page=1&size=10
{
"data": [...],
"total": 100,
"page": 1,
"size": 10
}
过滤和排序
GET /api/users?status=active&sort=create_time,desc
总结
良好的 API 设计让接口更易用、更易维护。遵循 RESTful 规范，可以设计出高质量的 API。