3. 证据报告基础：什么是证据报告、证据的类型（设计时、运行时、测试时）、证据的采集与存储、证据报告的标准格式

在 API 设计治理中，证据报告是连接设计规范、运行时行为与测试结果的唯一可信载体。没有证据，治理就是空谈；没有标准格式，证据就是噪音。本章从定义、分类、采集存储到标准格式，建立完整的证据报告知识体系。

3.1 什么是证据报告

证据报告是一份结构化、可追溯、可复现的数字化记录，用于证明 API 在特定时间点、特定环境下的设计合规性、运行正确性与测试覆盖度。它不仅是治理审计的输入，更是 Mock 隔离策略能否生效的判定依据。

3.2 证据的类型

根据证据产生的阶段与用途，分为三类：设计时证据、运行时证据、测试时证据。三者构成完整的证据链。

3.3 证据的采集与存储

3.3.1 采集策略

• 设计时证据： 通过 Git Hooks 或 CI 流水线自动采集，每次契约变更触发一次证据快照。
• 运行时证据： 通过 Sidecar 代理或 API 网关插件采集，采样率可配置（生产环境建议 1:1000，测试环境全量）。
• 测试时证据： 由测试框架（如 Postman、RestAssured、Karate）在每次测试执行后生成 JSON 格式的结果报告。

3.3.2 存储模型

证据存储采用分层桶结构，便于按时间、版本、环境快速检索：

evidence-store/
├── design-time/
│   ├── v2.1.0/
│   │   ├── openapi-spec.yaml
│   │   ├── design-review-notes.md
│   │   └── compatibility-check.json
│   └── v2.2.0/
├── run-time/
│   ├── 2025-03-21/
│   │   ├── mock-call-log.ndjson
│   │   └── error-rate.csv
│   └── 2025-03-22/
└── test-time/
    ├── suite-auth/
    │   ├── result-2025-03-21.json
    │   └── coverage-report.xml
    └── suite-order/

3.4 证据报告的标准格式

为了跨工具、跨团队交换证据，必须采用统一格式。推荐基于 JSON Schema 定义的标准证据报告结构，以下为核心字段：

{
  "evidenceReport": {
    "meta": {
      "reportId": "evt-20250321-001",
      "apiVersion": "2.1.0",
      "environment": "staging",
      "generatedAt": "2025-03-21T14:30:00Z",
      "generator": "evidence-collector v1.2.0"
    },
    "evidenceChain": [
      {
        "type": "design-time",
        "source": "openapi-spec.yaml",
        "checksum": "sha256:abc123...",
        "content": { ... }
      },
      {
        "type": "run-time",
        "source": "mock-call-log.ndjson",
        "checksum": "sha256:def456...",
        "content": { ... }
      },
      {
        "type": "test-time",
        "source": "result-2025-03-21.json",
        "checksum": "sha256:ghi789...",
        "content": { ... }
      }
    ],
    "conclusion": {
      "overallStatus": "pass",
      "violations": [],
      "coverage": 0.95
    }
  }
}

标准格式要求：

• meta 段：必须包含报告 ID、API 版本、环境、生成时间、生成器信息。
• evidenceChain 段：按时间顺序排列证据条目，每条必须包含类型、来源、校验和、内容。
• conclusion 段：汇总状态（pass/fail/warn）、违规列表、覆盖率指标。

3.5 证据报告生命周期（SVG 图）

下图展示了证据从采集、存储到报告生成与审计的完整生命周期：

3.6 证据报告质量检查清单

在生成或评审一份证据报告时，请逐项核对以下清单：