Buf

本文汇总翻译自 Buf 官方博客的 Protobuf Tip 系列文章（共 10 篇）。该系列由 Buf 团队撰写，Tip #1–#9 的作者是 M. C. Sunny Young de la Sota，Tip #10 的作者是 Kevin McDonald。每节开头附有原文链接。系列文章中的插图由 D2 图表语言生成，本文直接引用原文 SVG 链接。 系列概览 # 标题 一句话总结 原文 1 字段名是永恒的 永远不要重命名字段 链接 2 压缩你的 Protos！ 压缩无处不在，编码体积的权衡没那么重要 链接 3 枚举名需要前缀 枚举值的 FQN 不含枚举名，必须加前缀避免冲突 链接 4 接受我们无法修复的错误 分布式场景下有些错误不值得修，不破坏用户更重要 链接 5 避免 import public/weak 这两个特性是 C++ 历史包袱，不要用 链接 6 枚举别名的隐性危险 allow_alias 会坑到反射和 JSON，别用 链接 7 看清二进制的工具 buf convert + protoscope 调试 wire format 链接 8 永远不要用 required required 是 proto2 的大坑，无法安全移除 链接 9 有些数字比其他数字更"平等" 字段编号 1–15 解码最快 链接 10 选择正确的整数类型 默认用 int64 就对了 链接 Tip #1：字段名是永恒的 原文：Protobuf Tip #1: Field names are forever （2025-04-08） ...

Buf 工具针对于Schema驱动、基于 Protobuf 的 API 开发，为服务发布者和服务客户端提供可靠和更好的用户体验。简化了您的 Protobuf 管理策略，以便您可以专注于重要的事情。 下载安装 可以直接去buf的GitHub的release 页面下载，其他的安装方式参考官方文档 使用 三个yaml文件 初次接触buf项目的时候，有个疑问就是buf项目中buf.yaml buf.gen.yaml buf.work.yaml这个三个文件的区别和用途。下面是简单的一个表，列出了三个文件的区别： 文件名 文件位置 说明 buf.yaml 每个proto模块定义的根目录 buf.yaml 配置的位置告诉 buf 在哪里搜索 .proto 文件，模块的依赖项以及如何处理导入 buf.gen.yaml 一般放在仓库的根目录 文件控制 buf generate 命令如何针对任何输入执行 protoc 插件 buf.work.yaml 一般放在仓库的根目录 定义项目需要哪些proto模块 示例目录结构： . ├── buf.gen.yaml ├── buf.work.yaml ├── proto │ ├── acme │ │ └── weather │ │ └── v1 │ │ └── weather.proto │ └── buf.yaml └── vendor └── protoc-gen-validate ├── buf.yaml └── validate └── validate.proto 一个buf.yaml 的样例，可以通过buf mod init来创建： ...