2022-07-19 08:55:18 +00:00
# Migrate to `buf` from `prototool`
Why? Because `prototool` is outdated, and can not run on M1 mac.
We need 3 files:
- `build.go` : need to install protoc-gen-\* binaries with pin version in `go.mod`
- `buf.yaml`
- `buf.gen.yaml`
FYI, the libs version I use:
- [golang/protobuf v1.5.2 ](https://github.com/golang/protobuf/releases/tag/v1.5.2 )
- [grpc-ecosystem/grpc-gateway v1.16.0 ](https://github.com/grpc-ecosystem/grpc-gateway/releases/tag/v1.16.0 )
2023-03-20 21:00:21 +00:00
- [bufbuild/protoc-gen-validate ](github.com/bufbuild/protoc-gen-validate )
2022-10-09 11:03:05 +00:00
- [kei2100/protoc-gen-marshal-zap ](github.com/kei2100/protoc-gen-marshal-zap )
2022-07-19 08:55:18 +00:00
`build.go` :
```go
//go:build tools
// +build tools
import (
2022-10-09 11:03:05 +00:00
_ "github.com/golang/protobuf/protoc-gen-go"
_ "github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway"
_ "github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger"
_ "github.com/kei2100/protoc-gen-marshal-zap/plugin/protoc-gen-marshal-zap"
2022-07-19 08:55:18 +00:00
)
```
`buf.yaml`
```yaml
version: v1
deps:
2023-03-20 21:00:21 +00:00
- buf.build/envoyproxy/protoc-gen-validate:6607b10f00ed4a3d98f906807131c44a
- buf.build/kei2100/protoc-gen-marshal-zap:081f499bbca4486784773e060c1c1418
2022-07-19 08:55:18 +00:00
- buf.build/haunt98/googleapis:b38d93f7ade94a698adff9576474ae7c
- buf.build/haunt98/grpc-gateway:ecf4f0f58aa8496f8a76ed303c6e06c7
breaking:
use:
- FILE
lint:
use:
- DEFAULT
```
`buf.gen.yaml` :
```yaml
version: v1
plugins:
- name: go
out: pkg
opt:
- plugins=grpc
2023-03-20 21:00:21 +00:00
- name: buf.build/bufbuild/validate-go:v0.9.0
out: pkg
opt:
- lang=go
- name: marshal-zap
out: pkg
2022-07-19 08:55:18 +00:00
- name: grpc-gateway
out: pkg
opt:
- logtostderr=true
- name: swagger
out: .
opt:
- logtostderr=true
```
Update `Makefile` :
```Makefile
gen:
2022-10-09 11:03:05 +00:00
go install github.com/golang/protobuf/protoc-gen-go
2023-03-20 21:00:21 +00:00
go install github.com/kei2100/protoc-gen-marshal-zap/plugin/protoc-gen-marshal-zap
2022-10-09 11:03:05 +00:00
go install github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
go install github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger
go install github.com/bufbuild/buf/cmd/buf@latest
buf mod update
buf format -w
buf generate
2022-07-19 08:55:18 +00:00
```
2022-10-09 11:03:05 +00:00
Run `make gen` to have fun of course.
2022-07-19 08:55:18 +00:00
2023-03-20 21:00:21 +00:00
If using `bufbuild/protoc-gen-validate` , `kei2100/protoc-gen-marshal-zap` , better make a raw copy of proto file for other services to integrate:
```Makefile
raw:
2023-03-20 21:08:31 +00:00
cp ./api.proto ./raw/
sed -i "" -e "s/import \"validate\/validate\.proto\";//g" ./raw/api.proto
sed -i "" -e "s/\[(validate\.rules)\.string.min_len = 1\]//g" ./raw/api.proto
sed -i "" -e "s/import \"marshal-zap\.proto\";//g" ./raw/api.proto
sed -i "" -e "s/\[(marshal_zap\.mask) = true]//g" ./raw/api.proto
2023-03-20 21:00:21 +00:00
```
2022-07-19 08:55:18 +00:00
## FAQ
2023-03-20 21:00:21 +00:00
Remember `bufbuild/protoc-gen-validate` , `kei2100/protoc-gen-marshal-zap` , `grpc-ecosystem/grpc-gateway` is optional, so feel free to delete if you don't use theme.
2022-10-09 11:03:05 +00:00
2022-07-19 08:55:18 +00:00
If use `vendor` :
- Replace `buf generate` with `buf generate --exclude-path vendor` .
- Replace `buf format -w` with `buf format -w --exclude-path vendor` .
2022-07-30 17:16:44 +00:00
If you use grpc-gateway:
2022-07-19 09:06:55 +00:00
2022-07-30 17:16:44 +00:00
- Replace `import "third_party/googleapis/google/api/annotations.proto";` with `import "google/api/annotations.proto";`
- Delete `security_definitions` , `security` , in `option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger)` .
2022-07-19 09:06:55 +00:00
2022-07-19 08:55:18 +00:00
The last step is delete `prototool.yaml` .
2022-10-09 11:03:05 +00:00
If you are not migrate but start from scratch:
2022-07-30 17:16:44 +00:00
- Add `buf lint` to make sure your proto is good.
- Add `buf breaking --against "https://your-grpc-repo-goes-here.git"` to make sure each time you update proto, you don't break backward compatibility.
2022-07-19 08:55:18 +00:00
## Thanks
- [uber/prototool ](https://github.com/uber/prototool )
- [bufbuild/buf ](https://github.com/bufbuild/buf )