简介
Buf 是一款更高效、开发者友好的 Protobuf API 管理工具，不仅支持代码生成，还支持插件和 Protobuf 格式化。
我们可以使用 Buf 替代原本基于 Protoc 的代码生成流程，一方面可以统一管理团队 Protoc 插件的版本、代码生成配置，另一方面可以简化项目开发配置。
本文将会用两部分内容来简述 Buf 的使用流程，涵盖 Golang 服务端开发和前端开发的内容。
- 基于 Protobuf 生成 Golang 代码。
- 基于 Protobuf 生成 Typescript 类型定义代码。
Buf 安装
如果您使用的是 Macos，可以直接通过 Brew 安装。
brew install bufbuild/buf/buf
如果您使用的是 Windows，推荐您通过 Golang 的 install 命令安装。
# Substitute GOBIN for your bin directory
# Leave unset to default to $GOPATH/bin
GO111MODULE=on GOBIN=/usr/local/bin go install \
github.com/bufbuild/buf/cmd/buf@v1.18.0
更多安装方式可以自行查阅官方文档 - Getting Started with the Buf CLI。
安装成功之后，我们可以通过 buf --version 命令进行验证。
使用 Buf 生成 Golang 代码
使用 Buf 生成代码可以拆分以下步骤。
- 初始化 Buf 配置（配置 Protobuf 协议格式化和 Lint 校验）。
- 编写 Protobuf 协议。
- 初始化 Buf 代码生成配置。
- 运行 Buf 生成代码。
本文将会基于 Buf 提供的 Remote Plugin 工具进行说明。
初始化 Buf 配置
我们在任意项目下创建名为 proto 的目录并使用 buf mod init 初始化 Protobuf 协议的 Buf 配置。
值得注意的是这个目录既可以是前后端共享的路径，也可以是共享的集中式 Git 仓库，形式取决于项目管理者本身的规划。
此时项目的 proto 目录下会出现一个名为 buf.yaml 的配置文件，如图所示。
.
└── proto
└── buf.yaml
一般情况下，我们可以考虑改动 buf.yaml 配置如下所示。
version: v1
deps:
- buf.build/googleapis/googleapis:main
lint:
use:
- DEFAULT
except:
- PACKAGE_DIRECTORY_MATCH
- PACKAGE_VERSION_SUFFIX
breaking:
use:
- FILE
改动之后的配置可以允许我们在协议中导入 google 提供的 api，禁用包名和目录对不上将会导致编译报错，禁用强制包名后缀为版本号将会导致报错。
其中后面两项为 Proto3 协议规范，但有时候我们可以根据情况进行调整。
编写 Protobuf 协议
接下来我们继续创建 proto/api 和 proto/api/hello 子目录，并在 proto/api/hello 目录下创建文件 hello.proto。
syntax = "proto3";
// 一般情况下 Package 可以按照「项目名.服务类型.服务名」的方式进行命名
package bufexample.api.hello;
import "google/protobuf/timestamp.proto";
// 如果需要生成 Golang 代码需要指定 go_package, 通常是「项目名/服务类型/服务名」即可
option go_package = "bufexample/api/hello;hello";
// Buf 官方推荐服务名后面增
service HelloService {
rpc Hello(HelloRequest) returns (HelloResponse) {}
}
message HelloRequest {
string name = 1;
}
message HelloResponse {
string name = 1;
google.protobuf.Timestamp now = 2;
}
完成 Protobuf 协议文件的创建之后，我们的目录如图所示。
.
└── proto
├── api
│ └── hello
│ └── hello.proto
└── buf.yaml
初始化 Buf 代码生成配置
完成 Protobuf 协议编写之后，我们切换回项目目录，并在此创建两个文件，分别是 buf.go.gen.yaml 和 buf.ts.gen.yaml 用于生成 Golang 和 Typescript 的代码。
其中 buf.go.gen.yaml 文件用于生成 Golang 的代码，内容如下所示。
version: v1
plugins:
- plugin: buf.build/protocolbuffers/go
out: ./gengo
# 这个 module 参数其实就是协议 package 的第一个点的名称，去掉的话就会多一层名为 bufexample 的目录
opt: module=bufexample
- plugin: buf.build/grpc/go:v1.3.0
out: ./gengo
# 这个 module 参数其实就是协议 package 的第一个点的名称，去掉的话就会多一层名为 bufexample 的目录
opt: module=bufexample
另一个 buf.ts.gen.yaml 文件用于生成 Typescript 类型定义代码，内容如下所示。
version: v1
plugins:
- plugin: buf.build/bufbuild/es
out: ./gents
值得注意的是两份配置均使用了远程
运行 Buf 生成代码
在完成上述步骤之后，我们可以在项目目录下运行指定命令 buf generate 即可生成代码。
对于 Golang 代码生成，我们可以指定 buf.go.gen.yaml 作为生成配置。
buf generate --template ./buf.go.gen.yaml .
命令运行之后，Buf 工具将会帮助我们生成对应的 Golang 代码，值得注意的是第一次运行需要加载远程插件，具体耗时取决于您的网络条件。
.
├── buf.go.gen.yaml
├── buf.ts.gen.yaml
├── gengo
│ └── api
│ └── hello
│ ├── hello.pb.go
│ └── hello_grpc.pb.go
└── proto
├── api
│ └── hello
│ └── hello.proto
└── buf.yaml
对于 Typescript 类型定义代码，我们可以指定 buf.ts.gen.yaml 作为生成配置。
命令运行之后，Buf 工具将会帮助我们生成对应的 Typescript 类型定义代码，值得注意的是第一次运行同样需要加载远程插件，具体耗时取决于您的网络条件。
.
├── buf.go.gen.yaml
├── buf.ts.gen.yaml
├── gents
│ └── proto
│ └── api
│ └── hello
│ ├── hello_pb.d.ts
│ └── hello_pb.js
└── proto
├── api
│ └── hello
│ └── hello.proto
└── buf.yaml
