3、参数校验失败场景分析

在异步导出接口中，参数校验失败是触发频率最高的错误类型。与同步接口不同，异步导出在参数校验失败时，系统尚未创建导出任务，因此响应中不应包含 taskId 或 exportUrl。本节将四种典型校验失败场景拆解为独立分析，帮助设计者在 OpenAPI 规范中精准定义每种场景的响应结构。

3.1 必填参数缺失

必填参数缺失是最基础的校验失败场景。在异步导出中，常见的必填参数包括 exportType（导出类型）、format（文件格式）以及业务标识如 projectId。当请求体中缺少这些字段时，API 应返回 400 Bad Request，并在响应体中明确指明缺失的字段路径。

3.2 参数类型错误

当传入的参数值与 OpenAPI 规范中定义的 type 不匹配时，触发类型错误。例如 exportType 期望 string 但传入 integer，或 pageSize 期望 integer 但传入 string。类型错误在异步导出中尤其需要关注，因为导出参数往往涉及枚举值或数值范围。

// 类型错误示例：exportType 应为 string，实际传入 integer
POST /api/v1/exports
Content-Type: application/json

{
  "exportType": 12345,
  "format": "csv",
  "projectId": "proj-abc"
}

// 响应
{
  "error": {
    "code": "VALIDATION_TYPE_ERROR",
    "message": "参数类型错误",
    "details": [
      {
        "field": "exportType",
        "expectedType": "string",
        "actualValue": 12345,
        "actualType": "integer"
      }
    ]
  }
}

3.3 参数格式错误

格式错误通常发生在字符串类型参数上，例如日期格式、邮箱格式、UUID 格式或自定义枚举值格式。在异步导出中，dateRange（日期范围）和 sortBy（排序字段）是格式错误的高发区。

3.4 参数范围越界

范围越界包括数值范围（如 pageSize 超过最大限制）、字符串长度范围（如 fileName 超过 255 字符）以及数组元素个数范围（如 selectedIds 超过 1000 个）。在异步导出中，pageSize 和 maxExportRows 是范围越界的典型参数。

// 范围越界示例：pageSize 超过最大允许值 1000
POST /api/v1/exports
Content-Type: application/json

{
  "exportType": "order_report",
  "format": "xlsx",
  "pageSize": 5000
}

// 响应
{
  "error": {
    "code": "VALIDATION_OUT_OF_RANGE",
    "message": "参数值超出允许范围",
    "details": [
      {
        "field": "pageSize",
        "value": 5000,
        "constraints": {
          "minimum": 1,
          "maximum": 1000
        }
      }
    ]
  }
}

3.5 四种场景的响应差异对比

下表从 code、details 结构、典型约束字段三个维度对比四种校验失败场景，便于在 OpenAPI 规范中为每种场景定义独立的 response 对象。