# 为客户选定的数据格式，是一份必须遵守的契约

> 格式选错很少第一天就出问题，往往等真实数据或 schema 改动偏离双方的默认假设时才暴露。

原文: https://fdetimes.net/zh/guides/client-data-format-csv-protobuf-contract/

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 列表：

```proto
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 就行”时，要把它当作一场谈判的开始，而不是结束。

**本周动手试试:**

- 挑一个你目前发给客户的 CSV 文件，为它写一页规范：分隔符、引号、编码、有无表头以及每一列的类型。
- 打开你最近改过的 .proto 文件，找出所有已删除但没放进 reserved 的字段，并加以修正。
- 编写一个测试，用当前 schema 读取旧版本 schema 生成的数据，然后把它加入发布流水线。

## 信源

- [Language Guide (proto 3) | Protocol Buffers Documentation](https://protobuf.dev/programming-guides/proto3/)

- [Encoding | Protocol Buffers Documentation](https://protobuf.dev/programming-guides/encoding/)

- [Proto Best Practices | Protocol Buffers Documentation](https://protobuf.dev/best-practices/dos-donts/)

- [Schema evolution in Avro, Protocol Buffers and Thrift](https://martin.kleppmann.com/2012/12/05/schema-evolution-in-avro-protocol-buffers-thrift.html)

- [RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files](https://www.rfc-editor.org/rfc/rfc4180)

- [Schema Evolution and Compatibility for Schema Registry on Confluent Platform](https://docs.confluent.io/platform/current/schema-registry/fundamentals/schema-evolution.html)
