Go 語言 grpcurl 工具

原文鏈接：https://chai2010.cn/advanced-go-programming-book/ch4-rpc/ch4-08-grpcurl.html

4.8 grpcurl 工具

Protobuf 本身具有反射功能，可以在運(yùn)行時(shí)獲取對(duì)象的 Proto 文件。gRPC 同樣也提供了一個(gè)名為 reflection 的反射包，用于為 gRPC 服務(wù)提供查詢。gRPC 官方提供了一個(gè) C++ 實(shí)現(xiàn)的 grpc_cli 工具，可以用于查詢 gRPC 列表或調(diào)用 gRPC 方法。但是 C++ 版本的 grpc_cli 安裝比較復(fù)雜，我們推薦用純 Go 語言實(shí)現(xiàn)的 grpcurl 工具。本節(jié)將簡(jiǎn)要介紹 grpcurl 工具的用法。

4.8.1 啟動(dòng)反射服務(wù)

reflection 包中只有一個(gè) Register 函數(shù)，用于將 grpc.Server 注冊(cè)到反射服務(wù)中。reflection 包文檔給出了簡(jiǎn)單的使用方法：

import (
    "google.golang.org/grpc/reflection"
)

func main() {
    s := grpc.NewServer()
    pb.RegisterYourOwnServer(s, &server{})

    // Register reflection service on gRPC server.
    reflection.Register(s)

    s.Serve(lis)
}

如果啟動(dòng)了 gprc 反射服務(wù)，那么就可以通過 reflection 包提供的反射服務(wù)查詢 gRPC 服務(wù)或調(diào)用 gRPC 方法。

4.8.2 查看服務(wù)列表

grpcurl 是 Go 語言開源社區(qū)開發(fā)的工具，需要手工安裝：

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

grpcurl 中最常使用的是 list 命令，用于獲取服務(wù)或服務(wù)方法的列表。比如 grpcurl localhost:1234 list 命令將獲取本地 1234 端口上的 grpc 服務(wù)的列表。在使用 grpcurl 時(shí)，需要通過 -cert 和 -key 參數(shù)設(shè)置公鑰和私鑰文件，連接啟用了 tls 協(xié)議的服務(wù)。對(duì)于沒有沒用 tls 協(xié)議的 grpc 服務(wù)，通過 -plaintext 參數(shù)忽略 tls 證書的驗(yàn)證過程。如果是 Unix Socket 協(xié)議，則需要指定 -unix 參數(shù)。

如果沒有配置好公鑰和私鑰文件，也沒有忽略證書的驗(yàn)證過程，那么將會(huì)遇到類似以下的錯(cuò)誤：

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

如果 grpc 服務(wù)正常，但是服務(wù)沒有啟動(dòng) reflection 反射服務(wù)，將會(huì)遇到以下錯(cuò)誤：

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

假設(shè) grpc 服務(wù)已經(jīng)啟動(dòng)了 reflection 反射服務(wù)，服務(wù)的 Protobuf 文件如下：

syntax = "proto3";

package HelloService;

message String {
	string value = 1;
}

service HelloService {
	rpc Hello (String) returns (String);
	rpc Channel (stream String) returns (stream String);
}

grpcurl 用 list 命令查看服務(wù)列表時(shí)將看到以下輸出：

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

其中 HelloService.HelloService 是在 protobuf 文件定義的服務(wù)。而 ServerReflection 服務(wù)則是 reflection 包注冊(cè)的反射服務(wù)。通過 ServerReflection 服務(wù)可以查詢包括本身在內(nèi)的全部 gRPC 服務(wù)信息。

4.8.3 服務(wù)的方法列表

繼續(xù)使用 list 子命令還可以查看 HelloService 服務(wù)的方法列表：

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

從輸出可以看到 HelloService 服務(wù)提供了 Channel 和 Hello 兩個(gè)方法，和 Protobuf 文件的定義是一致的。

如果還想了解方法的細(xì)節(jié)，可以使用 grpcurl 提供的 describe 子命令查看更詳細(xì)的描述信息：

$ grpcurl -plaintext localhost:1234 describe HelloService.HelloService
HelloService.HelloService is a service:
{
  "name": "HelloService",
  "method": [
    {
      "name": "Hello",
      "inputType": ".HelloService.String",
      "outputType": ".HelloService.String",
      "options": {

      }
    },
    {
      "name": "Channel",
      "inputType": ".HelloService.String",
      "outputType": ".HelloService.String",
      "options": {

      },
      "clientStreaming": true,
      "serverStreaming": true
    }
  ],
  "options": {

  }
}

輸出列出了服務(wù)的每個(gè)方法，每個(gè)方法輸入?yún)?shù)和返回值對(duì)應(yīng)的類型。

4.8.4 獲取類型信息

在獲取到方法的參數(shù)和返回值類型之后，還可以繼續(xù)查看類型的信息。下面是用 describe 命令查看參數(shù) HelloService.String 類型的信息：

$ grpcurl -plaintext localhost:1234 describe HelloService.String
HelloService.String is a message:
{
  "name": "String",
  "field": [
    {
      "name": "value",
      "number": 1,
      "label": "LABEL_OPTIONAL",
      "type": "TYPE_STRING",
      "options": {

      },
      "jsonName": "value"
    }
  ],
  "options": {

  }
}

json 信息對(duì)應(yīng) HelloService.String 類型在 Protobuf 中的定義如下：

message String {
	string value = 1;
}

輸出的 json 數(shù)據(jù)只不過是 Protobuf 文件的另一種表示形式。

4.8.5 調(diào)用方法

在獲取 gRPC 服務(wù)的詳細(xì)信息之后就可以 json 調(diào)用 gRPC 方法了。

下面命令通過 ?-d? 參數(shù)傳入一個(gè) json 字符串作為輸入?yún)?shù)，調(diào)用的是 HelloService 服務(wù)的 Hello 方法：

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

如果 -d 參數(shù)是 @ 則表示從標(biāo)準(zhǔn)輸入讀取 json 輸入?yún)?shù)，這一般用于比較輸入復(fù)雜的 json 數(shù)據(jù)，也可以用于測(cè)試流方法。

下面命令是連接 Channel 流方法，通過從標(biāo)準(zhǔn)輸入讀取輸入流參數(shù)：

$ grpcurl -plaintext -d @ localhost:1234 HelloService.HelloService/Channel
{"value": "gopher"}
{
  "value": "hello:gopher"
}

{"value": "wasm"}
{
  "value": "hello:wasm"
}

通過 grpcurl 工具，我們可以在沒有客戶端代碼的環(huán)境下測(cè)試 gRPC 服務(wù)。