protoc-gen-echo is a protoc plug-in that generates Echo server code from proto file.
If you want to create a Echo's http api /helloworld/:name/hi/:nice, you just need to add rpc in a proto file, and generate it.
/helloworld/:name/hi/:nice mapping http api will be generated by protoc-gen-echo.
protoc-gen-echo can generate complete backend all code combination with protoc-gen-ent.
** About ent you can find more help from ent.
sudo apt install protobuf-compiler make service Greeter { // Sends a greeting rpc SayHello (HelloRequest) returns (HelloReply) { option (google.api.http) = { get: "/helloworld/{name}/hi/{nice}" }; } //... } //... You can generate code used by make:
make example Or you can generate code used by below too:
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest go install github.com/go-woo/protoc-gen-echo@latest protoc --proto_path=. \ --proto_path=./third_party \ --go_out=paths=source_relative:. \ --echo_out=paths=source_relative:. \ ./example/v1/greeter.proto The protoc-gen-echo generated 2 files:greeter_router.pb.go and greeter_handler.pb.go.
The greeter.pb.go was generated by protoc-gen-go
More help can be found in protoc.
Your business logic stubs has been generated in your_xxxx_handler.pb.go, You can edit business logic in stubs.
func $(YourService)$(RpcName)BusinessHandler(payload *YourRequest) (YourReply, error) { // Here can put your business logic, can use ORM:github.com/go-woo/protoc-gen-ent return YourReply{}, nil } All handlers typo can be found in your_xxxx_router.pb.go.
For this example, in greeter_router.pb.go. You can find generated echo's handler _Greeter_SayHello0_HTTP_Handler.
func RegisterGreeterRouter(e *echo.Echo) { e.GET("/helloworld/:name/hi/:nice", _Greeter_SayHello0_HTTP_Handler) //... } In same file, you can find _Greeter_SayHello0_HTTP_Handler's implement:
func _Greeter_SayHello0_HTTP_Handler(c echo.Context) error { var req *HelloRequest = new(HelloRequest) req.Name = c.Param(strings.ToLower("Name")) req.Nice = c.Param(strings.ToLower("Nice")) reply, err := GreeterSayHelloBusinessHandler(req, c) if err != nil { return err } return c.JSON(http.StatusOK, &reply) } Our focus is on GreeterSayHelloBusinessHandler(payload). In greeter_handler.pb.go, you can write business logic.
func GreeterSayHelloBusinessHandler(req *HelloRequest, c echo.Context) (HelloReply, error) { // Here can put your business logic,protoc-gen-ent soon coming reqJson, err := json.Marshal(req) if err != nil { return HelloReply{}, err } fmt.Printf("Got HelloRequest is: %v\n", string(reqJson)) return HelloReply{}, nil } For running this example we need to write a main.go
package main import ( v1 "github.com/go-woo/protoc-gen-echo/example/v1" "github.com/labstack/echo/v4" "github.com/labstack/echo/v4/middleware" ) func main() { e := echo.New() e.Use(middleware.Logger()) e.Use(middleware.Recover()) v1.RegisterGreeterRouter(e) // you can add custom router outside protoc-gen-echo too. // MyCustomRouter(e) e.Logger.Fatal(e.Start(":1323")) } More help and doc can be found on Echo , include rate limited, auto update TLS cert, etc.
cd example && go run main.go Open browser, URL:http://localhost:1223/helloworld/Lok-Tar/hi/Ogar
Or shell execute
curl -X GET http://localhost:1323/helloworld/Lok-Tar/hi/Ogar Service option
//get token URL option (google.api.default_host) = "/login"; //need auth root path, can multi path option (google.api.oauth_scopes) = "/restricted," was used for JWT describer.
If you want to support JWT, can add it. Else you can comment it.
-
Do not remove
your_xxxx_handler.pb.go. It was generated only when the first time, and will not be generated or overwritten after that again, because the business logic code you added is already in it. -
JSON format in http body. If http client request has body, header should has
Content-Type: application/json -
Validate. Single source(proto) is the most important means to ensure consistency. protobuf message filed validate can use protoc-gen-validate.
-
protoc-gen-echofollow google.api.httprule. -
ent still does not support message nesting, so proto http rule body must be *.
gRPC generated by protoc-gen-go-grpc
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest Add --go-grpc_out=paths=source_relative:. \
protoc --proto_path=. \ --proto_path=./third_party \ --go_out=paths=source_relative:. \ --echo_out=paths=source_relative:. \ --go-grpc_out=paths=source_relative:. \ ./example/v1/greeter.proto OAS generated by protoc-gen-openapi
go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest Add --openapi_out=paths=source_relative:. \
protoc --proto_path=. \ --proto_path=./third_party \ --go_out=paths=source_relative:. \ --echo_out=paths=source_relative:. \ --openapi_out=paths=source_relative:. \ ./example/v1/greeter.proto Generated yaml file can be browser on swagger or openapi
Fields validate generated by protoc-gen-validate
go install github.com/envoyproxy/protoc-gen-validate@latest Add --validate_out="lang=go:." \
protoc --proto_path=. \ --proto_path=./third_party \ --go_out=paths=source_relative:. \ --echo_out=paths=source_relative:. \ --validate_out="lang=go:." \ ./example/v1/greeter.proto - Add generate jwt openapi/swagger support
https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#securitySchemeObject https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto