rest-ops

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              # List
POST   /users              # Create
GET    /users/{id}         # Get one
PUT    /users/{id}         # Replace
PATCH  /users/{id}         # Update
DELETE /users/{id}         # Delete

# Query parameters
GET /users?page=2&limit=20          # Pagination
GET /users?sort=created_at:desc     # Sorting
GET /users?role=admin               # Filtering

安全检查清单

• 仅使用 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