name: rest-patterns
description: “RESTful API设计模式、HTTP语义、缓存和速率限制的快速参考。触发词：rest api、http方法、状态码、api设计、端点设计、api版本控制、速率限制、缓存头。”
allowed-tools: “Read Write”
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 Entity |
验证错误 |
| 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?page=2&limit=20 # 分页
GET /users?sort=created_at:desc # 排序
GET /users?role=admin # 过滤
安全检查清单
- [ ] 仅使用 HTTPS/TLS
- [ ] 使用 OAuth 2.0 或 JWT 进行认证
- [ ] 验证所有输入
- [ ] 对每个客户端进行速率限制
- [ ] 配置 CORS 头
- [ ] 不在 URL 中包含敏感数据
- [ ] 对敏感响应使用
no-store
常见错误
| 错误 |
修正 |
| URL 中使用动词 |
/getUsers → /users |
| 深层嵌套 |
扁平化或使用查询参数 |
| 用 200 表示错误 |
使用正确的 4xx/5xx 状态码 |
| 没有分页 |
始终对集合进行分页 |
| 缺少速率限制 |
防止滥用 |
快速参考
| 任务 |
模式 |
| 分页 |
?page=2&limit=20 |
| 排序 |
?sort=field:asc |
| 过滤 |
?status=active |
| 稀疏字段 |
?fields=id,name |
| 包含关联数据 |
?include=orders |
使用场景
- 设计新的 API 端点
- 选择 HTTP 方法和状态码
- 实现缓存头
- 设置速率限制
- 构建错误响应
扩展资源
如需详细模式，请加载：
./references/status-codes.md - 完整的状态码参考及示例./references/caching-patterns.md - Cache-Control、ETag、CDN 模式./references/rate-limiting.md - 速率限制策略和头信息./references/response-formats.md - 错误、版本控制、批量操作、HATEOAS