Schema驱动API设计


Schema 驱动API设计工作流程：将Schema（数据结构或模式）置于开发过程的中心。
让”数据结构Schema“成为团队之间沟通的纽带，并创建一个共享框架来理解正在实施的各种系统。

Schema本质上是描述 API 的元数据文档。它定义了系统的输入和输出，同时消除了歧义。如果使用得当，它可以为 API 与其使用者之间的契约奠定基础。

下面是一个 OpenAPI [1]架构示例，描述了 RESTful API 的运行状况检查端点：

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
paths:
  /health:
    get:
      summary: Health Check
      description: Check the health of the API
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '500':
          description: API is experiencing issues

components:
  schemas:
    HealthResponse:
      type: object
      properties:
        database:
          $ref: '#/components/schemas/HealthStatus'
        vendor:
          $ref: '#/components/schemas/HealthStatus'
      required:
        - database
        - vendor
    HealthStatus:
      type: string
      enum: [healthy, offline]

  • /health定义附有summary和description。
  • schema 描述了请求成功时的预期正文。
  • 描述了一个HealthStatus组件，该组件是一个字符串，有healthy 和offline两种可能的值。

虽然这只是一个虚构的示例，但它确实说明了您可以在schema 中期望的详细程度。

Schema 驱动工作流程的一些关键方面包括：

  • 单一事实来源：所有相关方，包括 API、客户端团队和其他利益相关者，都应依赖架构作为系统之间输入和输出数据结构的真实定义。
  • 更轻松的并行开发。团队无需等待 API 完全实现即可开始工作。他们可以使用架构生成代码、存根或模拟数据，以在 API 不可用时模拟 API 行为。如果合同发生变化，构建错误将表明需要进行必要的调整以支持新合同。
  • 契约测试：该模式作为契约测试的基础，API 提供者和客户端验证其实现是否符合商定的模式。
  • 版本控制：您可以获得版本控制带来的所有好处。您可以使用 git commit 哈希或标签来标识架构的特定版本。当需求发生变化时，可以使用与管理代码相同的变更控制流程来更新架构。这使既得利益方有机会使用他们熟悉的相同代码审查流程来审查架构并提供反馈。

总而言之，有许多工具可以帮助您为 API 定义架构并实施Schema 驱动的工作流程。这些生态系统有足够的时间来发展，可用的工具也相当熟练。