用途
rest-ops 是一份 RESTful API 设计的快速参考，用于在设计和评审接口时快速查阅 HTTP 语义、资源建模、状态码选择以及缓存与限流相关做法。该技能在以下情形触发：rest api、http methods、status codes、api design 等。
主要能力
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?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 |
使用方式
该技能以参考文档形式提供。在需要时加载对应详细资料：
- ./references/status-codes.md——完整状态码参考（含示例）
- ./references/caching-patterns.md——Cache-Control、ETag、CDN 模式
- ./references/rate-limiting.md——限流策略与相关头
- ./references/response-formats.md——错误、版本控制、批量操作、HATEOAS
适用场景
- 设计新的 API 端点
- 选择 HTTP 方法与状态码
- 实现缓存头
- 设置限流
- 组织错误响应结构
限制
本资料未提供关于具体语言/框架实现、版本兼容性或工具集成的说明，暂未提供。