Skip to main content

gRPC gateway

Overview

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 {
        rest.RestConf
        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"`
    }
)

GatewayConf

NameNoteDataTypeRequired?Sample
RestConfrest Service ConfigurationRestConfYESReferenceBasic Service Configuration
UpstreamsgRPC Service Configuration[]UpstreamYES
TimeoutTimeout timedurationNO5s

Upstream

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

RouteMapping

NameNoteDataTypeRequired?Sample
MethodHTTP methodsstringYESget
PathHTTP PathstringYES/ping
RpcPathgRPC PathstringYEShello.Hello/Ping

Examples

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.

tip

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
ListenOn: 0.0.0.0:8080

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
Upstreams:
  - Grpc:
      Target: localhost:8080
    # protoset mode
    ProtoSets:
      - hello.pb
    # Mappings can also be written in proto options
    Mappings:
      - 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 (
    "flag"

    "github.com/zeromicro/go-zero/core/conf"
    "github.com/zeromicro/go-zero/gateway"
)

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

func main() {
    flag.Parse()

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

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 0.0.0.0:8080...
# 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
{"msg":"pong"}%

References

Contents