buf

缓冲液

buf CLI 是使用 Protocol Buffer 的最佳工具。它提供：

• 强制执行良好 API 设计选择和结构的 linter。
• 一种重大变更检测器，可在源代码或线路级别强制执行兼容性。
• 一个根据可配置模板调​​用插件的生成器。
• 一个格式化程序，可根据行业标准格式化 Protobuf 文件。
• 与 Buf 架构注册表集成，包括完整的依赖关系管理。

安装

自制

您可以使用 Homebrew（macOS 或 Linux）安装buf ：

brew install bufbuild/buf/buf

这将安装：

• buf 、 protoc-gen-buf-breaking和protoc-gen-buf-lint二进制文件
• Bash、Fish、Powershell 和 zsh 的 Shell 完成脚本

其他方法

对于其他安装方法，请参阅我们的官方文档，其中包括：

• 通过 npm 安装buf
• 在 Windows 上安装buf
• 使用buf作为 Docker 镜像
• 从 tarball 以及通过 GitHub Releases 从源代码安装为二进制文件
• 使用 minisign 公钥验证版本

用法

Buf 的帮助界面提供命令和标志的摘要：

buf --help

有关更全面的使用信息，请参阅 Buf 的文档，尤其是这些指南：

• buf breaking
• buf build
• buf generate
• buf lint
• buf format
• buf registry （用于使用 BSR）

CLI 重大变更政策

我们永远不会在给定的 CLI 主要版本中进行重大更改。 buf达到 v1.0 后，您可以预期在 v2.0 之前不会发生重大更改。但由于我们没有计划发布 v2.0，因此我们可能永远不会破坏buf CLI。

此重大更改策略不适用于buf beta门后面的命令，您应该预期对buf beta registry等命令进行重大更改。然而，当这些命令或标志升级到测试版之外时，该策略就会生效。

我们对 Protobuf 的目标

Buf 的目标是用模式驱动的范例取代当前以 REST/JSON 为中心的 API 开发范例。与 REST/JSON 相比，使用 IDL 定义 API 具有许多优势，而 Protobuf 是迄今为止业界最稳定且广泛采用的 IDL。我们选择建立在这个广泛信任的基础上，而不是从头开始创建新的 IDL。

尽管 Protobuf 具有技术优势，但实际使用它长期以来一直比它需要的更具挑战性。 Buf CLI 和 BSR 是我们努力永久改变这种状况并使 Protobuf 可靠且易于服务所有者和客户使用的基石，换句话说，创建一个现代的 Protobuf 生态系统。

虽然我们打算逐步改进buf CLI 和 BSR，但我们相信这样一个生态系统的基本基础已经就位。

Buf 模式注册表

Buf 架构注册表 (BSR) 是一个用于管理 Protobuf API 的 SaaS 平台。它为您的所有 Protobuf 资产提供集中式注册表和单一事实来源，不仅包括您的.proto文件，还包括远程插件。尽管 BSR 提供​​了直观的浏览器 UI， buf使您能够从命令行执行大多数与 BSR 相关的任务，例如将 Protobuf 源推送到注册表以及管理用户和存储库。

BSR 不需要使用buf 。我们已向所有Protobuf 用户提供buf CLI 的核心功能。

更高级的 CLI 功能

虽然buf的核心功能应该涵盖大多数用例，但我们添加了一些更高级的功能来涵盖边缘情况：

• 自动文件发现。 Buf 遍历您的文件树并根据您提供的构建配置构建.proto文件，这意味着您不再需要手动指定--proto_paths 。但是，在需要禁用文件发现的情况下，您仍然可以通过 CLI 标志手动指定.proto文件。
• 用于检查和破坏性更改的细粒度规则配置。虽然我们确实有推荐的默认值，但您始终可以选择您的用例所需的确切规则集，其中有 40 条 lint 规则和 53 条重大更改规则可用。
• CLI 输出的可配置错误格式。 buf默认以file:line:column:message形式输出每个 lint 错误和遇到的重大更改的信息，但您也可以选择 JSON、MSVS、JUnit 和 Github Actions 输出。
• 由buf的精细错误输出驱动的编辑器集成。目前，我们为 Vim 和 Visual Studio Code 以及 IntelliJ 和 GoLand 等 JetBrains IDE 提供 linting 集成，但我们计划将来支持 Emacs 等其他编辑器。
• 通用输入定位。 Buf 使您不仅可以针对本地.proto文件，还可以针对各种其他输入（例如 tarball 和 ZIP 文件、远程 Git 存储库以及预构建的图像文件）执行 linting 和重大更改检测等操作。
• 速度。 Buf 的内部 Protobuf 编译器使用所有可用内核编译 Protobuf 源代码，而不影响确定性输出，这比protoc快得多。这允许近乎即时的反馈，这对于编辑器集成等功能特别重要。

后续步骤

安装buf后，我们建议您完成 CLI 教程，该教程提供了 CLI 核心功能的广泛但实用的概述。游览大约需要 10 分钟即可完成。

完成导览后，请查看您感兴趣的特定领域的其余文档。

社区

如需有关 Protobuf、最佳实践等的帮助和讨论，请加入我们的 Slack。

有关 Buf CLI 的更新，请关注 GitHub 上的此存储库。

对于功能请求、错误或技术问题，请发送电子邮件至 [email protected]。对于一般查询或包含在我们即将推出的功能测试版中，请发送电子邮件至 [email protected]。