Buf 完整指南如何把 Protobuf 工程从手写脚本带到一站式工具链【免费下载链接】bufThe best way of working with Protocol Buffers.项目地址: https://gitcode.com/GitHub_Trending/bu/bufBuf 是 Protocol Buffers 的现代化工程工具链它把你仓库里的 .proto 文件纳入一份小小的配置统一管理把格式规整、风格检查、兼容性检查、代码生成、依赖管理统一成一组标准命令还能让同一份定义最终发布到集中式注册中心Buf Schema Registry简称 BSR变成团队都能复用的版本化 API。项目定位一条配置贯穿始终的 Protobuf 工具链Buf 要解决的问题很具体如果你今天还在围着protoc -I拼 shell 脚本、逐台机器装插件、靠人肉同步 .proto 文件Buf 就是替代方案。它沿用你熟悉的 schema 语言和 protoc 插件模型但把零碎件换成模块 工作区 配置文件的组合——同一份 buf.yaml 让编译、lint、兼容性检查、生成对齐同一份输入同一份 buf.gen.yaml 成为代码生成的唯一事实来源本地文件到受治理的 API 之间只剩标准命令。在源码层面lint 与破坏性变更检测的规则引擎位于 private/bufpkg/bufcheck生成引擎位于 private/bufpkg/bufgen。环境准备用 Homebrew 装好 Buf 并验证版本前提是你的 macOS 或 Linux 机器上装有 HomebrewBuf 同样提供 Windows、Docker、npm 等安装渠道本文走 Homebrew 这条线。执行brew install bufbuild/buf/buf这一条命令装下的不止buf主命令还包括 lint 与破坏性检测插件protoc-gen-buf-lint、protoc-gen-buf-breaking以及 Bash、zsh、Fish、PowerShell 的补全脚本。接着验证是否生效buf --version看到正常的版本号输出环境就就绪了。核心任务演练从初始化工作区到产出代码的最小链路假设你刚建好一个空目录里面放着几个 .proto 文件比如一个声明了 message 和 service 的 example.proto。接下来按顺序走五步每步都是一条命令的事。第 1 步初始化工作区配置。先让 Buf 知道哪些目录是模块buf config init执行后项目根目录会多出 buf.yaml多模块项目还会生成 buf.work.yaml。本仓库根目录的 buf.yaml 就是可以直接对照的范例v2 格式声明一个模块并启用 STANDARD lint 集合。第 2 步先编译再规整。动生成之前先确认整体能编译通过buf build成功时不会打印任何错误意味着所有 import 都已解析。趁热把格式统一掉buf format -w-w会把规整结果直接写回文件跑完后 .proto 的缩进、语句顺序全部归一diff 里就是这次改动的全部内容。第 3 步风格检查。格式管好不好看lint 管API 形状对不对buf lint它会按 buf.yaml 里声明的规则集逐项检查有问题会直接指出文件和行号趁你还在编辑时修最省事。第 4 步兼容性检查。如果目录已有 Git 历史可以拿当前 schema 和上一个版本比一比确认改字段名、改类型没有踩到兼容红线buf breaking --against .git#branchmain无输出即没有不兼容变更。--against可以指向 Git 分支、本地目录或注册中心模块所以这条命令在你本机和 CI 里写法完全一致。第 5 步产出结果。到这一步如果目录里已有 buf.gen.yaml一条命令就能把定义变成代码buf generate生成物落到配置文件里声明的各个输出目录不再需要你手写一串插件命令。典型工作流两个真实任务场景为多语言项目一键生成代码痛点团队里每台机器都要各自装生成插件生成命令散落在冗长的 shell 脚本中而 go_package 这类语言专属选项写在 .proto 里又很难同时照顾多语言。Buf 的解法是把用什么插件、输出到哪、带什么选项全部收进版本化配置。以Go 类型 ConnectRPC 处理器为例最小配置大致长这样version: v2 managed: enabled: true plugins: - local: protoc-gen-go out: gen/go opt: - pathssource_relative - local: protoc-gen-connect-go out: gen/go inputs: - directory: protomanaged 模式让语言专属选项留在配置文件而不是 .proto 里插件既可以像上面这样本地运行也可以用托管在注册中心的远程插件那样机器上连插件二进制都不用装。执行buf generate后生成代码就落在 gen/ 下。仓库自带了一份 Go 生成模板可供参考etc/template/buf.go.gen.yaml还有只生成客户端的变体 etc/template/buf.go-client.gen.yaml。想加第二种语言只需再补一个插件块输入与选项都不用再动。把协议发布到注册中心供他人复用痛点别的团队要用你这套 message 定义大家就开始跨仓库拷贝 .proto 或手工 vendor版本一改就得两边手动同步时间一长必然漂移。正确做法是把模块发布到 Buf Schema Registrybuf login buf push推送成功后这个模块就成为组织内的权威来源。其他仓库在 buf.yaml 中把它声明为依赖、用 buf.lock 锁定版本构建时自动拉取彻底告别手工拷贝消费方甚至可以直接用常规包管理器安装注册中心产出的 SDK连生成环节都省了。周边与生态Buf 还能和谁搭配和 ConnectRPC一份定义三种传输协议.service 定义写一次ConnectRPC 就能同时产出支持 Connect纯 HTTP/JSON、gRPC、gRPC-Web 三种协议的客户端与服务端不需要再维护第二份服务定义。上面场景一里加一个 connect-go 插件就打通了这条线。和 Protobuf-ESJS/TS 的现代运行时对 JavaScript 和 TypeScript 项目Protobuf-ES 提供了现代化的运行时与生成器让浏览器和 Node 端用 Protobuf 的类型清晰、体积可控。和 Buf 组合后同一份定义可以同时驱动后端与前端。和 Protovalidate把校验规则写进 schema 里Protovalidate 允许把字段级校验规则非空、取值范围、正则匹配等直接标注在 schema 上且校验行为在各语言间保持一致省去每个服务各自重写一遍检查逻辑的麻烦。想继续深入可以从 README.md 看起Buf 自身的注册中心 API 定义在 proto/buf/alpha版本变更历史见 CHANGELOG.md。【免费下载链接】bufThe best way of working with Protocol Buffers.项目地址: https://gitcode.com/GitHub_Trending/bu/buf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
