服务端与数据 / 进阶

OpenAPI 不只写文档：让契约参与请求校验

把 OpenAPI 作为可执行契约：定义统一错误结构、在边界校验输入、生成客户端类型，并在 CI 中检查破坏性变更。

9 分钟OpenAPI · Validation · Contract Testing · TypeScript

先让规范描述真实边界

长度、格式、枚举、是否允许额外字段都应写进契约。只写字段名和示例，生成出来的文档看似完整，实际无法承担校验。

EXAMPLE / 01OpenAPI

components:
  schemas:
    CreateUserInput:
      type: object
      additionalProperties: false
      required: [email, displayName]
      properties:
        email:
          type: string
          format: email
          maxLength: 254
        displayName:
          type: string
          minLength: 1
          maxLength: 50

在 HTTP 边界校验，不让脏数据进入业务层

请求校验失败统一返回 400 或 422，并提供稳定错误码和字段路径。业务层接收到的参数应已经完成基本形状校验，但唯一性、余额和权限仍属于业务规则，不能完全交给 Schema。

EXAMPLE / 02OpenAPI

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "请求参数不合法",
    "details": [
      { "path": "body.email", "reason": "format" }
    ]
  }
}

在 CI 阻止破坏性变更

对 OpenAPI 文件做语法和引用检查；与主分支规范比较，识别删除字段、收紧枚举等 breaking change；从规范生成 TypeScript 类型或 SDK，并检查生成结果是否更新；用契约测试验证关键响应确实符合 Schema。

新增可选字段通常是兼容变更；删除字段、改变类型或把可选改为必填，需要新版本或明确迁移窗口。