api-design@1.0.0

CLI 安装指南

通过 SkillSPAI CLI 一键安装到你的 AI 编码工具：

npm install -g skillspai

# Codex CLI
skillspai install api-design --target codex

# Claude Code
skillspai install api-design --target claude

# Cursor
skillspai install api-design --target cursor

# Windsurf
skillspai install api-design --target windsurf

# OpenCode
skillspai install api-design --target opencode

skillspai install api-design@1.0.0 --target claude

Skill 内容

# RESTful API 设计规范

## URL 设计

```
GET    /api/v1/users           # 列表
POST   /api/v1/users           # 创建
GET    /api/v1/users/:id       # 详情
PUT    /api/v1/users/:id       # 全量更新
PATCH  /api/v1/users/:id       # 部分更新
DELETE /api/v1/users/:id       # 删除
GET    /api/v1/users/:id/posts # 子资源列表
```

### 命名规则
- 使用 kebab-case：`/api/user-profiles` 不是 `/api/userProfiles`
- 用复数名词：`/users` 不是 `/user`
- 嵌套不超过两层：`/users/:id/posts` 可以，`/users/:id/posts/:pid/comments/:cid` 太深
- 操作用子资源：`POST /orders/:id/cancel` 优于 `POST /cancel-order`

## 版本管理

### URL 路径版本（推荐）
```
/api/v1/users
/api/v2/users
```

### Header 版本
```
Accept: application/vnd.myapp.v2+json
```

### 版本兼容原则
- 新增字段：向后兼容，不需要新版本
- 删除字段：必须新版本，旧版本保留至少 6 个月
- 修改字段语义：必须新版本

## 请求与响应

### 请求体
```json
{
  "name": "张三",
  "email": "zhangsan@example.com",
  "role": "admin"
}
```

### 成功响应
```json
// 单个资源
{
  "data": { "id": "abc123", "name": "张三" }
}

// 列表（带分页）
{
  "data": [...],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 150,
    "totalPages": 8
  }
}
```

### 错误响应
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "邮箱格式不正确",
    "details": [
      { "field": "email", "message": "必须是有效邮箱地址" }
    ]
  }
}
```

### HTTP 状态码
```
200 OK                  # 成功（GET、PUT、PATCH）
201 Created             # 创建成功（POST）
204 No Content          # 删除成功（DELETE）
400 Bad Request         # 请求参数错误
401 Unauthorized        # 未认证
403 Forbidden           # 无权限
404 Not Found           # 资源不存在
409 Conflict            # 冲突（重复创建）
422 Unprocessable       # 业务校验失败
429 Too Many Requests   # 限流
500 Internal Error      # 服务端错误
```

## 分页

### 查询参数
```
GET /api/v1/users?page=1&size=20&sort=created_at&order=desc
GET /api/v1/users?search=张三&role=admin
```

### 游标分页（大数据量推荐）
```
GET /api/v1/users?cursor=abc123&limit=20

// 响应
{
  "data": [...],
  "cursor": { "next": "def456", "hasMore": true }
}
```

## 认证

### Bearer Token
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

### API Key
```
X-API-Key: sk-xxxxxxxxxxxx
```

### Token 设计
- Access Token: 短有效期（15-30 分钟）
- Refresh Token: 长有效期（7-30 天），用于刷新 Access Token
- Token 刷新不应要求重新登录

## 限流

### 响应头
```
X-RateLimit-Limit: 100        # 窗口内总配额
X-RateLimit-Remaining: 95     # 剩余次数
X-RateLimit-Reset: 1609459200 # 重置时间戳
```

### 429 响应
```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "请求过于频繁，请稍后再试",
    "retryAfter": 30
  }
}
```

## 过滤与搜索

```
# 精确过滤
GET /api/v1/users?role=admin&status=active

# 模糊搜索
GET /api/v1/users?search=张三

# 范围查询
GET /api/v1/orders?min_amount=100&max_amount=500
GET /api/v1/orders?created_after=2024-01-01

# 字段选择
GET /api/v1/users?fields=id,name,email
```

## 常见错误

- ❌ 用动词命名：`/api/getUsers` → ✅ 用名词 + HTTP 方法
- ❌ 返回 200 + 错误信息 → ✅ 返回正确的 HTTP 状态码
- ❌ 错误格式不统一 → ✅ 统一 error 响应结构
- ❌ 不分页返回全量数据 → ✅ 默认分页，最大限制 100
- ❌ 密码在响应中返回 → ✅ 敏感字段不返回
- ❌ 用 DELETE 返回删除的对象 → ✅ 返回 204 No Content