api

API 开发技能

本技能提供 RESTful API 开发的最佳实践和模式。

触发条件

• 创建 API 端点
• 设计 REST API
• 实现后端路由
• 处理请求/响应
• API 版本控制

RESTful 设计原则

URL 设计

# 资源命名 - 使用名词复数
GET    /api/v1/users           # 获取用户列表
GET    /api/v1/users/:id       # 获取单个用户
POST   /api/v1/users           # 创建用户
PUT    /api/v1/users/:id       # 更新用户（完整替换）
PATCH  /api/v1/users/:id       # 更新用户（部分更新）
DELETE /api/v1/users/:id       # 删除用户

# 嵌套资源
GET    /api/v1/users/:id/orders           # 用户的订单
GET    /api/v1/users/:id/orders/:orderId  # 用户的特定订单

# 动作资源
POST   /api/v1/users/:id/activate         # 激活用户
POST   /api/v1/orders/:id/cancel          # 取消订单

HTTP 方法语义

方法	语义	幂等	安全
GET	读取资源	✅	✅
POST	创建资源	❌	❌
PUT	完整更新	✅	❌
PATCH	部分更新	❌	❌
DELETE	删除资源	✅	❌

统一响应格式

成功响应

// 单个资源
{
  "success": true,
  "data": {
    "id": "123",
    "name": "张三",
    "email": "[email protected]"
  }
}

// 列表资源
{
  "success": true,
  "data": [
    { "id": "1", "name": "用户1" },
    { "id": "2", "name": "用户2" }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 100,
    "totalPages": 5
  }
}

// 创建成功
{
  "success": true,
  "data": { "id": "123", ... },
  "message": "创建成功"
}

错误响应

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "请求参数无效",
    "details": [
      { "field": "email", "message": "邮箱格式不正确" },
      { "field": "age", "message": "年龄必须大于 0" }
    ]
  }
}

API 路由实现

各框架的完整 CRUD 路由实现：

详见 Next.js API Patterns - App Router + Zod 验证 + 认证授权

详见 FastAPI Patterns - Pydantic 模型 + 异步路由

详见 Express.js Patterns - express-validator + 中间件

查询参数处理

分页

interface PaginationParams {
  page?: number;
  pageSize?: number;
  cursor?: string; // 游标分页
}

// 偏移分页
const { page = 1, pageSize = 20 } = query;
const skip = (page - 1) * pageSize;

// 游标分页（大数据量推荐）
const { cursor, pageSize = 20 } = query;
const where = cursor ? { id: { gt: cursor } } : {};