API Design

API Design — API 设计技能

根据业务需求设计专业级 API，输出 OpenAPI 3.0 规范。

Goal

根据业务需求设计 RESTful/GraphQL API，输出 OpenAPI 规范文档。包含路由设计、请求/响应 Schema、错误码体系、版本策略

Trigger

• 用户要求"设计API"、"定义接口"、"写API文档"
  • 需要从数据库 Schema 推导 API 端点
  • 需要统一团队 API 规范

工作流程

业务需求 → 资源识别 → 路由设计 → Schema 定义 → 错误码 → 输出规范

Step 1: 资源识别

从需求中提取核心资源：

Step 2: 路由设计

遵循 RESTful 规范：

GET    /api/v1/{resources}          # 列表查询
POST   /api/v1/{resources}          # 创建资源
GET    /api/v1/{resources}/{id}     # 获取详情
PUT    /api/v1/{resources}/{id}     # 全量更新
PATCH  /api/v1/{resources}/{id}     # 部分更新
DELETE /api/v1/{resources}/{id}     # 删除资源

嵌套资源：

GET    /api/v1/users/{id}/orders   # 用户的订单列表

业务动作：

POST   /api/v1/orders/{id}/submit  # 提交订单
POST   /api/v1/orders/{id}/cancel  # 取消订单

设计原则

Step 3: 请求/响应 Schema

请求体设计

CreateUserRequest:
  type: object
  required: [email, name]
  properties:
    email:
      type: string
      format: email
      description: 用户邮箱
    name:
      type: string
      minLength: 2
      maxLength: 50
      description: 用户昵称
    role:
      type: string
      enum: [admin, user, guest]
      default: user

响应体设计

单个资源：

UserResponse:
  type: object
  properties:
    id:
      type: string
      format: uuid
    email:
      type: string
    name:
      type: string
    created_at:
      type: string
      format: date-time

列表响应（统一分页）：

PaginatedResponse:
  type: object
  properties:
    data:
      type: array
      items: { $ref: '#/components/schemas/UserResponse' }
    pagination:
      type: object
      properties:
        page: { type: integer }
        page_size: { type: integer }
        total: { type: integer }
        total_pages: { type: integer }

错误响应（统一格式）：

ErrorResponse:
  type: object
  properties:
    error:
      type: object
      properties:
        code: { type: string, example: "VALIDATION_ERROR" }
        message: { type: string, example: "邮箱格式不正确" }
        details:
          type: array
          items:
            type: object
            properties:
              field: { type: string }
              message: { type: string }

Step 4: 错误码体系

Step 5: 输出 OpenAPI 规范

输出完整的 openapi.yaml：

openapi: 3.0.3
info:
  title: {项目名称} API
  version: 1.0.0
  description: {API 描述}
servers:
  - url: /api/v1
paths:
  /users:
    get:
      summary: 获取用户列表
      tags: [用户管理]
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: page_size
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUserResponse'
components:
  schemas:
    ...（Schema 定义）
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []

质量检查清单

输出前确认：

• 所有资源使用复数名词
• 统一的分页、排序、过滤参数
• 统一的错误响应格式
• 每个端点有清晰的 summary 和 description
• 请求/响应 Schema 完整定义
• 认证方式统一（Bearer Token / API Key）
• 版本策略明确（URL path / Header）
• 幂等性设计（PUT/DELETE 幂等，POST 非幂等）

Example

用户: 设计一个博客系统的 API，包含文章、评论、用户

输出:
1. 资源识别: User, Post, Comment
2. 路由设计:
   GET    /api/v1/posts          # 文章列表
   POST   /api/v1/posts          # 创建文章
   GET    /api/v1/posts/{id}     # 文章详情
   GET    /api/v1/posts/{id}/comments  # 文章评论
3. 输出 openapi.yaml

参考资料

• OpenAPI 3.0 模板: references/openapi-template.yaml
• 错误码规范: references/error-codes.md