奇技指南

gRPC是一个高性能、通用的开源 RPC 框架，由 Google 开发并基于 HTTP/2 协议标准而设计。本文介绍花椒服务端的 gRPC 开发实践。

本文来自花椒技术。

背景

在移动端平台开发中，为了增加代码复用，降低开发成本，通常会需要采用跨平台的开发技术，花椒也不例外。本次新的单品开发，由于时间紧，人员有限，经过调研选型，最终确定了 flutter 方案（具体选型过程不在本文讨论之内）。

为了让客户端更专注业务实现，降低接口联调测试成本，我们选用了 gRPC 方案。gRPC是一个高性能、通用的开源 RPC 框架，由 Google 开发并基于 HTTP/2 协议标准而设计，基于 ProtoBuf(Protocol Buffers)序列化协议开发，且支持当前主流开发语言。gRPC通过定义一个服务并指定一个可以远程调用的带有参数和返回类型的的方法，使客户端可以直接调用不同机器上的服务应用的方法，就像是本地对象一样。在服务端，服务实现这个接口并且运行 gRPC 服务处理客户端调用。在客户端，有一个stub提供和服务端相同的方法。

gRPC特点

• 基于标准化的 IDL（ProtoBuf）来生成服务器端和客户端代码，支持多种主流开发语言。同时可以更好的支持团队与团队之间的接口设计，开发，测试，协作等。

• 基于 HTTP/2 设计，支持双向流，多路复用，头部压缩。

• 支持流式发送和响应，批量传输数据，提升性能。

• ProtoBuf 序列化数据抓包、调试难度较大。我们使用服务端注入方式提供了用户或设备过滤，请求及返回值日志捕获，并开发对应后台模拟抓包展示。

• 相比 JSON， 对前端不够友好。gRPC 生态 提供了 gateway 的方式为 gRPC 服务代理出 RESTful 接口。

• ProtoBuf 提供了非常强的扩展性，可以为 protoc 开发定制插件，从而扩展 proto 文件的功能及描述性。

gRPC-Web

gRPC-Web 为前端浏览器提供了 Javascript 库用来访问 gRPC 服务，但是需要通过 Envoy 提供代理服务。相比 JSON 的方式对前端有够友好，同时也增加了服务端的部署成本。因此在这次项目中前端未使用 gRPC 服务，而是由 gRPC-Gateway 提供代理的 RESTful 接口。

gRPC-Gateway

grpc-gateway 是 protoc 的一个插件，它能读取 gRPC 的服务定义并生成反向代理服务器，将 RESTful 的 JSON 请求转换为 gRPC 的方式。这样无需太多工作即可实现一套基于 gRPC 服务的 RESTful 接口，方便前端使用调用接口，同时也方便开发过程中通过 Postman/Paw 之类的工具调试接口。

gateway -> gRPC 映射方式：

• HTTP 源 IP 添加到 gRPC 的 X-Forwarded-For 请求头

• HTTP 请求 Host 添加到 gRPC 的 X-Forwarded-Host 请求头

• HTTP 请求头 Authorization 添加到 gRPC 的 authorization 请求头

• HTTP 请求头带 Grpc-Metadata- 前缀的映射到 gRPC 的 metadata (key 名不带前缀)

例如，gRPC 接口要求的通用的 metadata 参数（如 platform, device_id 等）在 HTTP RESTful 的传递方式如下：

1GET /index HTTP/1.1
2grpc-metadata-platform: ios
3grpc-metadata-device_id: xxxxxxxxx
4grpc-metadata-timestamp: 1562641496
5grpc-metadata-locale: en_US
6grpc-metadata-version: 1.0.0
7grpc-metadata-user_id: 
8grpc-metadata-user_token: 
9Host: gateway.hostame.com

基础库

dart

为了便于客户端调用，连接复用及通用参数传递，我们封装了 dart 的基础库。

BaseClient 维护了针对 HOST 缓存的连接池，同时也提供了接口需要传递的 metadata 信息。

1var base = BaseClient(host: 'rpc.hostame.com', port: 443, secure: true);
2final md = await base.metadata;
3final stub = AuthClient(base.channel, options: CallOptions(metadata: md));

golang

