2. OpenAPI 契约基础：规范、定义与模型

在 BFF 架构中，OpenAPI 契约是前后端协作的“语法书”。它使用标准化的 YAML 或 JSON 格式，精确描述 API 的端点、请求参数、响应结构以及数据模型。本章将系统讲解 OpenAPI 规范的核心概念，并演示如何通过契约定义来规避常见的慢查询与类型错误。

2.1 OpenAPI 规范（Swagger）简介

OpenAPI 规范（原 Swagger 规范）是一种用于描述 RESTful API 的机器可读接口定义语言。它通过一份契约文件，同时服务于开发者、测试工具和代码生成器。

2.2 YAML / JSON 定义 API 端点

OpenAPI 契约文件通常以 openapi.yaml 或 openapi.json 命名。YAML 因其可读性高，成为 BFF 团队的首选。以下是一个标准的端点定义结构：

openapi: "3.0.3"
info:
  title: "BFF 用户服务契约"
  version: "1.0.0"
  description: "为移动端和 Web 端提供统一的用户数据接口"

paths:
  /users/{userId}:
    get:
      summary: "获取用户详细信息"
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-f0-9]{24}$'
      responses:
        '200':
          description: "成功返回用户对象"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'

2.3 请求 / 响应模型定义

模型定义是契约校验的核心。通过 components/schemas，我们可以精确描述数据的形状、类型和约束，从而在 BFF 层提前拦截无效数据，避免将错误请求转发到下游服务。

components:
  schemas:
    UserResponse:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: string
          description: "用户唯一标识"
        name:
          type: string
          maxLength: 50
          description: "用户昵称"
        email:
          type: string
          format: email
          description: "邮箱地址"
        createdAt:
          type: string
          format: date-time
          description: "创建时间"
    CreateUserRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 50
        email:
          type: string
          format: email
        phone:
          type: string
          pattern: '^\+?[1-9]\d{1,14}$'

2.4 契约校验与慢查询的关联

在 BFF 层实施严格的 OpenAPI 契约校验，可以从源头减少无效请求对下游服务的冲击。以下表格总结了常见校验规则与性能收益：

2.5 契约文件组织最佳实践

对于大型 BFF 项目，建议将契约文件按领域拆分，并通过 $ref 引用公共模型，避免单文件过大导致维护困难。

• 按端点分组： paths/users.yaml、paths/orders.yaml
• 公共模型复用： components/schemas/common.yaml
• 参数与响应分离： components/parameters.yaml、components/responses.yaml