bufbuild/buf

Buf

buf CLI是一个用于Protocol Buffers的工具。

核心功能与特性

• 能够在Buf模式注册表（BSR）上管理Protobuf资产。
• 代码规范检查器，用于强制实施良好的API设计选择和结构。
• 兼容性变更检测器，用于在源代码或 wire 级别强制兼容性。
• 代码生成器，基于可配置的模板调用插件。
• 格式化工具，按照行业标准格式化Protobuf文件。
• 与Buf模式注册表集成，包括完整的依赖管理。

镜像概述与主要用途

buf CLI旨在通过schema驱动的范式替代以REST/JSON为中心的API开发模式。它基于Protocol Buffers构建，解决了Protobuf使用复杂的问题，为服务所有者和客户端提供可靠、易用的现代Protobuf生态系统。无论是管理Protobuf文件、确保API设计一致性、检测兼容性变更，还是生成代码，buf CLI都能提供全面支持。

使用场景与适用范围

• 需要集中管理Protobuf API资产的团队。
• 希望强制实施API设计规范和最佳实践的项目。
• 需确保Protobuf接口兼容性，避免破坏性变更的服务。
• 需要自动化Protobuf代码生成流程的开发工作流。
• 寻求与编辑器集成，获取实时Protobuf代码检查反馈的开发者。

安装与使用方法

Docker镜像使用

基本用法

通过Docker运行buf CLI，无需本地安装：

sh
# 查看帮助信息
docker run --rm -v $(pwd):/workspace bufbuild/buf --help

# 检查当前目录下的Protobuf文件规范
docker run --rm -v $(pwd):/workspace bufbuild/buf lint

# 检测兼容性变更（对比当前代码与Git历史中的主分支）
docker run --rm -v $(pwd):/workspace bufbuild/buf breaking --against '.git#branch=main'

# 生成代码（需配置buf.gen.yaml）
docker run --rm -v $(pwd):/workspace bufbuild/buf generate

挂载工作目录说明

使用-v $(pwd):/workspace将本地当前目录挂载到容器内的/workspace目录，使buf能够访问本地Protobuf文件和配置。根据需要调整挂载路径。

其他安装方法

Homebrew（macOS/Linux）

sh
brew install bufbuild/buf/buf

此命令会安装：

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

更多安装方式

详见官方文档，包括：

• 通过npm安装
• Windows系统安装
• 从GitHub Releases下载二进制文件、压缩包或从源代码编译
• 使用https://github.com/jedisct1/minisign公钥验证发布版本

CLI使用指南

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

sh
buf --help

完整使用说明请参考buf的文档，重点关注以下指南：

• buf breaking（兼容性变更检测）
• buf build（构建Protobuf）
• 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等命令可能会有破坏性变更。当这些命令或标志脱离beta阶段后，本政策将生效。

Buf的Protobuf目标

Buf的目标是用schema驱动的范式替代当前以REST/JSON为中心的API开发模式。使用IDL定义API比REST/JSON具有更多优势，而Protobuf是业内最稳定、应用最广泛的IDL。我们选择在这一可信基础上构建，而非从头创建新的IDL。

尽管Protobuf在技术上具有优势，但实际使用一直过于复杂。buf CLI和BSR是我们致力于永久改变这一现状的核心，旨在为服务所有者和客户端提供可靠、易用的Protobuf工具——即创建现代Protobuf生态系统。

我们计划逐步改进buf CLI和BSR，但坚信这一生态系统的基础框架已就绪。

Buf模式注册表（BSR）

Buf模式注册表（BSR）是一个用于管理Protobuf API的SaaS平台。它提供集中式注册表和单一数据源，用于存储所有Protobuf资产，不仅包括.proto文件，还包括远程插件。尽管BSR提供直观的浏览器UI，buf允许通过命令行执行大多数BSR相关任务，如推送Protobuf源代码到注册表，管理用户和仓库。

使用buf无需依赖BSR。buf CLI的核心功能对所有Protobuf用户开放。

高级CLI功能

虽然buf的核心功能已覆盖大多数用例，但其还包含一些高级功能以应对边缘场景：

• 自动文件发现：buf遍历文件树并根据提供的构建配置构建.proto文件，无需手动指定--proto_paths。也可通过CLI标志手动指定.proto文件以禁用自动发现。
• 细粒度规则配置：针对代码规范检查和兼容性变更。提供推荐默认规则集，同时支持自定义选择，包含40条代码规范规则和53条兼容性变更规则。
• 可配置错误输出格式：默认以file:line:column:message格式输出每个规范错误和兼容性变更，也支持JSON格式，即将支持JUnit格式。
• 编辑器集成：基于buf的细粒度错误输出实现。目前提供Vim和Visual Studio Code的规范检查集成，计划支持Emacs和JetBrains IDEs（如IntelliJ、GoLand）。
• 通用输入目标：支持对本地.proto文件、tarball/ZIP压缩包、远程Git仓库、预构建镜像文件等多种输入源执行规范检查和兼容性变更检测。
• 速度优化：buf的内部Protobuf编译器利用所有可用核心编译源代码，同时保证输出确定性，比protoc显著更快，为编辑器集成等功能提供近实时反馈。

后续步骤

安装buf后，建议完成Buf之旅，该教程约10分钟，提供CLI和BSR核心功能的实践概述。

完成教程后，可查阅文档了解特定领域的详细信息。

社区支持

如需Protobuf相关帮助、最佳实践讨论等，可加入Slack社区。

关注https://github.com/bufbuild/buf/获取buf CLI的更新。

功能请求、错误报告或技术问题，请发送邮件至***。一般咨询或希望参与未来功能测试，请发送邮件至***。