4.8 grpcurl工具

Protobuf本身具有反射功能，可以在运行时获取对象的Proto文件。grpc同样也提供了一个名为reflection的反射包，用于为grpc服务提供查询。GRPC官方提供了一个C++实现的grpc_cli工具，可以用于查询GRPC列表或调用GRPC方法。但是C++版本的grpc_cli安装比较复杂，我们推荐用纯Go语言实现的grpcurl工具。本节将简要介绍grpcurl工具的用法。

4.8.1 启动反射服务

reflection包中只有一个Register函数，用于将grpc.Server注册到反射服务中。reflection包文档给出了简单的使用方法：

  1. import (
  2.     "google.golang.org/grpc/reflection"
  3. )
  5. func main() {
  6.     s := grpc.NewServer()
  7.     pb.RegisterYourOwnServer(s, &server{})
  9.     // Register reflection service on gRPC server.
  10.     reflection.Register(s)
  12.     s.Serve(lis)
  13. }

如果启动了gprc反射服务，那么就可以通过reflection包提供的反射服务查询GRPC服务或调用GRPC方法。

4.8.2 查看服务列表

grpcurl是Go语言开源社区开发的工具，需要手工安装：

  1. $ go get github.com/fullstorydev/grpcurl
  2. $ go install github.com/fullstorydev/grpcurl/cmd/grpcurl

grpcurl中最常使用的是list命令，用于获取服务或服务方法的列表。比如grpcurl localhost:1234 list命令将获取本地1234端口上的grpc服务的列表。在使用grpcurl时，需要通过-cert和-key参数设置公钥和私钥文件，链接启用了tls协议的服务。对于没有没用tls协议的grpc服务，通过-plaintext参数忽略tls证书的验证过程。如果是Unix Socket协议，则需要指定-unix参数。

如果没有配置好公钥和私钥文件，也没有忽略证书的验证过程，那么将会遇到类似以下的错误：

  1. $ grpcurl localhost:1234 list
  2. Failed to dial target host "localhost:1234": tls: first record does not look like a TLS handshake

如果grpc服务正常，但是服务没有启动reflection反射服务，将会遇到以下错误：

  1. $ grpcurl -plaintext localhost:1234 list
  2. Failed to list services: server does not support the reflection API

假设grpc服务已经启动了reflection反射服务，服务的Protobuf文件如下：

  1. syntax = "proto3";
  3. package HelloService;
  5. message String {
  6.     string value = 1;
  7. }
  9. service HelloService {
  10.     rpc Hello (String) returns (String);
  11.     rpc Channel (stream String) returns (stream String);
  12. }

grpcurl用list命令查看服务列表时将看到以下输出：

  1. $ grpcurl -plaintext localhost:1234 list
  2. HelloService.HelloService
  3. grpc.reflection.v1alpha.ServerReflection

其中HelloService.HelloService是在protobuf文件定义的服务。而ServerReflection服务则是reflection包注册的反射服务。通过ServerReflection服务可以查询包括本身在内的全部GRPC服务信息。

4.8.3 服务的方法列表

继续使用list子命令还可以查看HelloService服务的方法列表：

  1. $ grpcurl -plaintext localhost:1234 list HelloService.HelloService
  2. Channel
  3. Hello

从输出可以看到HelloService服务提供了Channel和Hello两个方法，和Protobuf文件的定义是一致的。

如果还想了解方法的细节，可以使用grpcurl提供的describe子命令查看更详细的描述信息：

  1. $ grpcurl -plaintext localhost:1234 describe HelloService.HelloService
  2. HelloService.HelloService is a service:
  3. {
  4.   "name": "HelloService",
  5.   "method": [
  6.     {
  7.       "name": "Hello",
  8.       "inputType": ".HelloService.String",
  9.       "outputType": ".HelloService.String",
  10.       "options": {
  12.       }
  13.     },
  14.     {
  15.       "name": "Channel",
  16.       "inputType": ".HelloService.String",
  17.       "outputType": ".HelloService.String",
  18.       "options": {
  20.       },
  21.       "clientStreaming": true,
  22.       "serverStreaming": true
  23.     }
  24.   ],
  25.   "options": {
  27.   }
  28. }

输出列出了服务的每个方法，每个方法输入参数和返回值对应的类型。

4.8.4 获取类型信息

在获取到方法的参数和返回值类型之后，还可以继续查看类型的信息。下面是用describe命令查看参数HelloService.String类型的信息：

  1. $ grpcurl -plaintext localhost:1234 describe HelloService.String
  2. HelloService.String is a message:
  3. {
  4.   "name": "String",
  5.   "field": [
  6.     {
  7.       "name": "value",
  8.       "number": 1,
  9.       "label": "LABEL_OPTIONAL",
  10.       "type": "TYPE_STRING",
  11.       "options": {
  13.       },
  14.       "jsonName": "value"
  15.     }
  16.   ],
  17.   "options": {
  19.   }
  20. }

json信息对应HelloService.String类型在Protobuf中的定义如下：

  1. message String {
  2.     string value = 1;
  3. }

输出的json数据只不过是Protobuf文件的另一种表示形式。

4.8.5 调用方法

在获取GRPC服务的详细信息之后就可以json调用GRPC方法了。

下面命令通过-d参数传入一个json字符串作为输入参数，调用的是HelloService服务的Hello方法：

  1. $ grpcurl -plaintext -d '{"value": "gopher"}' \
  2.     localhost:1234 HelloService.HelloService/Hello
  3. {
  4.   "value": "hello:gopher"
  5. }

如果-d参数是@则表示从标准输入读取json输入参数，这一般用于比较输入复杂的json数据，也可以用于测试流方法。

下面命令是链接Channel流方法，通过从标准输入读取输入流参数：

  1. $ grpcurl -plaintext -d @ localhost:1234 HelloService.HelloService/Channel
  2. {"value": "gopher"}
  3. {
  4.   "value": "hello:gopher"
  5. }
  7. {"value": "wasm"}
  8. {
  9.   "value": "hello:wasm"
  10. }

通过grpcurl工具，我们可以在没有服务端代码的环境下测试GRPC服务。