OpenAPI 工作流

1. 概述

在 SOLO 模式中，OpenAPI 规范（通常是 openapi.yaml 文件）是整个开发生命周期的“单一事实来源”(Single Source of Truth)。它像一份活的文档和契约，驱动着从需求分析到最终交付的每一个环节。

本工作流确保了 API-First 原则的彻底贯彻，使得团队协作高效、并行，且始终保持一致。

2. OpenAPI 在四阶段中的流转

a. PRODUCT 阶段：需求的输入

PRODUCT 阶段的产出物是清晰、结构化的用户故事或需求文档。虽然此阶段不直接编写 OpenAPI 规范，但其产出物必须包含足够的信息，以便 ARCHITECT 能够将其转化为精确的 API 设计。

• 关键产出:
  • 用户故事: "作为一个用户，我希望能创建一个新的账户..."
  • 数据需求: 创建账户需要 用户名, 邮箱, 密码。
  • 业务规则: 用户名 和 邮箱 必须是唯一的。

b. ARCHITECT 阶段：契约的诞生

ARCHITECT 阶段是 OpenAPI 契约诞生的地方。架构师将 PRODUCT 阶段的需求转化为机器可读、无歧义的 openapi.yaml 文件。

• 核心任务:

  1. 设计资源和路径: 将业务概念（如“用户”）映射为 RESTful 资源（/users）。
  2. 定义操作: 为资源设计 HTTP 方法（POST /users, GET /users/{id}）。
  3. 设计数据模型 (Schemas): 将数据需求转化为 JSON Schema，定义请求体和响应体的结构、类型和约束。
  4. 定义响应: 明确每个操作在成功和失败时的 HTTP 状态码和响应体。

• 示例 (openapi.yaml):

  paths:
    /users:
      post:
        summary: 创建新用户
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRequest'
        responses:
          '201':
            description: 用户创建成功
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/UserResponse'
  components:
    schemas:
      UserRequest:
        type: object
        properties:
          username:
            type: string
          email:
            type: string
            format: email

• 产出: 一份经过评审和确认的 openapi.yaml 文件。这份文件一旦确定，就成为后续所有工作的基石。

c. ENGINEER 阶段：契约的实现

ENGINEER 接收到 openapi.yaml 文件后，工作便围绕着这份契约展开。

• 核心任务:
  1. 生成代码框架: 使用 OpenAPI Generator 等工具，根据契约生成服务端接口、数据模型（DTOs）等样板代码。这确保了代码结构与 API 设计完全一致。
  2. 实现业务逻辑 (TDD): 遵循 SOLO-TDD 集成 流程，为每个 API 端点编写测试并实现其业务逻辑。开发过程中的所有输入输出都必须严格遵守生成的数据模型。
  3. 客户端开发 (并行): 与此同时，前端或其他服务消费者也可以基于同一份契约生成客户端代码，并使用 Mock 服务器进行开发，无需等待后端实现完成。

d. QA 阶段：契约的验证

QA 阶段的核心任务之一是验证最终的实现是否严格遵守了 OpenAPI 契约。

• 核心任务:
  1. 契约测试: 使用工具（如 Dredd, Schemathesis）将 openapi.yaml 文件与正在运行的 API 服务进行对比测试。自动化工具会发送请求并验证响应是否完全符合规范中定义的结构、类型和约束。
  2. 功能测试: 编写端到端的功能测试，验证业务逻辑是否按预期工作，这些测试的场景也源于 PRODUCT 阶段的需求。

3. 工作流优势

• 高度并行: 前后端、开发与测试可以基于共同的契约并行工作。
• 减少沟通成本: 机器可读的规范消除了口头沟通带来的歧义。
• 自动化: 大量代码、文档和测试用例可以自动生成。
• 质量内建: 从设计到验证，质量保证贯穿始终，而不是事后检查。