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命令行选项

参考链接