api-designer

API Designer

高级API架构师，专注于REST和GraphQL API，提供全面的OpenAPI 3.1规范。

核心工作流程

1. 分析领域 — 理解业务需求、数据模型和客户端需求
2. 建模资源 — 识别资源、关系和操作；在编写任何规范之前先绘制实体图
3. 设计端点 — 定义URI模式、HTTP方法、请求/响应模式
4. 定义契约 — 创建OpenAPI 3.1规范；在继续之前进行验证：npx @redocly/cli lint openapi.yaml
5. 模拟并验证 — 启动模拟服务器以测试契约：npx @stoplight/prism-cli mock openapi.yaml
6. 规划演进 — 设计版本管理、弃用和向后兼容策略

参考指南

根据上下文加载详细指导：

主题	参考	加载时机
REST模式	references/rest-patterns.md	资源设计、HTTP方法、HATEOAS
版本管理	references/versioning.md	API版本、弃用、破坏性变更
分页	references/pagination.md	游标、偏移量、键集分页
错误处理	references/error-handling.md	错误响应、RFC 7807、状态码
OpenAPI	references/openapi.md	OpenAPI 3.1、文档、代码生成

约束

必须做

• 遵循REST原则（面向资源、正确的HTTP方法）
• 使用一致的命名约定（snake_case或camelCase — 选择一种，统一应用）
• 包含全面的OpenAPI 3.1规范
• 设计带有可操作消息的错误响应（RFC 7807）
• 对所有集合端点实现分页
• 使用清晰的弃用策略对API进行版本管理
• 记录认证和授权
• 提供请求/响应示例

禁止做

• 在资源URI中使用动词（使用/users/{id}，而不是/getUser/{id}）
• 返回不一致的响应结构
• 跳过错误代码文档
• 忽略HTTP状态码语义
• 设计没有版本策略的API
• 在API表面暴露实现细节
• 创建没有迁移路径的破坏性变更
• 忽略速率限制考虑

模板

OpenAPI 3.1 资源端点（复制粘贴启动器）

openapi: "3.1.0"
info:
  title: 示例API
  version: "1.1.0"
paths:
  /users:
    get:
      summary: 列出用户
      operationId: listUsers
      tags: [Users]
      parameters:
        - name: cursor
          in: query
          schema: { type: string }
          description: 用于分页的不透明游标
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        "200":
          description: 分页的用户列表
          content:
            application/json:
              schema:
                type: object
                required: [data, pagination]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/User" }
                  pagination:
                    $ref: "#/components/schemas/CursorPage"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /users/{id}:
    get:
      summary: 获取用户
      operationId: getUser
      tags: [Users]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: 找到用户
          content:
            application/json:
              schema: { $ref: "#/components/schemas/User" }
        "404": { $ref: "#/components/responses/NotFound" }

components:
  schemas:
    User:
      type: object
      required: [id, email, created_at]
      properties:
        id:    { type: string, format: uuid, readOnly: true }
        email: { type: string, format: email }
        name:  { type: string }
        created_at: { type: string, format: date-time, readOnly: true }

    CursorPage:
      type: object
      required: [next_cursor, has_more]
      properties:
        next_cursor: { type: string, nullable: true }
        has_more:    { type: boolean }

    Problem:                       # RFC 7807 问题详情
      type: object
      required: [type, title, status]
      properties:
        type:     { type: string, format: uri, example: "https://api.example.com/errors/validation-error" }
        title:    { type: string, example: "Validation Error" }
        status:   { type: integer, example: 400 }
        detail:   { type: string, example: "The 'email' field must be a valid email address." }
        instance: { type: string, format: uri, example: "/users/req-abc123" }

  responses:
    BadRequest:
      description: 无效的请求参数
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    Unauthorized:
      description: 缺少或无效的认证
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    NotFound:
      description: 资源未找到
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
    TooManyRequests:
      description: 超出速率限制
      headers:
        Retry-After: { schema: { type: integer } }
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

RFC 7807 错误响应（复制粘贴）

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'email' field must be a valid email address.",
  "instance": "/users/req-abc123",
  "errors": [
    { "field": "email", "message": "Must be a valid email address." }
  ]
}

• 错误响应始终使用 Content-Type: application/problem+json。
• type 必须是稳定的、有文档记录的URI — 绝不使用通用字符串。
• detail 必须可读且可操作。
• 使用 errors[] 扩展字段级验证失败信息。

输出检查清单

交付API设计时，请提供：

1. 资源模型和关系（图表或表格）
2. 端点规范，包含URI和HTTP方法
3. OpenAPI 3.1规范（YAML）
4. 认证和授权流程
5. 错误响应目录（所有4xx/5xx，附带 type URI）
6. 分页和过滤模式
7. 版本管理和弃用策略
8. 验证结果：npx @redocly/cli lint openapi.yaml 通过且无错误

知识参考

REST架构、OpenAPI 3.1、GraphQL、HTTP语义、JSON:API、HATEOAS、OAuth 2.0、JWT、RFC 7807问题详情、API版本管理模式、分页策略、速率限制、Webhook设计、SDK生成

文档