---

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" }
    ]
  }
}