yoshie
/
posts-go
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat: add buf lint, buf breaking

main
sudo pacman -Syu 2022-07-31 00:16:44 +07:00
parent 1f34c69ec8
commit 3c000a273a
No known key found for this signature in database
GPG Key ID: D6CB5C6C567C47B0
2 changed files with 16 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/2022-07-19-migrate-to-buf.html
View File

@ -1,4 +1,4 @@
<!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
<!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 use cases:<ul><li>For services only provide gRPC.<li>For services provide both 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 (
@ -22,7 +22,7 @@ plugins:
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
</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 (
@ -62,4 +62,4 @@ plugins:
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>Replace <code>import "third_party/googleapis/google/api/annotations.proto";</code> with <code>import "google/api/annotations.proto";</code><p>Delete <code>security_definitions</code>, <code>security</code>, in <code>option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger)</code>.<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>
</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>If you use grpc-gateway:<ul><li>Replace <code>import "third_party/googleapis/google/api/annotations.proto";</code> with <code>import "google/api/annotations.proto";</code><li>Delete <code>security_definitions</code>, <code>security</code>, in <code>option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger)</code>.</ul><p>The last step is delete <code>prototool.yaml</code>.<p>If you are not migrate but start new:<ul><li>Add <code>buf lint</code> to make sure your proto is good.<li>Add <code>buf breaking --against "https://your-grpc-repo-goes-here.git"</code> to make sure each time you update proto, you don't break backward compatibility.</ul><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>

20
posts/2022-07-19-migrate-to-buf.md
View File

@ -2,10 +2,10 @@
Why? Because `prototool` is outdated, and can not run on M1 mac.
There are 2 usecase:
There are 2 use cases:
- 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).
- For services only provide gRPC.
- For services provide both REST and gRPC, which make use of [grpc-ecosystem/grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway).
We need 3 files:
@ -18,7 +18,7 @@ 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
## gRPC only
`build.go`:
@ -66,7 +66,7 @@ gen:
Then run `make gen` to check result.
## REST and GRPC using grpc-gateway
## REST and gRPC using grpc-gateway
`build.go`:
@ -137,12 +137,18 @@ If use `vendor`:
- Replace `buf generate` with `buf generate --exclude-path vendor`.
- Replace `buf format -w` with `buf format -w --exclude-path vendor`.
Replace `import "third_party/googleapis/google/api/annotations.proto";` with `import "google/api/annotations.proto";`
If you use grpc-gateway:
Delete `security_definitions`, `security`, in `option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger)`.
- 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 new:
- 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.
## Thanks
- [uber/prototool](https://github.com/uber/prototool)