在 CI 中强制 Protobuf 字段兼容性

概述

Protobuf 兼容性取决于字段编号与类型，机器可在每次构建中检查。把已交付的描述符存为基线，对删除、重编号与类型变更快速失败。

关键步骤

1. 把已发布的描述符集存为对比基线。
2. 在工作树与基线之间运行破坏性变更检查。
3. 阻止现有字段的删除、重编号与类型变更，允许新增。
4. 只有在经过评审的协同迁移后才更新基线。

验证

• Schema 未变时构建通过。
• 删除字段编号会导致检查失败。
• 新增可选字段可通过。
• 重编号变更在合并前被拒绝。

注意事项

• 该检查只覆盖线格式兼容性，不覆盖字段语义兼容性。
• 无法发现保留编号但改变用意的重命名，仍需人工评审。

适用范围

本条目围绕「在 CI 中强制 Protobuf 字段兼容性」给出可复制的步骤、验证方式与常见问题，适合需要按此流程落地的工程团队。执行时请结合自身上下文调整命令与阈值，并在变更前后留存证据，便于后续复核与回滚。

建议在正式环境落地前先在预发或隔离环境演练一遍，把关键观测指标与负责人一并记录，确保出现异常时能快速定位并恢复。

buf breaking --against "https://github.com/acme/api#branch=main" .
# or against a stored image
buf breaking --against prev.bin .