feat: add migrate to buf
parent
045d946478
commit
aa962c7931
|
|
@ -0,0 +1,65 @@
|
||||||
|
<!doctype html><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><link rel=preconnect href=https://fonts.googleapis.com><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link href="https://fonts.googleapis.com/css2?family=Recursive:wght,CASL,MONO@300..800,0..1,0..1&display=swap" rel=stylesheet><link rel=stylesheet href=styles.css><a href=index>Index</a><h1>Migrate to <code>buf</code> from <code>prototool</code></h1><p>Why? Because <code>prototool</code> is outdated, and can not run on M1 mac.<p>There are 2 usecase:<ul><li>For services only provide GRPC<li>For services provide REST and GRPC, which make use of <a href=https://github.com/grpc-ecosystem/grpc-gateway>grpc-ecosystem/grpc-gateway</a>.</ul><p>We need 3 files:<ul><li><code>build.go</code>: need to install protoc-gen-* binaries with pin version in <code>go.mod</code><li><code>buf.yaml</code><li><code>buf.gen.yaml</code></ul><p>FYI, the libs version I use:<ul><li><a href=https://github.com/golang/protobuf/releases/tag/v1.5.2>golang/protobuf v1.5.2</a><li><a href=https://github.com/grpc-ecosystem/grpc-gateway/releases/tag/v1.16.0>grpc-ecosystem/grpc-gateway v1.16.0</a></ul><h2>GRPC only</h2><p><code>build.go</code>:<pre><code class=language-go>//go:build tools
|
||||||
|
// +build tools
|
||||||
|
|
||||||
|
import (
|
||||||
|
_ "github.com/golang/protobuf/protoc-gen-go"
|
||||||
|
)
|
||||||
|
</code></pre><p><code>buf.yaml</code>:<pre><code class=language-yaml>version: v1
|
||||||
|
breaking:
|
||||||
|
use:
|
||||||
|
- FILE
|
||||||
|
lint:
|
||||||
|
use:
|
||||||
|
- DEFAULT
|
||||||
|
</code></pre><p><code>buf.gen.yml</code><pre><code class=language-yaml>version: v1
|
||||||
|
plugins:
|
||||||
|
- name: go
|
||||||
|
out: pkg
|
||||||
|
opt:
|
||||||
|
- plugins=grpc
|
||||||
|
</code></pre><p>Update <code>Makefile</code>:<pre><code class=language-Makefile>gen:
|
||||||
|
go install github.com/golang/protobuf/protoc-gen-go
|
||||||
|
go install github.com/bufbuild/buf/cmd/buf@latest
|
||||||
|
buf format -w
|
||||||
|
buf generate
|
||||||
|
</code></pre><p>Then run <code>make gen</code> to check result.<h2>REST and GRPC using grpc-gateway</h2><p><code>build.go</code>:<pre><code class=language-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"
|
||||||
|
)
|
||||||
|
</code></pre><p><code>buf.yaml</code><pre><code class=language-yaml>version: v1
|
||||||
|
deps:
|
||||||
|
- buf.build/haunt98/googleapis:b38d93f7ade94a698adff9576474ae7c
|
||||||
|
- buf.build/haunt98/grpc-gateway:ecf4f0f58aa8496f8a76ed303c6e06c7
|
||||||
|
breaking:
|
||||||
|
use:
|
||||||
|
- FILE
|
||||||
|
lint:
|
||||||
|
use:
|
||||||
|
- DEFAULT
|
||||||
|
</code></pre><p><code>buf.gen.yaml</code>:<pre><code class=language-yaml>version: v1
|
||||||
|
plugins:
|
||||||
|
- name: go
|
||||||
|
out: pkg
|
||||||
|
opt:
|
||||||
|
- plugins=grpc
|
||||||
|
- name: grpc-gateway
|
||||||
|
out: pkg
|
||||||
|
opt:
|
||||||
|
- logtostderr=true
|
||||||
|
- name: swagger
|
||||||
|
out: .
|
||||||
|
opt:
|
||||||
|
- logtostderr=true
|
||||||
|
</code></pre><p>Update <code>Makefile</code>:<pre><code class=language-Makefile>gen:
|
||||||
|
go install github.com/golang/protobuf/protoc-gen-go
|
||||||
|
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 format -w
|
||||||
|
buf mod update
|
||||||
|
buf generate
|
||||||
|
</code></pre><p>Run <code>make gen</code> to get fun of course.<h2>FAQ</h2><p>If use <code>vendor</code>:<ul><li>Replace <code>buf generate</code> with <code>buf generate --exclude-path vendor</code>.<li>Replace <code>buf format -w</code> with <code>buf format -w --exclude-path vendor</code>.</ul><p>The last step is delete <code>prototool.yaml</code>.<h2>Thanks</h2><ul><li><a href=https://github.com/uber/prototool>uber/prototool</a><li><a href=https://github.com/bufbuild/buf>bufbuild/buf</a></ul><a href=mailto:hauvipapro+posts@gmail.com>Feel free to ask me via email</a>
|
||||||
|
|
@ -0,0 +1,145 @@
|
||||||
|
# Migrate to `buf` from `prototool`
|
||||||
|
|
||||||
|
Why? Because `prototool` is outdated, and can not run on M1 mac.
|
||||||
|
|
||||||
|
There are 2 usecase:
|
||||||
|
|
||||||
|
- For services only provide GRPC
|
||||||
|
- For services provide REST and GRPC, which make use of [grpc-ecosystem/grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway).
|
||||||
|
|
||||||
|
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)
|
||||||
|
|
||||||
|
## GRPC only
|
||||||
|
|
||||||
|
`build.go`:
|
||||||
|
|
||||||
|
```go
|
||||||
|
//go:build tools
|
||||||
|
// +build tools
|
||||||
|
|
||||||
|
import (
|
||||||
|
_ "github.com/golang/protobuf/protoc-gen-go"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
`buf.yaml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: v1
|
||||||
|
breaking:
|
||||||
|
use:
|
||||||
|
- FILE
|
||||||
|
lint:
|
||||||
|
use:
|
||||||
|
- DEFAULT
|
||||||
|
```
|
||||||
|
|
||||||
|
`buf.gen.yml`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: v1
|
||||||
|
plugins:
|
||||||
|
- name: go
|
||||||
|
out: pkg
|
||||||
|
opt:
|
||||||
|
- plugins=grpc
|
||||||
|
```
|
||||||
|
|
||||||
|
Update `Makefile`:
|
||||||
|
|
||||||
|
```Makefile
|
||||||
|
gen:
|
||||||
|
go install github.com/golang/protobuf/protoc-gen-go
|
||||||
|
go install github.com/bufbuild/buf/cmd/buf@latest
|
||||||
|
buf format -w
|
||||||
|
buf generate
|
||||||
|
```
|
||||||
|
|
||||||
|
Then run `make gen` to check result.
|
||||||
|
|
||||||
|
## REST and GRPC using grpc-gateway
|
||||||
|
|
||||||
|
`build.go`:
|
||||||
|
|
||||||
|
```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"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
`buf.yaml`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: v1
|
||||||
|
deps:
|
||||||
|
- 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
|
||||||
|
- name: grpc-gateway
|
||||||
|
out: pkg
|
||||||
|
opt:
|
||||||
|
- logtostderr=true
|
||||||
|
- name: swagger
|
||||||
|
out: .
|
||||||
|
opt:
|
||||||
|
- logtostderr=true
|
||||||
|
```
|
||||||
|
|
||||||
|
Update `Makefile`:
|
||||||
|
|
||||||
|
```Makefile
|
||||||
|
gen:
|
||||||
|
go install github.com/golang/protobuf/protoc-gen-go
|
||||||
|
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 format -w
|
||||||
|
buf mod update
|
||||||
|
buf generate
|
||||||
|
```
|
||||||
|
|
||||||
|
Run `make gen` to get fun of course.
|
||||||
|
|
||||||
|
## FAQ
|
||||||
|
|
||||||
|
If use `vendor`:
|
||||||
|
|
||||||
|
- Replace `buf generate` with `buf generate --exclude-path vendor`.
|
||||||
|
- Replace `buf format -w` with `buf format -w --exclude-path vendor`.
|
||||||
|
|
||||||
|
The last step is delete `prototool.yaml`.
|
||||||
|
|
||||||
|
## Thanks
|
||||||
|
|
||||||
|
- [uber/prototool](https://github.com/uber/prototool)
|
||||||
|
- [bufbuild/buf](https://github.com/bufbuild/buf)
|
||||||
Loading…
Reference in New Issue