数据质量契约：在管线入口把错误挡住

契约比文档更可靠

数据管线的常见问题是「口径写在文档里，代码却各自解释」。字段含义、时间戳语义、空值规则如果没有进入构建期或运行期校验，错误往往在下游才被发现，此时定位成本已经很高。

我们的做法是把口径写成数据质量契约：一份可执行的声明，由管线在入口处强制校验，失败就停止，而不是带着疑问继续向下游流动。

三层校验

层次	检查内容	时机
结构层	字段存在、类型、主键唯一	每次装载
语义层	时间有序、时区、单位、枚举取值	每次装载
统计层	空值率、跳变幅度、重复率阈值	每日汇总

结构层与语义层应当硬失败；统计层更适合作为告警，因为它依赖历史分布，阈值需要按数据源单独标定，不宜一刀切。

一个最小契约示例

contract: bars@v3
fields:
  symbol:      { type: string, required: true }
  ts:          { type: timestamp, timezone: UTC, required: true }
  close:       { type: decimal, min: 0, required: true }
constraints:
  unique: [symbol, ts]
  ordered_by: ts
quality:
  null_rate_max: 0.01          # 示例内容 · 需核实
  duplicate_rate_max: 0.0
on_violation: fail_fast

注意 on_violation: fail_fast：管线不自动「修好」数据。自动填充看似省事，却会把上游问题伪装成下游结论，这是可复现性最难排查的一类故障。

失败也要留下结构

校验失败时的输出同样需要结构化：哪个契约、哪一批次、哪个字段、样本行标识、违反的规则。有了这些信息，修复动作才可审计、可回溯。

violation {
  contract:    bars@v3
  batch:       2026-11-13      # 示例内容 · 需核实
  field:       ts
  rule:        ordered_by
  sample_rows: 12
  action:      quarantine_batch
}

小结

契约不是一次性配置，而是随数据源演进而版本化的资产。本文仅讨论工程校验结构，不涉及任何数据源选型或合规判断。文中阈值与批次标识均为示意。

示例内容 · 需核实。