3.5 KiB

Raw Blame History

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:

build.go:

//go:build tools
// +build tools

import (
  _ "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"
)

buf.yaml

version: v1
deps:
  - buf.build/envoyproxy/protoc-gen-validate:6607b10f00ed4a3d98f906807131c44a
  - buf.build/kei2100/protoc-gen-marshal-zap:081f499bbca4486784773e060c1c1418
  - buf.build/haunt98/googleapis:b38d93f7ade94a698adff9576474ae7c
  - buf.build/haunt98/grpc-gateway:ecf4f0f58aa8496f8a76ed303c6e06c7
breaking:
  use:
    - FILE
lint:
  use:
    - DEFAULT

buf.gen.yaml:

version: v1
plugins:
  - plugin: buf.build/grpc/go:v1.2.0
    out: pkg
  - plugin: buf.build/protocolbuffers/go:v1.28.1
    out: pkg
  - plugin: buf.build/bufbuild/validate-go:v0.9.0
    out: pkg
    opt:
      - lang=go
  - plugin: marshal-zap
    out: pkg
  - plugin: grpc-gateway
    out: pkg
    opt:
      - logtostderr=true
  - plugin: swagger
    out: .
    opt:
      - logtostderr=true

Update Makefile:

gen:
  go install github.com/kei2100/protoc-gen-marshal-zap/plugin/protoc-gen-marshal-zap
  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

Run make gen to have fun of course.

If using bufbuild/protoc-gen-validate, kei2100/protoc-gen-marshal-zap, better make a raw copy of proto file for other services to integrate:

raw:
    mkdir -p ./raw
    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

FAQ

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.

If use vendor:

Replace buf generate with buf generate --exclude-path vendor.
Replace buf format -w with buf format -w --exclude-path vendor.

If you use grpc-gateway:

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).

The last step is delete prototool.yaml.

If you are not migrate but start from scratch:

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.

3.5 KiB Raw Blame History

Migrate to buf from prototool

FAQ

Thanks

3.5 KiB

Raw Blame History

Migrate to `buf` from `prototool`