4. 参数定义与校验：路径参数、查询参数、请求头参数、Cookie参数

在 OpenAPI 3.0 规范中，API 接口的参数定义是文档化与自动化校验的基石。本章聚焦于四种核心参数类型（路径、查询、请求头、Cookie）及其校验规则（required、schema、example），确保前后端契约清晰、安全合规。

4.1 参数类型与适用场景

不同参数类型在 URL 结构、传输位置与语义上存在显著差异。下表总结了它们的核心特征与典型用例：

4.2 参数校验规则：required、schema、example

OpenAPI 通过三个核心属性定义参数的校验约束：

• required：布尔值，标记该参数是否为必填。路径参数默认必填；查询参数、请求头参数、Cookie 参数默认可选。
• schema：定义参数的数据类型、格式、枚举、最小/最大值、正则模式等。支持 JSON Schema 子集。
• example：提供一个示例值，用于文档展示与客户端代码生成。可配合 examples 字段提供多个示例。

以下是一个完整的 OpenAPI 3.0 参数定义示例，涵盖四种参数类型：

paths:
  /users/{userId}/orders:
    get:
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 999999
          example: 42
          description: 用户唯一标识

        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [pending, shipped, delivered, cancelled]
          example: shipped
          description: 订单状态过滤

        - name: X-Request-Id
          in: header
          required: true
          schema:
            type: string
            pattern: '^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$'
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          description: 全链路追踪 ID

        - name: session_token
          in: cookie
          required: false
          schema:
            type: string
            minLength: 32
            maxLength: 128
          example: "sess_abc123def456..."
          description: 用户会话令牌

4.3 参数校验流程与后端断言

后端服务在接收到请求后，应按照 OpenAPI 定义的规则进行参数校验。下图展示了从请求解析到错误码断言的完整流程：

4.4 常见错误码断言清单

后端在参数校验失败时，应返回统一的错误码与描述，便于前端定位问题。以下为推荐的标准错误码断言表：

4.5 参数校验的 DevOps 集成

在 CI/CD 流水线中，参数校验规则应作为 API 契约的一部分进行自动化验证。下图展示了从 OpenAPI 文档到后端断言的 DevOps 集成架构：

4.6 参数定义与校验的常见陷阱

• 路径参数未设置 required：OpenAPI 中路径参数默认 required，但若显式设为 false，部分工具会忽略校验，导致运行时错误。
• schema 类型与 example 不匹配：example 值必须符合 schema 定义的类型与格式，否则会误导客户端开发者。
• Cookie 参数忽略安全属性：仅定义 schema 不够，后端应强制设置 HttpOnly、Secure、SameSite 等安全标志。
• 枚举值未同步：当业务状态新增时，需同步更新 OpenAPI 文档中的 enum 列表与后端校验逻辑，否则会导致合法请求被拒绝。
• 错误码不统一：不同团队使用不同的错误码格式（如 40001 vs PARAM_INVALID），增加前端适配成本。