The grpc-gateway is a plugin of the Google protocol buffers compiler
protoc.
It reads protobuf service definitions and generates a reverse-proxy server which
translates a RESTful HTTP API into gRPC. This server is generated according to the
google.api.http
annotations in your service definitions.
This helps you provide your APIs in both gRPC and RESTful style at the same time.
We use the gRPC-Gateway to serve millions of API requests per day, and have been since 2018, and through all of that, we have never had any issues with it.
- William Mill, Ad Hoc
gRPC is great -- it generates API clients and server stubs in many programming languages, it is fast, easy-to-use, bandwidth-efficient and its design is combat-proven by Google. However, you might still want to provide a traditional RESTful JSON API as well. Reasons can range from maintaining backward-compatibility, supporting languages or clients that are not well supported by gRPC, to simply maintaining the aesthetics and tooling involved with a RESTful JSON architecture.
This project aims to provide that HTTP+JSON interface to your gRPC service. A small amount of configuration in your service to attach HTTP semantics is all that's needed to generate a reverse-proxy with this library.
The grpc-gateway requires a local installation of the Google protocol buffers
compiler protoc
v3.0.0 or above. Please install this via your local package
manager or by downloading one of the releases from the official repository:
https://github.com/protocolbuffers/protobuf/releases
The following instructions assume you are using Go Modules for dependency management. Use a tool dependency to track the versions of the following executable packages:
// +build tools
package tools
import (
_ "github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway"
_ "github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger"
_ "github.com/golang/protobuf/protoc-gen-go"
)
Run go mod tidy
to resolve the versions. Install by running
$ go install \
github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway \
github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger \
github.com/golang/protobuf/protoc-gen-go
This will place three binaries in your $GOBIN
;
protoc-gen-grpc-gateway
protoc-gen-swagger
protoc-gen-go
Make sure that your $GOBIN
is in your $PATH
.
Define your gRPC service using protocol buffers
your_service.proto
:
syntax = "proto3";
package example;
message StringMessage {
string value = 1;
}
service YourService {
rpc Echo(StringMessage) returns (StringMessage) {}
}
Add a google.api.http
annotation to your .proto file
your_service.proto
:
syntax = "proto3";
package example;
+
+import "google/api/annotations.proto";
+
message StringMessage {
string value = 1;
}
service YourService {
- rpc Echo(StringMessage) returns (StringMessage) {}
+ rpc Echo(StringMessage) returns (StringMessage) {
+ option (google.api.http) = {
+ post: "/v1/example/echo"
+ body: "*"
+ };
+ }
}
You will need to provide the required third party protobuf files to the
protoc
compiler. They are included in this repo under thethird_party/googleapis
folder, and we recommend copying them into yourprotoc
generation file structure. If you've structured your proto files according to something like the Buf style guide, you could copy the files into a top-level
See a_bit_of_everything.proto for examples of more annotations you can add to customize gateway behavior and generated Swagger output.
If you do not want to modify the proto file for use with grpc-gateway you can alternatively use an external gRPC Service Configuration file. Check our documentation for more information.
Generate gRPC stub
Here is an example of what a protoc
command might look like:
protoc -I. --go_out=plugins=grpc,paths=source_relative:./gen/go/ your/service/v1/your_service.proto
It will generate a stub file with path ./gen/go/your/service/v1/your_service.pb.go
.
Implement your service in gRPC as usual
For example, the following generates gRPC code for Ruby based on your/service/v1/your_service.proto
:
protoc -I. --ruby_out=./gen/ruby your/service/v1/your_service.proto
protoc -I. --grpc-ruby_out=./gen/ruby your/service/v1/your_service.proto
Generate reverse-proxy using protoc-gen-grpc-gateway
protoc -I. --grpc-gateway_out=logtostderr=true,paths=source_relative:./gen/go \
your/service/v1/your_service.proto
It will generate a reverse proxy gen/go/your/service/v1/your_service.pb.gw.go
.
Write an entrypoint for the HTTP reverse-proxy server
package main
import (
"context"
"flag"
"net/http"
"github.com/golang/glog"
"github.com/grpc-ecosystem/grpc-gateway/runtime"
"google.golang.org/grpc"
gw "github.com/yourorg/yourrepo/proto/gen/go/your/service/v1/your_service" // Update
)
var (
// command-line options:
// gRPC server endpoint
grpcServerEndpoint = flag.String("grpc-server-endpoint", "localhost:9090", "gRPC server endpoint")
)
func run() error {
ctx := context.Background()
ctx, cancel := context.WithCancel(ctx)
defer cancel()
// Register gRPC server endpoint
// Note: Make sure the gRPC server is running properly and accessible
mux := runtime.NewServeMux()
opts := []grpc.DialOption{grpc.WithInsecure()}
err := gw.RegisterYourServiceHandlerFromEndpoint(ctx, mux, *grpcServerEndpoint, opts)
if err != nil {
return err
}
// Start HTTP server (and proxy calls to gRPC server endpoint)
return http.ListenAndServe(":8081", mux)
}
func main() {
flag.Parse()
defer glog.Flush()
if err := run(); err != nil {
glog.Fatal(err)
}
}
(Optional) Generate swagger definitions using protoc-gen-swagger
protoc -I. --swagger_out=logtostderr=true:./gen/swagger your/service/v1/your_service.proto
This GopherCon UK 2019 presentation from our maintainer @JohanBrandhorst provides a good intro to using the grpc-gateway. It uses the following boilerplate repo as a base: https://github.com/johanbrandhorst/grpc-gateway-boilerplate.
During code generation with protoc
, flags to grpc-gateway tools must be passed
through protoc using the --<tool_suffix>_out=<flags>:<path>
pattern, for
example:
--grpc-gateway_out=logtostderr=true,repeated_path_param_separator=ssv:.
--swagger_out=logtostderr=true,repeated_path_param_separator=ssv:.
protoc-gen-grpc-gateway
supports custom mapping from Protobuf import
to
Golang import paths. They are compatible with
the parameters with the same names in protoc-gen-go
.
In addition we also support the request_context
parameter in order to use the
http.Request
's Context (only for Go 1.7 and above). This parameter can be
useful to pass the request-scoped context between the gateway and the gRPC service.
protoc-gen-grpc-gateway
also supports some more command line flags to control
logging. You can give these flags together with parameters above. Run
protoc-gen-grpc-gateway --help
for more details about the flags.
Similarly, protoc-gen-swagger
supports command-line flags to control Swagger
output (for example, json_names_for_fields
to output JSON names for fields
instead of protobuf names). Run protoc-gen-swagger --help
for more flag
details. Further Swagger customization is possible by annotating your .proto
files with options from
openapiv2.proto - see
a_bit_of_everything.proto
for examples.
More examples are available under examples
directory.
proto/examplepb/echo_service.proto
, proto/examplepb/a_bit_of_everything.proto
, proto/examplepb/unannotated_echo_service.proto
: service definition
proto/examplepb/echo_service.pb.go
, proto/examplepb/a_bit_of_everything.pb.go
, proto/examplepb/unannotated_echo_service.pb.go
: [generated] stub of the serviceproto/examplepb/echo_service.pb.gw.go
, proto/examplepb/a_bit_of_everything.pb.gw.go
, proto/examplepb/uannotated_echo_service.pb.gw.go
: [generated] reverse proxy for the serviceproto/examplepb/unannotated_echo_service.yaml
: gRPC API Configuration for unannotated_echo_service.proto
server/main.go
: service implementationmain.go
: entrypoint of the generated reverse proxyTo use the same port for custom HTTP handlers (e.g. serving swagger.json
),
gRPC-gateway, and a gRPC server, see
this example by CoreOS
(and its accompanying blog post).
Grpc-Metadata-
prefix to gRPC metadata (prefixed with grpcgateway-
)Grpc-Timeout
header.But patch is welcome.
X-Forwarded-For
gRPC request header.X-Forwarded-Host
gRPC request header.Authorization
header is added as authorization
gRPC request header.grpcgateway-
and added with their values to gRPC request
header.grpcgateway-
).OrigName: true
.See CONTRIBUTING.md.
grpc-gateway is licensed under the BSD 3-Clause License. See LICENSE.txt for more details.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。