1. 数据契约基础：什么是数据契约、核心要素与API契约的区别

说实话，我第一次听到「数据契约」这个词，是在一次跨团队的数据故障复盘会上。当时数据管道崩了，消费方拿到的字段全是 null，生产方说「我改了 schema 但忘了通知」，消费方说「你改之前好歹说一声啊」——两边吵了半小时。我坐在那儿突然意识到：这不就是缺一份契约吗？

后来我花了两年时间，在不同公司落地数据契约体系。今天咱们就从最基础的问题开始：数据契约到底是什么？它长什么样？跟 API 契约有什么不同？

1.1 什么是数据契约

数据契约，说白了就是数据生产方和消费方之间的一份书面约定。它明确规定了：你生产什么数据、什么格式、什么质量、什么时间交付，我消费方怎么用、用多少、出问题找谁。

你想想看，我们做 API 开发时，Swagger/OpenAPI 文档就是契约。但到了数据层面，很多人还在靠「口头沟通 + 邮件通知」来协作。这不出问题才怪。

我在项目中遇到过最典型的场景：业务方说「我要用户画像数据」，数据工程师给了个 Hive 表路径，字段名全靠猜。后来我们引入数据契约，每个数据集必须注册 schema、owner、SLA，消费方才能接入。效果立竿见影——数据事故减少了 70%。

1.2 数据契约的核心要素

一份完整的数据契约，我个人习惯把它拆成六个维度。少了任何一个，契约都不完整。

维度	说明	示例
Schema	字段名称、类型、是否必填、默认值	user_id: string (required)
语义	每个字段的业务含义、枚举值范围	status: 0=未激活, 1=已激活
质量	完整性、准确性、时效性指标	null 率 < 1%, 延迟 < 5min
SLA	数据可用时间、刷新频率、故障响应时间	每日 08:00 前产出, P0 故障 30min 响应
血缘	数据来源、加工链路、依赖关系	源表: ods.user_info → dwd.user_profile
治理	数据保留周期、脱敏规则、访问权限	手机号脱敏, 保留 180 天

嗯，这里要注意：Schema 和语义是最容易被忽略的。我曾经接手过一个项目，字段名叫 flag，文档写的是「0 或 1」，但没人知道 0 和 1 分别代表什么。后来查了三个月前的邮件才搞清楚——这种坑，一份契约就能填上。

1.3 数据契约与 API 契约的区别

很多人会问：数据契约不就是 API 契约的数据版吗？其实不然。我做个对比你就明白了。

对比维度	API 契约	数据契约
交互模式	请求-响应，同步为主	推送/拉取，异步为主
数据规模	单次 KB ~ MB 级	批量 GB ~ TB 级
变更频率	版本化，向后兼容	Schema 演进，兼容性更复杂
质量关注点	响应状态码、延迟	数据完整性、时效性、准确性
治理需求	鉴权、限流	脱敏、保留策略、血缘追踪
典型工具	OpenAPI, gRPC, GraphQL	Avro, Protobuf, Great Expectations

为什么会这样？因为 API 契约面向的是「一次调用」，而数据契约面向的是「持续的数据流」。你想想看，一个 API 接口返回 100 条记录，出错了重试就行。但一个数据管道每天跑几亿条记录，字段类型变了、null 值多了、延迟了半小时——这些在 API 世界里几乎不会发生，但在数据世界里是家常便饭。

1.4 一张图看懂数据契约全景

下面这张图，是我在多个项目中反复打磨出来的。它展示了数据契约在整个数据链路中的位置，以及它如何连接生产方和消费方。

这张图想表达的核心逻辑是：数据契约不是一张纸，而是一个贯穿数据全生命周期的治理机制。生产方注册契约，消费方订阅契约，数据管道按契约执行，质量监控按契约告警——所有环节都围绕契约运转。

1.5 什么时候该上数据契约

我经常被问到：我们团队才 5 个人，需要搞数据契约吗？我的回答是：看痛点。

• 如果你经常遇到「数据突然变了没人通知」——需要契约
• 如果你花大量时间在「这个字段是什么意思」的沟通上——需要契约
• 如果你每次数据出问题都要拉群吵架定责——需要契约
• 如果你的数据消费方超过 3 个团队——强烈建议上契约