为客户选定的数据格式,是一份必须遵守的契约
格式选错很少第一天就出问题,往往等真实数据或 schema 改动偏离双方的默认假设时才暴露。
要点速览
- RFC 4180 只是参考文档:CSV 的引号、编码和表头都必须书面约定。
- Protobuf 靠编号识别字段,用过的编号绝不能再分配,删除的字段必须放进 reserved。
- 关键问题是 schema 变更时哪一方先升级,这个问题应在第一次会议上提出。
RFC 4180 是许多团队至今仍称为“CSV 标准”的文档,但它把自己归为 informational(信息性)类别:只是参考,并非正式标准。每当你对“发个 CSV 给我们就行”点头同意,就等于签下了一份条款无人写明的契约。
对前线部署工程师(FDE)来说,这是整个部署过程中影响最持久的技术决策之一。集成代码可以重写,但一个已经在客户那边运行的数据格式,在你离开项目之后仍然必须遵守。
因此,选择格式时真正值得问的是:你在承诺什么,以及这份承诺如何在数据和 schema 变化时依然成立。
格式是契约,文件扩展名只是标签
每种格式都会以自己的方式回答三个问题:字节如何编码?每个字段的名称和类型放在哪里,是在数据内部,还是在另一份文档里?增加或删除字段后,客户还能不能读取?
CSV 对这三个问题的回答都很模糊。RFC 4180 要求,包含逗号、双引号或换行符的字段必须用双引号括起来。它还指出,CSV 的常见用法是 US-ASCII,其他字符集必须通过单独的参数声明。
举一个假设的例子:在一家物流客户的第一周,数据负责人只要求每天导出一份 CSV。
三周后,一个配送地址里出现了未加引号的逗号,一个客户名称包含非 ASCII 字符而双方从未约定编码,客户的报表随之错列,却没有报出一行错误。
两处故障,恰好都出在 RFC 4180 提出过警告的地方。
Protobuf 把字段名留在读取方
Protobuf 比 CSV 严格得多,但它把契约放在了另一个地方。其编码文档指出,在传输格式中,每个字段只由编号标识;名称和类型只能在解码端,根据消息定义来确定。
第一个推论是:只给客户发送 Protobuf 消息而不提供 .proto 文件,就好比寄出一个上锁的压缩包,却把钥匙留在自己手里。
第二个推论则更宽容。Martin Kleppmann 解释说,解析器遇到不认识的字段编号时,虽然不知道字段名,但仍能根据类型码算出要跳过多少字节。
Protobuf 文档也确认,旧解析器会忽略看不懂的新字段,所以新增字段通常是安全的。
枚举的处理同样宽松。在 proto3 中,无法识别的枚举值在解码时会保留在消息里,而不会让整个读取失败,因此客户的旧系统可以原样携带一个它还不认识的值。客户端代码因此应当为无法识别的值预留一个分支。
示例:schema 变更时的订单数据流
回到那家物流客户。假设两个月后,运营部门想给每个订单增加一个 delivery_window 字段,同时删除已经不用的 legacy_zone 字段。
用 CSV,就是加一列。如果客户的脚本按列位置而不是按列名读取,后面所有列都会错位一格,且不会报任何错误。如果文件没有表头,客户根本无从察觉。
用 Protobuf,新增 delivery_window 只需给它一个新编号。陷阱在删除字段上。字段编号是字段的永久身份,Protobuf 文档和 Kleppmann 都强调,已分配的编号绝不能复用。删除 legacy_zone 时,要把它的编号放进 reserved 列表:
message Order {
reserved 3;
reserved "legacy_zone";
string order_id = 1;
string address = 2;
string delivery_window = 4;
}
设想六个月后,另一位工程师把编号 3 分配给新字段 priority。客户的旧系统仍会按 legacy_zone 的定义解码编号 3,而 Protobuf 文档也承认,传输格式无法检测出一个字段用一种定义编码、却用另一种定义解码。
结果可能是解析错误,Protobuf 文档自己都称这是最好的情况。但后果清单里还包括数据损坏和个人数据泄露,这类问题在客户自己发现之前,没人会察觉。
一行 reserved 就能挡住这一整类事故:一旦有人试图复用已保留的编号,protoc 编译器会立即报错。
schema 变更时,谁先升级?
这个问题应当在第一次会议上提出。Confluent Schema Registry 是 Kafka 生态中的 schema 管理工具,它对 BACKWARD 的定义是:使用新 schema 的消费者,能够读取用紧邻的上一版 schema 生产的数据。对于 Protobuf,Confluent 文档推荐使用 BACKWARD_TRANSITIVE 模式。
由这一定义可以推出:读取方先切换到新 schema,写入方随后才能变更。如果读取方由你控制,或者客户升级很快,这个顺序很容易遵守。
但如果客户是一家每次代码变更都要经过审批委员会的大型企业,你这边想改 schema 的时间会远早于对方。这时就必须问:客户的旧系统能否读取新数据?对 Protobuf 而言,答案取决于你是只新增了字段,还是同时改了类型或复用了编号。
从第一次需求调研开始该做什么
先问清楚谁读取数据、用什么工具读取。在电子表格里打开文件的分析师,与持续调用你 API 的服务,需要的契约截然不同。
接着问 schema 会多久变一次,客户的升级周期有多长。schema 仍在变动,客户升级又慢,这就是一个信号:应当选择带显式 schema、演进规则清晰的格式,再确定你承诺的兼容方向。
然后把规范写在一页纸上,发给客户确认,哪怕对方只说了一句“发个 CSV 就行”。对 CSV 来说,这一页要写明分隔符、引号字符、编码、有无表头以及每一列的类型。
对 Protobuf 来说,就是放在客户可访问的代码仓库中的 .proto 文件,外加 reserved 规则。最后,编写一个用新 schema 读取旧数据的测试,并在每次发布时运行。
常见错误
最常见的错误,是把 CSV 当成人人理解一致的标准,而描述它的文档本身只是参考。第二个错误,是发送 Protobuf 消息却没有交付 .proto 文件的流程,让客户去猜字段 4 是什么意思。
第三个错误,是删除 Protobuf 字段却没有把它加进 reserved。第四个更难发现:修改字段类型。Protobuf 的最佳实践文档警告,这会破坏反序列化,尽管有些旧数据在新类型下仍能解析,因此只测几条记录可能带来虚假的安全感。
最后一个错误,是按自己团队的偏好而不是客户的工具来选格式。格式再高效,接收方打不开也毫无用处。
一段 schema 经历,胜过一行技能清单
简历上不要只罗列“CSV、Protobuf、Schema Registry”。要写一次 schema 发生变更、客户系统依然正常运行的经历。
面试官问到数据集成时,一个有力的回答只需要三点,就像上面的订单示例:你与客户约定了哪一方先升级;删除 legacy_zone 时你把编号 3 放进了 reserved;每次发布都运行一个用新 schema 读取旧数据的测试。这三点足以说明你真正做过这项工作。
下次客户说“发个 CSV 就行”时,要把它当作一场谈判的开始,而不是结束。
这篇文章对你有帮助吗?
感谢你的反馈!
6 个信源
- Language Guide (proto 3) | Protocol Buffers Documentation
- Encoding | Protocol Buffers Documentation
- Proto Best Practices | Protocol Buffers Documentation
- Schema evolution in Avro, Protocol Buffers and Thrift · 2012-12-05
- RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files
- Schema Evolution and Compatibility for Schema Registry on Confluent Platform