golang 后端服务需要同时支持 gRPC 和 gateway 两种请求方式。为了简化部署和上线依赖，gateway 和 gRPC 的功能放在了一起，并通过拦截器注入对应的功能，主要包括 gRPC 统计，访问日志，接口鉴权，请求参数校验，gateway JSON 编码等。

 1    svrMux := &ServerMux{
 2      ...
 3        ServeMux: http.NewServeMux(),
 4    }
 5    svrMux.svr = grpc.NewServer(
 6        grpc.UnaryInterceptor(
 7            middleware.ChainUnaryServer(
 8                recovery.UnaryServerInterceptor(recovery.WithRecoveryHandler(svrMux.recoveryHandler)),
 9                prometheus.UnaryServerInterceptor, // prometheus 统计
10                svrMux.UnaryResponseInterceptor(),
11                proto.UnaryServerInterceptor(), // metadata 解析
12                log.UnaryServerInterceptor(conf.GlobalCallback()), // 访问日志
13                auth.UnaryServerInterceptor(conf.GlobalCallback()), // 接口鉴权
14                validator.UnaryServerInterceptor(), // 请求参数校验
15            )),
16        grpc.StreamInterceptor(
17            middleware.ChainStreamServer(
18                ...
19            )))
20    svrMux.mux = runtime.NewServeMux(
21        runtime.WithMarshalerOption(runtime.MIMEWildcard, json.Proto), // json 设置
22        runtime.WithProtoErrorHandler(svrMux.protoErrorHandler), // 错误处理
23        runtime.WithStreamErrorHandler(svrMux.streamErrorHandler),
24    )
25    // gRPC gateway mux
26    svrMux.ServeMux.Handle("/", svrMux.mux)

引用到的 package

1github.com/golang/protobuf
2github.com/grpc-ecosystem/go-grpc-middleware
3github.com/grpc-ecosystem/go-grpc-prometheus
4github.com/grpc-ecosystem/grpc-gateway
5github.com/lnnujxxy/protoc-gen-validate
6github.com/youlu-cn/grpc-gen
7go.uber.org/zap
8google.golang.org/grpc

开发流程

为了提高开发效率，方便维护及模块复用，服务端按功能进行组件化开发。每个组件可以单独运行一个服务，也可以和其它组件共同组成一个服务。每个组件都需要实现 Component 接口：

 1type Component interface {
 2    // 组件名称
 3    Name() string
 4    // 初始化存储
 5    InitStorage() error
 6    // 初始化注册 gRPC
 7    InitGRPC(svc Service) error
 8    // 初始化注册 gateway
 9    InitGateway(svc Service) error
10    // cron 回调
11    StorageCron()
12}

对应组件开发完成后，需要开发对应的服务容器，步骤如下。

• 初始化 base package

1base.Init(context.TODO(), cfg, &global.Callback{
2    Authenticator: &auth.Callback{},
3    LogCapture:    &log.Capture{},
4})

• 如需对外提供服务，需要提供端口及 TLS 证书

base.DefaultServer.AddPublicServer(rpcPort, gatewayPort, setting.TLSConfig)

• 组件注册

1base.DefaultServer.RegisterComponent(&user.Component{})
2base.DefaultServer.RegisterComponent(&push.Component{})
3...

• 监听服务

base.DefaultServer.Serve()

接口定义及实现

proto 规范

gRPC 基于标准化的 IDL（ProtoBuf）来生成服务器端和客户端代码，我们决定将所有的接口描述及文档说明都放到 proto 文件中，便于查看及修改。对 proto 的接口描述及注释的规范如下：

 1// 消息类型注释，支持多行，
 2// 支持 markdown 语法：
 3//
 4// > blockquote
 5//
 6// | Syntax | Description |
 7// | ----------- | ----------- |
 8// | Header | Title |
 9// | Paragraph | Text |
