企业官网建设流程全解析

Buf：现代 Protobuf 工具链

bufbuild/buf 在 GitHub 上已经拿到 11,226 Star。它把自己定位为现代 Protobuf 工具链，替代日常开发中围绕 protoc 的脚本和手动流程。从 v1.0 开始，Buf CLI 承诺在同一大版本内不做破坏性变更，beta 命令除外。

1、这项目是干嘛的

Buf 解决的是 Protobuf 工作流。它把编译、格式化、lint、破坏性变更检测、代码生成、依赖管理和 Buf Schema Registry 客户端装进一个 CLI。核心思路是把 .proto 文件从本地编辑到发布治理化 API 的整条链路串起来。

如果你现在还在用 shell 脚本调用protoc -I，Buf 提供的是同一份 schema 语言、同一套生成插件模型，但零件更少，路径更直接。它不会因为 import 顺序不同而给出不同结果，也不需要每台机器都维护一组插件版本。

2、为什么要用它

用 protoc 的团队通常会遇到几个麻烦：import 路径靠-I参数维护，顺序一变行为就可能变；每台机器和 CI runner 都要装对应版本的插件；字段兼容性要到客户端报错或序列化异常才能发现；跨仓库共享 .proto 文件时不是拷贝就是手写 vendor。

Buf 把这些步骤收进配置。模块在buf.yaml里声明一次，编译器自己发现文件并拒绝歧义 import。lint 和 breaking 检查可以在本地、编辑器、CI 和 BSR 上跑。代码生成通过buf.gen.yaml描述，插件可以是本地二进制，也可以是 BSR 上的远程插件。依赖直接声明在buf.yaml里，版本锁在buf.lock中。README 里列了一张对比表：找文件、编译、风格检查、兼容性、代码生成、依赖管理、API 消费者、治理这几件事，用 protoc 要拼多个工具，用 Buf 则是一个配置加一组命令。

3、核心工作流

Buf 把目录树看成一个 module，把项目看成一个 workspace。一个基础的buf.yaml就能让 build、lint、breaking、generate、push 这些命令对同一份输入达成一致。

常用命令如下：

buf build buf format -w buf lint buf breaking --against '.git#branch=main' buf generate buf push

buf build编译 workspace。buf lint在编辑阶段就拦截 API 形状问题。buf breaking把当前 schema 和旧版本对比，标出 source、JSON 或 wire 格式上的不兼容。buf generate按配置跑 protoc 插件。buf push把模块发布到 BSR。

4、代码生成与破坏性变更

buf generate兼容普通 protoc 插件模型，但把生成逻辑搬进版本化配置。远程插件意味着不需要在每台机器上维护生成器二进制。managed mode 让 API 生产者把语言相关的文件选项从 .proto 里剥离，消费者仍能得到正确的生成包名。

破坏性变更可以分成不同层面。重命名字段可能只破坏生成源码，不改变 wire 格式；把 int32 改成 string 则会让所有已序列化消息失效。buf breaking用 FILE、PACKAGE、WIRE_JSON、WIRE 这几类规则把差异显式化。--against支持 Git 分支、BSR 模块、tarball、zip 或预构建的 Buf image。同一条命令在笔记本、CI 和发布自动化里都能用。

5、安装与生态

安装最方便的方式是用 Homebrew：

brew install bufbuild/buf/buf

初始化后跑一遍常用检查：

buf config init buf build buf format -w buf lint buf breaking --against '.git#branch=main'

Buf 周边还有 ConnectRPC、Protobuf-ES、Protovalidate 等项目。ConnectRPC 用 Protobuf schema 生成同时支持 Connect、gRPC、gRPC-Web 的 HTTP API；Protobuf-ES 给 JavaScript 和 TypeScript 提供现代 Protobuf 运行时；Protovalidate 把校验规则写进 schema，跨语言统一执行。BSR 则把这些能力串成一条线：模块上传后自动编译、生成文档、解析依赖，并输出多种语言的 SDK。

6、适合谁用

• 用 Protobuf 做多语言微服务或 API 治理的团队
• 还在用 shell 脚本绕 protoc，想减少脚本和配置碎片的人
• 需要把 schema 当作单一事实来源，驱动代码生成、文档、SDK 和校验的项目

核心 CLI 功能不需要 BSR 账号。登录注册表后，可以使用分发、远程插件、生成 SDK、托管文档、私有模块依赖解析和服务器端检查。

核心 CLI 功能不需要 BSR 账号。登录注册表后，可以使用分发、远程插件、生成 SDK、托管文档、私有模块依赖解析和服务器端检查。