3. 报表导出场景分析：常见报表导出格式与关键交互点

在契约测试驱动报表导出回放场景中，理解不同导出格式的技术特性与流程中的关键交互点，是设计有效契约的基础。本章将系统分析 CSV、Excel、PDF 三种主流格式的导出场景，并拆解导出流程中必须被契约覆盖的交互节点。

3.1 常见报表导出格式对比

不同导出格式在数据结构、渲染方式、文件体积与使用场景上存在显著差异。下表从契约测试视角对比三种格式的核心特征：

3.2 导出流程中的关键交互点

一次完整的报表导出请求，从前端触发到文件下载，通常经历 5 个核心阶段。每个阶段都包含一个或多个必须被契约覆盖的交互点。

3.2.1 导出流程总览

下图展示了报表导出请求的端到端流程，并标注了契约测试必须覆盖的交互节点（用深色节点标识）：

3.2.2 各交互点详细说明

以下按阶段拆解每个交互点的契约测试要点：

1. 请求提交（前端 → 后端 API）
   • 契约内容：请求方法、路径、请求头（Authorization、Accept）、请求体结构（报表ID、导出格式、时间范围）。
   • 典型契约断言：当请求缺少必要字段时，返回 400 错误；当认证过期时，返回 401。
2. 参数校验（后端内部）
   • 契约内容：导出格式枚举值校验、时间范围逻辑校验（结束时间不得早于开始时间）、数据权限校验。
   • 典型契约断言：传入非法格式字符串时，返回 422 并附带支持的格式列表。
3. 数据查询（后端 → 数据源）
   • 契约内容：查询 SQL 或 API 调用的入参、返回字段结构、分页参数、超时阈值。
   • 典型契约断言：数据源返回空结果集时，导出文件应包含表头但不包含数据行。
4. 文件生成（后端 → 文件引擎）
   • 契约内容：文件引擎的输入数据结构、输出文件格式约束（如 CSV 分隔符、Excel 单元格类型、PDF 页面尺寸）。
   • 典型契约断言：生成的文件 MIME 类型正确，文件头魔数（Magic Number）匹配预期格式。
5. 文件传输（后端 → 前端 / 存储）
   • 契约内容：直接下载时的响应头（Content-Disposition、Content-Length）、异步导出时的回调 URL 或下载链接结构。
   • 典型契约断言：下载链接在指定时间内有效，文件 MD5 与响应头中的校验值一致。

3.3 格式特定交互点深度分析

除了通用流程，每种导出格式在文件生成阶段存在独特的交互点，这些点往往是契约测试最容易遗漏的地方。

3.3.1 CSV 导出关键交互点

• 字段分隔符： 默认逗号，但部分场景要求使用制表符或分号。契约需验证分隔符一致性。
• 文本限定符： 当字段内包含逗号或换行符时，必须使用双引号包裹。契约需验证转义逻辑。
• 字符编码： 常见为 UTF-8 或 GBK。契约需验证文件头 BOM 标记（如 UTF-8 BOM）。
• 空值处理： 空字段应输出空字符串而非 "null" 或 "NULL"。契约需验证空值表示。

// CSV 导出契约示例（Pact 风格）
{
  "interaction": {
    "description": "导出 CSV 报表时字段包含逗号",
    "request": {
      "method": "GET",
      "path": "/api/reports/123/export",
      "query": { "format": "csv" }
    },
    "response": {
      "status": 200,
      "headers": {
        "Content-Type": "text/csv; charset=utf-8",
        "Content-Disposition": "attachment; filename=\"report_123.csv\""
      },
      "body": "id,name,description\n1,\"Product A, Deluxe\",\"Description with, comma\"\n2,\"Product B\",\"Simple\""
    }
  }
}

3.3.2 Excel 导出关键交互点

• 单元格数据类型： 数字、日期、字符串、布尔值必须使用正确的单元格类型写入。契约需验证日期格式（如 yyyy-MM-dd）。
• 合并单元格： 表头合并区域的定义。契约需验证合并范围与内容。
• 公式与计算结果： 如果导出包含公式，契约需验证公式字符串与缓存的计算结果。
• 样式元数据： 字体、颜色、边框、对齐方式。契约可抽样验证关键单元格样式。

3.3.3 PDF 导出关键交互点

• 分页逻辑： 每页行数、分页符位置、跨页表头重复。契约需验证特定数据量下的分页结果。
• 字体嵌入： 中文字体必须嵌入或使用标准 CID 字体。契约需验证 PDF 中文字符可正常渲染。
• 页眉页脚： 页码、报表标题、生成时间。契约需验证页眉页脚内容与位置。
• 水印与安全： 机密水印、打印权限、密码保护。契约需验证安全策略是否生效。

3.4 交互点与契约测试的映射关系

下表将上述关键交互点映射到契约测试的三种常见类型，帮助你在实际项目中快速确定契约编写优先级：