Buf 工具针对于Schema驱动、基于 Protobuf 的 API 开发,为服务发布者和服务客户端提供可靠和更好的用户体验。简化了您的 Protobuf 管理策略,以便您可以专注于重要的事情。
下载安装
可以直接去buf的GitHub的release页面下载,其他的安装方式参考官方文档
使用
三个yaml文件
初次接触buf项目的时候,有个疑问就是buf项目中buf.yaml
buf.gen.yaml
buf.work.yaml
这个三个文件的区别和用途。下面是简单的一个表,列出了三个文件的区别:
文件名 | 文件位置 | 说明 |
---|---|---|
buf.yaml | 每个proto模块定义的根目录 | buf.yaml 配置的位置告诉 buf 在哪里搜索 .proto 文件,模块的依赖项以及如何处理导入 |
buf.gen.yaml | 一般放在仓库的根目录 | 文件控制 buf generate 命令如何针对任何输入执行 protoc 插件 |
buf.work.yaml | 一般放在仓库的根目录 | 定义项目需要哪些proto模块 |
示例目录结构:
.
├── buf.gen.yaml
├── buf.work.yaml
├── proto
│ ├── acme
│ │ └── weather
│ │ └── v1
│ │ └── weather.proto
│ └── buf.yaml
└── vendor
└── protoc-gen-validate
├── buf.yaml
└── validate
└── validate.proto
一个buf.yaml的样例,可以通过buf mod init
来创建:
version: v1
breaking:
use:
- FILE
lint:
use:
- DEFAULT
build:
excludes:
- foo/bar
注:迁移相关,请参考Migrate from Prototool
一个buf.gen.yaml的样例:
version: v1
plugins:
- plugin: go
out: gen/go
opt: paths=source_relative
- plugin: go-grpc
out: gen/go
opt:
- paths=source_relative
- require_unimplemented_servers=false
buf可以远程proto插件方式,本地不需要安装插件。远程插件生成输入代码。输入可以是 git 存储库、tarball、zip 文件、包含使用 buf.yaml
配置文件配置的 Protobuf 文件的本地目录。
上面的文件使用远程插件可以改成下面内容:
version: v1
plugins:
- plugin: buf.build/protocolbuffers/go
out: gen/go
opt: paths=source_relative
- plugin: go-grpc
out: gen/go
opt:
- paths=source_relative
- require_unimplemented_servers=false
更多内容,可以参考 Never install Protobuf plugins again with remote plugins
一个buf.work.yaml的样例
version: v1
directories:
- paymentapis
- petapis
命令行选项
RPC客户端
buf的curl子命令可用来调用 gRPC 或 Connect 的服务器上的HTTP 服务。
$ buf curl --schema buf.build/bufbuild/eliza \
--data '{"name": "Bob Loblaw"}' \
https://demo.connect.build/buf.connect.demo.eliza.v1.ElizaService/Introduce
默认调用的是buf自研的Connect RPC,调用gRPC需要使用--protocol
指定
$ buf curl --schema . --protocol grpc --http2-prior-knowledge \
http://localhost:20202/foo.bar.v1.FooService/DoSomething
参考 官方文档
发布Buf 模块
参考
更多参数选项,请参考 buf命令行选项