
关于
应用 REST API 设计模式,涵盖版本控制、分页、错误处理、HATEOAS 和限流。
name: rest-ops description: "RESTful API 设计模式、HTTP 语义、缓存和速率限制快速参考。触发条件:rest api、http methods、status codes、api design、endpoint design、api versioning、rate limiting、caching headers。" license: MIT allowed-tools: "Read Write" metadata: author: claude-mods
REST 模式
RESTful API 设计模式和 HTTP 语义快速参考。
HTTP 方法
| 方法 | 用途 | 幂等 | 可缓存 | |--------|---------|------------|-----------| | GET | 获取资源 | 是 | 是 | | POST | 创建新资源 | 否 | 否 | | PUT | 替换整个资源 | 是 | 否 | | PATCH | 部分更新 | 可能 | 否 | | DELETE | 删除资源 | 是 | 否 |
常用状态码
| 码 | 名称 | 用途 |
|------|------|-----|
| 200 | OK | 成功并返回内容 |
| 201 | Created | POST 成功(添加 Location 头) |
| 204 | No Content | 成功,无返回体 |
| 400 | Bad Request | 无效语法 |
| 401 | Unauthorized | 未认证 |
| 403 | Forbidden | 未授权 |
| 404 | Not Found | 资源不存在 |
| 422 | Unprocessable | 验证错误 |
| 429 | Too Many Requests | 被限流 |
| 500 | Server Error | 内部错误 |
资源设计
GET /users # 列表
POST /users # 创建
GET /users/{id} # 获取单个
PUT /users/{id} # 替换
PATCH /users/{id} # 更新
DELETE /users/{id} # 删除
GET /users/{id}/posts # 嵌套资源
命名规则
- 使用复数名词:
/users而非/user - 使用连字符:
/user-profiles而非/userProfiles - 避免动词:
POST /users而非POST /createUser - 嵌套表示所属关系:
/users/{id}/posts
分页
GET /users?page=2&per_page=20
GET /users?cursor=abc123&limit=20
响应头:
Link: <https://api.example.com/users?page=3>; rel="next"
X-Total-Count: 100
版本控制
| 方式 | 示例 | 优缺点 |
|------|------|--------|
| URL 路径 | /v1/users | 简单明确,但 URL 变化 |
| 请求头 | Accept: application/vnd.api+json;version=1 | 干净,但不直观 |
| 查询参数 | /users?version=1 | 灵活,但易被忽略 |
缓存头
Cache-Control: public, max-age=3600
ETag: "abc123"
Last-Modified: Wed, 15 Jan 2024 10:00:00 GMT
速率限制头
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800
Retry-After: 60
错误响应格式
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input",
"details": [
{ "field": "email", "message": "Must be a valid email" }
]
}
}

