Buf CLI

Buf

Buf 是面向现代 Protobuf 的工具链。它用快速编译器、模块感知工作区、格式化、Lint、破坏性变更检测、代码生成、依赖管理、API 调用以及 Buf Schema Registry 客户端，取代日常使用的 protoc。

如果你仍然通过围绕 protoc -I ... 编写 shell 脚本来处理 Protobuf，那么 Buf 正是你需要的升级方案：采用相同的 Schema 语言、相同的生成代码插件模型，减少繁琐环节，并提供一条从本地 .proto 文件直达受治理、带版本的 API 的路径。

开始

使用 Homebrew 安装 buf：

brew install bufbuild/buf/buf

初始化工作区并运行每个 Protobuf 仓库都应通过的检查：

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

从已纳入版本控制的 buf.gen.yaml 生成代码，而不是维护手写的 shell 命令：

buf generate

如需从空工作区开始，逐步创建可运行的 Connect 服务，请运行 Buf CLI 快速入门。

Buf 的优势

Protobuf 工作	使用 protoc 和脚本	使用 Buf
查找文件	维护 -I 路径，并祈祷导入顺序不会改变行为。	在 buf.yaml 中声明一次模块；Buf 会发现文件并拒绝有歧义的导入。
编译	管理本地 protoc 安装，并解析不断变化的 stderr 输出。	使用 Buf 内置编译器；该编译器已通过 protoc 描述符输出进行测试，并针对确定性并行编译而构建。
风格	依赖代码审查意见或单独的工具。	在本地、编辑器、CI 和 BSR 上运行 buf lint，使用 40 多条内置规则和自定义插件。
兼容性	等到生成代码失败、客户端出错或序列化数据无法读取后，才发现问题。	在合并前，针对 Git、BSR 模块、tarball、zip 文件或 Buf 镜像运行 buf breaking。
代码生成	在每台机器上安装插件二进制文件，并通过冗长命令定义行为。	在 buf.gen.yaml 中配置插件、输出、选项、输入和托管模式设置；可使用本地或远程插件。
依赖项	在仓库之间复制 .proto 文件，或手动将它们加入供应商目录。	在 buf.yaml 中声明 BSR 模块依赖，并在 buf.lock 中固定版本。
API 使用者	把 Schema 和生成说明发给大家。	发布到 BSR，让使用者通过 go get、npm install、Maven、Gradle、pip install、NuGet、Cargo、SwiftPM、CMake 或压缩包安装生成的 SDK。
治理	在每个仓库中重新实现检查，并希望每个团队都一直启用这些检查。	在 BSR 层强制执行破坏性变更、唯一性和自定义策略。

核心 CLI 功能无需 BSR 账户即可使用。登录注册表后，你可以按需使用分发、远程插件、生成的 SDK、托管文档、私有模块的依赖解析以及服务端检查。

核心工作流

Buf 将 .proto 文件目录树视为一个模块，并将项目视为一个工作区。只需一个简单的 buf.yaml，即可让构建、Lint、破坏性变更检测、代码生成、依赖解析和发布使用相同的输入。

version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE

接下来，有用的命令都刻意设计得很简单：

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

buf build 会编译工作区。buf lint 会在作者仍在编辑时发现 API 结构问题。buf breaking 会将当前 schema 与先前版本进行比较，并标记源代码、JSON 或线缆格式不兼容的问题。buf generate 会根据纳入版本控制的模板运行 protoc 插件。buf push 会将命名模块发布到 BSR。

代码生成

buf generate 兼容常规的 protoc 插件模型，但它将代码生成纳入版本化配置。此示例使用托管在 BSR 上的远程插件，从 proto/ 生成 Go Protobuf 类型和 ConnectRPC 处理程序：

version: v2
clean: true
managed:
  enabled: true
  override:
    - file_option: go_package_prefix
      value: github.com/acme/weather/gen/go
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/connectrpc/go
    out: gen/go
    opt: paths=source_relative
inputs:
  - directory: proto

远程插件无需在每位开发者的计算机或 CI 运行器上安装和维护生成器二进制文件。托管模式让 API 提供方无需将特定语言的文件选项放入 .proto 文件，同时消费者仍能获得适用于目标语言的正确生成包名。

本地插件也可以使用。只要插件遵循标准 Protobuf 插件协议，Buf 就能运行它。

破坏性变更

Protobuf 兼容性并非只有一种。重命名字段可能会破坏生成的源代码，同时保留二进制线缆格式；将字段从 int32 改为 string 则会破坏所有现有的序列化消息。buf breaking 通过 FILE、PACKAGE、WIRE_JSON 和 WIRE 兼容性规则类别，明确区分这些情况。

buf breaking --against '.git#branch=main'

--against 接受 Git 分支、BSR 模块、tarball、zip 文件、本地目录或预构建的 Buf 镜像。这在实际代码库中很重要：同一条命令可在笔记本电脑、CI 和发布自动化流程中运行。

Buf Schema Registry

Buf Schema Registry 是一个面向 Protobuf 的注册表。它可存储模块、验证模块能否编译、生成文档、解析依赖、托管远程插件、生成 SDK，并能在破坏性变更影响消费者之前执行 schema 检查。

buf push

将模块推送到 BSR，可为组织提供 Protobuf API 的真实来源。消费者可以将 schema 作为 BSR 模块依赖，在常用包管理器中安装生成的 SDK，也可以通过 BSR 文档查看服务、消息、字段、枚举、引用和历史提交。

相关项目

当 schema 的用途不止于代码生成时，Buf 最能发挥作用。ConnectRPC 使用 Protobuf schema 构建简单的 HTTP API，无需单独定义服务即可支持 Connect、gRPC 和 gRPC-Web。Protobuf-ES 为 JavaScript 和 TypeScript 用户提供现代 Protobuf 运行时和生成器。Protovalidate 将验证规则纳入 schema，并在不同语言间一致地执行。

一个契约应驱动整个工作流：编译、Lint、兼容性检查、生成客户端和服务端、验证、API 调用、包发布以及受管控的变更。

安装

Homebrew 会安装 buf、protoc-gen-buf-breaking 和 protoc-gen-buf-lint 二进制文件，以及适用于 Bash、Fish、PowerShell 和 zsh 的 Shell 补全脚本。

brew install bufbuild/buf/buf

其他受支持的安装方式包括 npm、Windows、Docker、[二进制文件下载]、[tarball]、[从源代码构建]和 minisign 验证。完整列表请参阅安装文档。

CLI 稳定性

Buf CLI 的发布不会在同一主版本内引入破坏性变更。自 buf 达到 v1.0 以来，您可以放心，在 v2.0 发布之前不会有破坏性变更。我们没有发布 v2.0 的计划。

此政策不适用于由 buf beta 门控的命令。在 beta 命令正式发布之前，请预期它们会有破坏性变更。

文档

• Buf CLI
• CLI 快速入门
• 模块和工作区
• 代码生成
• Lint
• 破坏性变更检测
• 格式化
• 使用 buf curl 调用 API
• Buf Schema Registry
• 生成的 SDK
• 远程插件
• Schema 检查
• 从 protoc 迁移

社区

如需获得有关 Protobuf、最佳实践和 Buf 的帮助或参与讨论，请加入我们的 Slack。

如需报告 bug、提出功能请求或咨询技术问题，请在此代码仓库中提交 issue，或发送邮件至 [email protected]。如有一般咨询，请发送邮件至 [email protected]。