2. OpenAPI 参数校验基础：参数校验的必要性、常见校验规则

在异步导出任务中，客户端提交的请求参数是触发整个导出流程的起点。如果参数在入口处未经校验便直接进入业务逻辑，轻则导致导出任务执行失败、浪费计算资源，重则引发系统异常甚至数据泄露。OpenAPI 规范下的参数校验，是构建容错体系的第一道防线。

2.1 参数校验的必要性

参数校验并非“锦上添花”，而是生产环境的刚性需求。其核心价值体现在以下四个维度：

2.2 常见校验规则详解

OpenAPI 3.0 规范中，参数校验规则通过 schema 对象定义。以下是在异步导出接口中最常用的五类校验规则，按优先级从高到低排列。

2.2.1 必填校验（Required）

最基础的校验规则。对于异步导出任务，以下参数通常标记为必填：

• 导出类型（exportType）：决定导出的是用户数据、订单数据还是日志数据。
• 时间范围（startTime / endTime）：限定导出数据的起止时间。
• 文件格式（fileFormat）：指定导出文件为 CSV、Excel 或 PDF。

2.2.2 类型校验（Type）

确保参数值的数据类型与预期一致。常见类型及校验要点：

2.2.3 长度校验（Length / Size）

对字符串和数组类型的参数进行长度约束，防止资源滥用。

• 字符串长度：使用 minLength 和 maxLength。例如，导出文件名前缀限制为 1~50 个字符。
• 数组元素个数：使用 minItems 和 maxItems。例如，导出字段列表至少包含 1 个字段，最多 100 个字段。
• 数值范围：使用 minimum 和 maximum。例如，导出行数上限最小为 1，最大为 100000。

# OpenAPI 3.0 示例：导出参数的长度与范围校验
parameters:
  - name: maxRows
    in: query
    schema:
      type: integer
      minimum: 1
      maximum: 100000
    description: 导出行数上限（1~100000）
  - name: fields
    in: query
    schema:
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 100
    description: 导出字段列表（至少1个，最多100个）

2.2.4 枚举校验（Enum）

当参数值只能从预定义集合中选择时，使用枚举校验。这是异步导出接口中防止“非法导出类型”的关键手段。

2.2.5 正则校验（Pattern）

用于对字符串格式进行精确约束，在异步导出中常用于以下场景：

• 日期格式：^\d{4}-\d{2}-\d{2}$（如 2025-03-15）
• 时间戳格式：^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$（ISO 8601）
• 邮箱格式：^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$（导出结果通知邮箱）
• 文件名安全校验：^[a-zA-Z0-9_-]+$（防止路径遍历攻击）

# OpenAPI 3.0 示例：日期与邮箱的正则校验
parameters:
  - name: startTime
    in: query
    schema:
      type: string
      pattern: '^\d{4}-\d{2}-\d{2}$'
    description: 导出起始日期，格式 yyyy-MM-dd
  - name: notifyEmail
    in: query
    schema:
      type: string
      pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    description: 导出完成通知邮箱

2.3 校验规则的组合使用

在实际的异步导出接口中，一个参数往往需要同时应用多条校验规则。例如：

• exportType：必填 + 枚举（USER_DATA / ORDER_DATA / LOG_DATA）
• startTime：必填 + 字符串类型 + 正则（日期格式）
• maxRows：可选 + 整数类型 + 最小值 1 + 最大值 100000
• fields：可选 + 数组类型 + 最少 1 项 + 最多 100 项 + 每项为字符串