Skip to main content

gRPC gateway


With the prevalence of the microservice architecture, the gRPC framework is widely used as a high-performance, cross-language remote process call (RPC).However, gRPC does not apply to all application scenarios.For example, when the client does not support a gRPC protocol or needs to expose the gRPC service to a web application, a way to convert the RESTful API to a gRPC.The gRPC gateway should therefore be created.

Implementation in gRPC brokered go-Zero

The gRPC gateway in go-Zero is a HTTP server that converts RESTful API into a gRPC request and converts gRPC response to RESTful API.The process is as follows::

  1. Resolves the definition of a gRPC service from proto file.
  2. Resolve HTTP mapping rules for gRPC services from the configuration file.
  3. Generate HTTP processor for gRPC services based on the definition of a gRPC service and HTTP mapping rules.
  4. Start HTTP server, handle HTTP requests.
  5. Convert HTTP request to a gRPC request.
  6. Convert gRPC response to HTTP response.
  7. Return HTTP response.

Details can be consulted gateway.

Configure Introduction

type (
GatewayConf struct {
Upstreams []Upstream
Timeout time.Duration `json:",default=5s"`

RouteMapping struct {
Method string
Path string
RpcPath string

Upstream struct {
Name string `json:",optional"`
Grpc zrpc.RpcClientConf
ProtoSets []string `json:",optional"`
Mappings []RouteMapping `json:",optional"`


RestConfrest Service ConfigurationRestConfYESReferenceBasic Service Configuration
UpstreamsgRPC Service Configuration[]UpstreamYES
TimeoutTimeout timedurationNO5s


NameService NamestringNOdemo1-gateway
GrpcgRPC Service ConfigurationRpcClientConfYESReferenceRPC configuration
ProtoSetsproto file list[]stringNO["hello.pb"]
MappingsRoute mapping, do not fill by default all grpc paths[]RouteMappingNO


MethodHTTP methodsstringYESget
PathHTTP PathstringYES/ping
RpcPathgRPC PathstringYEShello.Hello/Ping


In go-zero, there are two ways to use gRPC gateways: protoDescriptor and grpcReflection.

protoDescriptor method requires proto to be a pb file via protoc and then reference the pb file to rest-grpc rule in gateway.


go-zero sdk version v1.5.0 gateway configuration will cause configuration conflicts, please avoid this version, the current example is using v1.4.4 version

1 We create a new project, demo1, and a new hello.proto file in demo1, as follows:

syntax = "proto3";

package hello;

option go_package = "./hello";

message Request {

message Response {
string msg = 1;

service Hello {
rpc Ping(Request) returns(Response);

2 Create the gateway directory in the demo1 directory, and then execute the following command in the demo1 directory to generate the protoDescriptor:

$ protoc --descriptor_set_out=gateway/hello.pb hello.proto

3 Generate the grpc service code by executing the following command in the demo1 directory:

$ goctl rpc protoc hello.proto --go_out=server --go-grpc_out=server --zrpc_out=server

Populate the logic for the Ping method in demo1/server/internal/logic/pinglogic.go with the following code:

func (l *PingLogic) Ping(in *hello.Request) (*hello.Response, error) {
return &hello.Response{
Msg: "pong",
}, nil

4 Modify the configuration file demo1/server/etc/hello.yaml to read as follows:

Name: hello.rpc

5 Go to the demo1/gateway directory, create the directory etc, and add the configuration file gateway.yaml, as follows:

Name: demo1-gateway
Host: localhost
Port: 8888
- Grpc:
Target: localhost:8080
# protoset mode
- hello.pb
# Mappings can also be written in proto options
- Method: get
Path: /ping
RpcPath: hello.Hello/Ping

6 Go to the demo1/gateway directory and create a new gateway.go file with the following contents:

package main

import (


var configFile = flag.String("f", "etc/gateway.yaml", "config file")

func main() {

var c gateway.GatewayConf
conf.MustLoad(*configFile, &c)
gw := gateway.MustNewServer(c)
defer gw.Stop()

7 Open two separate terminals to start the grpc server service and the gateway service, and then visit http://localhost:8888/ping:

# Go to the demo1/server directory and start the grpc service
$ go run hello.go
Starting rpc server at
# Go to the demo1/gateway directory and start the gateway service
$ go run gateway.go
# Open a new terminal and access the gateway service
$ curl http://localhost:8888/ping