bufbuild/buf

 # Buf [](https://github.com/bufbuild/buf/blob/main/LICENSE) [](https://github.com/bufbuild/buf/releases) [](https://github.com/bufbuild/buf/actions?workflow=ci) [](https://hub.docker.com/r/bufbuild/buf) [](https://github.com/bufbuild/homebrew-buf) [][badges_slack] [`buf`][buf] CLI 是用于处理 [Protocol Buffers][protobuf] 的最佳工具。它提供： - 一个 [linter][lint_usage]，用于强制执行良好的 API 设计选择和结构。 - 一个 [破坏性变更检测器][breaking_tutorial]，用于在源代码或 wire 层面强制执行兼容性。 - 一个 [生成器][generate_usage]，基于 [配置文件][templates] 调用您的插件。 - 一个 [格式化工具][format_usage]，按照行业标准格式化您的 Protobuf 文件。 - 与 [Buf Schema Registry][bsr] 集成，包括完整的依赖管理。 ## 安装 ### Homebrew 您可以使用 [Homebrew][brew]（macOS 或 Linux）安装 `buf`： ``` brew install bufbuild/buf/buf ``` 这将安装： - `buf`、[`protoc-gen-buf-breaking`][breaking] 和 [`protoc-gen-buf-lint`][lint] 二进制文件 - 用于 [Bash]、[Fish]、[Powershell] 和 [zsh] 的 Shell 补全脚本 ### 其他方法 有关其他安装方法，请参阅我们的[官方文档][install]，其中涵盖： - 通过 [npm] 安装 `buf` - 在 [Windows] 上安装 `buf` - 将 `buf` 作为 [Docker 镜像][docker] 使用 - 作为 [二进制文件][binary]、从 [tarball] 以及通过 [GitHub Releases][releases] 从 [源代码][source] 安装 - 使用 [minisign] 公钥[验证][verifying]发行版 ## 用法 Buf 的帮助界面提供了命令和标志的摘要： ``` buf --help ``` 有关更全面的用法信息，请查阅 Buf 的[文档][docs]，特别是以下指南： * [`buf breaking`][breaking_tutorial] * [`buf build`][build_usage] * [`buf generate`][generate_usage] * [`buf lint`][lint_usage] * [`buf format`][format_usage] * [`buf registry`][bsr_quickstart]（用于使用 [BSR]） ## CLI 破坏性变更策略 我们绝不会在 CLI 的特定主版本内进行破坏性变更。在 `buf` 达到 v1.0 之后，您可以预期在 v2.0 之前不会有破坏性变更。但由于我们不计划发布 v2.0，我们可能永远不会破坏 `buf` CLI。 ## 我们对 Protobuf 的目标 [Buf] 的目标是用**schema-driven（模式驱动）**范式取代当前以 REST/JSON 为中心的 API 开发范式。使用 [IDL] 定义 API 比 REST/JSON 提供了更多优势，而 [Protobuf] 是业内最稳定、采用最广泛的 IDL。我们选择在这个广泛受信任的基础上进行构建，而不是从头开始创建新的 IDL。 尽管具有技术优势，但实际 *使用* Protobuf 长期以来一直比需要的更具挑战性。Buf CLI 和 [BSR](#the-buf-schema-registry) 是我们努力彻底改变这一状况的基石，旨在让 Protobuf 对服务所有者和客户端都变得可靠且易于使用——换句话说，创建一个**现代 Protobuf 生态系统**。 虽然我们打算逐步改进 `buf` CLI 和 [BSR](#the-buf-schema-registry)，但我们确信这样一个生态系统的基础工作 *已经* 就绪。 ## Buf Schema Registry [Buf Schema Registry][bsr] (BSR) 是一个用于管理 Protobuf API 的 SaaS 平台。它为所有 Protobuf 资产提供了一个集中式注册中心和单一事实来源，不仅包括您的 `.proto` 文件，还包括 [远程插件][bsr_plugins]。尽管 BSR 提供了直观的浏览器 UI，但 `buf` 允许您从命令行执行大多数与 BSR 相关的任务，例如将 Protobuf 源代码[推送][pushing]到注册中心以及管理[用户][users]和[存储库][repositories]。 ## 更多高级 CLI 功能 虽然 `buf` 的[核心功能][features]应该涵盖大多数用例，但我们还包含了一些更高级的功能来处理边缘情况： * **自动文件发现**。Buf 会根据您提供的[构建配置][build_config]遍历您的文件树并构建您的 `.proto` 文件，这意味着您不再需要手动指定 `--proto_paths`。但是，在需要禁用文件发现的情况下，您仍然可以通过 CLI 标志手动指定 `.proto` 文件。 * **细粒度的规则配置**，用于[linting][lint_rules]和[破坏性变更][breaking_rules]。虽然我们有推荐的默认值，但您始终可以选择您的用例所需的准确规则集，其中包含 [40 条 lint 规则][lint_rules]和 [53 条破坏性变更规则][breaking_rules]。 * **可配置的错误格式**，用于 CLI 输出。默认情况下，`buf` 针对其遇到的每个 lint 错误和破坏性变更以 `file:line:column:message` 形式输出信息，但您也可以选择 JSON、MSVS、JUnit 和 Github Actions 输出。 * **编辑器集成**，由 `buf` 的精细错误输出驱动。我们目前为 [Vim 和 Visual Studio Code][ide] 以及 [JetBrains IDE][jetbrains]（如 IntelliJ 和 GoLand）提供 linting 集成，但我们计划在未来支持其他编辑器，例如 Emacs。 * **通用 Input 定位**。Buf 使您能够不仅针对本地 `.proto` 文件执行 linting 和破坏性变更检测等操作，还能针对广泛的其他 [Inputs]，例如 tarball 和 ZIP 文件、远程 Git 存储库以及预构建的 [image][images] 文件。 * **速度**。Buf 的内部 Protobuf [compiler] 使用所有可用核心编译您的 Protobuf 源代码，而不影响确定性输出，这比 `protoc` 快得多。这允许近乎即时的反馈，这对于[编辑器集成][ide]等功能尤为重要。 ## 后续步骤 安装 `buf` 后，我们建议完成 [CLI 教程][cli-tutorial]，该教程提供了 CLI 核心功能的广泛但实践性的概述。该教程大约需要 10 分钟完成。 完成教程后，请查阅[文档][docs]的其余部分以了解您感兴趣的特定领域。 ## 构建 以下是通过我们的 [releases] 提供的按 CPU 架构和操作系统划分的二进制文件明细： | | Linux | MacOS | Windows | | --- | --- | --- | --- | | x86 (64-bit) | ✅ | ✅ | ✅ | | ARM (64-bit) | ✅ | ✅ | ✅ | | ARMv7 (32-bit) | ✅ | ❌ | ❌ | | RISC-V (64-bit) | ✅ | ❌ | ❌ | | ppc64le | ✅ | ❌ | ❌ | | s390x | ✅ | ❌ | ❌ | ## 社区 如需有关 Protobuf、最佳实践等方面的帮助和讨论，请在 [Slack][badges_slack] 上加入我们。 有关 Buf CLI 的更新，请[在 GitHub 上关注此仓库][repo]。 如有功能请求、错误或技术问题，请发送电子邮件至 [dev@buf.build][email_dev]。如有一般咨询或希望加入我们即将推出的功能 Beta 测试，请发送电子邮件至 [info@buf.build][email_info]。

标签：API管理, API设计, Buf, CLI, DNS解析, EVTX分析, EVTX分析, Go语言, gRPC, IDL, Lint工具, LNA, Protobuf, Protocol Buffers, Schema Registry, SOC Prime, Subfinder, WiFi技术, 云安全监控, 代码检测, 代码生成, 依赖管理, 向后兼容, 开发工具, 开源项目, 接口定义语言, 数据序列化, 日志审计, 暗色界面, 格式化, 格式化工具, 渗透测试工具, 破坏性变更检测, 程序破解, 网络调试, 自动化, 请求拦截, 静态分析