10message ExampleMessage {
11    uint64 id = 1; // 字段注释，简洁
12}
13
14// 服务说明，支持 markdown 语法
15//
16// 1. First item
17// 2. Second item
18// 3. Third item
19//
20// ```json
21// {
22//   "firstName": "John",
23//   "lastName": "Smith",
24//   "age": 25
25// }
26// ```
27service Example {
28    option (auth.visible) = {
29        scope: PUBLIC_SCOPE // Service scope：仅内网可见或对外可见
30    };
31
32    // 方法说明，支持 markdown
33    //
34    // - [x] Write the press release
35    // - [ ] Update the website
36    // - [ ] Contact the media
37    rpc test (ExampleMessage) returns (ExampleMessage) {
38        option (auth.access) = {
39            level: LOW_ACCESS_LEVEL // 接口请求权限
40        };
41        option (google.api.http) = {
42            post: "/example/test"
43            body: "*"
44        };
45    }
46}

代码生成

golang

 1gengo:
 2    @protoc -Iproto \
 3        -I${GOPATH}/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
 4        -I${GOPATH}/src/github.com/lnnujxxy/protoc-gen-validate \
 5        -I${GOPATH}/src/github.com/youlu-cn/grpc-gen/protoc-gen-auth \
 6        --go_out=plugins=grpc:go/pb \
 7        --grpc-gateway_out=logtostderr=true:go/pb \
 8        --validate_out="lang=go:go/pb" \
 9        --auth_out="lang=go:go/pb" \
10        proto/*.proto

SDK 引入

golang 使用 go mod 的方式直接引入 pb 生成的 .go 文件

dart

 1ifeq ($(shell uname), Darwin)
 2PROTO_ROOT_DIR = $(shell brew --prefix)/Cellar/protobuf/*
 3else
 4PROTO_ROOT_DIR = /usr/local
 5endif
 6
 7gendart:
 8    @protoc --dart_out=dart/front_user/lib/src/generated $(PROTO_ROOT_DIR)/include/google/protobuf/*.proto
 9    @protoc -Iproto \
10        -I${GOPATH}/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
11        -I${GOPATH}/src/github.com/lnnujxxy/protoc-gen-validate \
12        -I${GOPATH}/src/github.com/youlu-cn/grpc-gen/protoc-gen-auth \
13        --dart_out=grpc:dart/user/lib proto/*.proto

SDK 引入

修改 pubspec.yaml，执行 flutter packages get 或 flutter packages upgrade

 1dependencies:
 2  flutter:
 3    sdk: flutter
 4
 5  protobuf: ^0.13.4
 6  grpc: ^1.0.1
 7  user:
 8    git:
 9      url: [email protected]:project/repo.git
10      path: dart/user

已知问题：

dart 在对 protobuf 生成的类型做 json 编码时，json 中的 key 是字段号而非名字，导致无法与其它语言交互。ISSUE (https://github.com/dart-lang/protobuf/issues/220)

文档生成

gRPC gateway 提供了通过 proto 文件生成 swagger API 文档，缺点是只支持 gateway 的 RESTful 接口，并且默认的展示方式有点不符合我们的常规文档使用方式。

我们基于 protoc 插件开发了 protoc-gen-markdown 工具，可以由 proto 文件生成 markdown 文档，提供 gRPC 接口描述，以及 RESTful 接口描述及 JSON 示例，提供全文目录，支持锚点导航等。生成方式如下：

1gendoc:
2    @protoc -Iproto \
3        -I${GOPATH}/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
4        -I${GOPATH}/src/github.com/lnnujxxy/protoc-gen-validate \
5        -I${GOPATH}/src/github.com/youlu-cn/grpc-gen/protoc-gen-auth \
6        --markdown_out=":doc" \
7        proto/*.proto

文档会在对应路径生成接口列表 README.md，以及每个 protobuf 对应的接口文档。

调试

传统的 RESTful 接口在调试及问题排查时，可以通过抓包或者 MitM（中间人攻击）的方式，配置也比较容易。而 gRPC 因为使用了 HTTP2 及 protobuf 二进制流，抓包及数据流反解难度相对较高，调试及问题排查时会比较复杂。为了解决这个问题，我们通过服务端注入的方式，配合查询后台过滤对应的请求日志，从而实现如下类似抓包的效果。

后续计划

1. gRPC Streaming

2. 框架层集成全链路 Trace 支持

3. 迭代优化框架，提供对应脚手架，简化新组件/服务创建及开发流程

界世的你当不

只做你的肩膀

无

 360官方技术公众号 

技术干货|一手资讯|精彩活动

空·