在 ASP.NET Core 中使用 gRPCurl 和 gRPCui 测试 gRPC 服务

作者：James Newton-King

此工具适用于 gRPC，让开发人员可以在不生成客户端应用的情况下测试服务：

• gRPCurl 是一种开源命令行工具，可提供与 gRPC 服务的交互。
• gRPCui 基于 gRPCurl，并为 gRPC 添加开源交互式 Web UI。

本文介绍如何提供这种交互：

• 使用 gRPC ASP.NET Core 应用设置 gRPC 服务器反射。
• 使用测试工具与 gRPC 交互：
  • 使用 grpcurl 发现和测试 gRPC 服务。
  • 使用 grpcui 通过浏览器与 gRPC 服务交互。

注意

若要了解如何对 gRPC 服务进行单元测试，请参阅在 ASP.NET Core 测试 gRPC 服务。

设置 gRPC 反射

工具必须了解服务的 Protobuf 协定，然后才能调用它们。 有两种方法可以实现此目的：

• 在服务器上设置 gRPC 反射。 gRPCurl 等工具使用反射来自动发现服务协定。
• 手动将 .proto 文件添加到工具中。

使用 gRPC 反射会更加轻松。 gRPC 反射向应用添加了新的 gRPC 服务，客户端可以调用该服务来发现服务。

gRPC ASP.NET Core 包含 Grpc.AspNetCore.Server.Reflection 包，因此具有对 gRPC 反射的内置支持。 在应用中配置反射：

• 添加 Grpc.AspNetCore.Server.Reflection 包引用。
• 在 Program.cs 中注册反射：
  • AddGrpcReflection 用于注册启用反射的服务。
  • MapGrpcReflectionService 用于添加反射服务终结点。

builder.Services.AddGrpc();
builder.Services.AddGrpcReflection();

var app = builder.Build();

app.MapGrpcService<GreeterService>();

IWebHostEnvironment env = app.Environment;

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService();
}

设置 gRPC 反射后：

• gRPC 反射服务将添加到服务器应用。
• 支持 gRPC 反射的客户端应用可以调用反射服务来发现服务器托管的服务。
• 仍从客户端调用 gRPC 服务。 反射只支持服务发现，不会绕过服务器端安全设置。 受身份验证和授权保护的终结点需要调用方传递凭据才能成功调用终结点。

gRPCurl

gRPCurl 是由 gRPC 社区创建的命令行工具。 其功能包括：

• 调用 gRPC 服务，包括流式服务。
• 使用 gRPC 反射进行服务发现。
• 列出并描述 gRPC 服务。
• 适用于安全 (TLS) 和不安全（纯文本）服务器。

有关下载和安装 grpcurl 的信息，请参阅 gRPCurl GitHub 主页。

使用 grpcurl

-help 参数说明 grpcurl 命令行选项：

$ grpcurl -help

发现服务

使用 describe 谓词来查看服务器定义的服务。 将 <port> 指定为 gRPC 服务器的 localhost 端口号。 端口号是在 Properties/launchSettings.json 中创建和设置项目时随机分配的：

$ grpcurl localhost:<port> describe
greet.Greeter is a service:
service Greeter {
  rpc SayHello ( .greet.HelloRequest ) returns ( .greet.HelloReply );
  rpc SayHellos ( .greet.HelloRequest ) returns ( stream .greet.HelloReply );
}
grpc.reflection.v1alpha.ServerReflection is a service:
service ServerReflection {
  rpc ServerReflectionInfo ( stream .grpc.reflection.v1alpha.ServerReflectionRequest ) returns ( stream .grpc.reflection.v1alpha.ServerReflectionResponse );
}

上面的示例：

• 在服务器 localhost:<port> 上运行 describe 谓词。 其中 <port> 是在 Properties/launchSettings.json 中创建和设置 gRPC 服务器项目时随机分配的
• 打印 gRPC 反射返回的服务和方法。
  • Greeter 是应用实现的服务。
  • ServerReflection 是由Grpc.AspNetCore.Server.Reflection 包添加的服务。

结合 describe 与服务、方法或消息名称，以查看其详细信息：

$ grpcurl localhost:<port> describe greet.HelloRequest
greet.HelloRequest is a message:
message HelloRequest {
  string name = 1;
}

调用 gRPC 服务

指定服务和方法名称以及表示请求消息的 JSON 参数，以调用 gRPC 服务。 将 JSON 转换为 Protobuf 并发送到服务。

$ grpcurl -d '{ \"name\": \"World\" }' localhost:<port> greet.Greeter/SayHello
{
  "message": "Hello World"
}

在上面的示例中：

• -d 参数使用 JSON 来指定请求消息。 此参数必须位于服务器地址和方法名称之前。
• 调用 greeter.Greeter 服务上的 SayHello 方法。
• 以 JSON 的形式打印响应消息。
• 其中 <port> 是在 Properties/launchSettings.json 中创建和设置 gRPC 服务器项目时随机分配的

前面的示例使用 \ 对 " 字符进行转义。 转义 " 在 PowerShell 控制台中是必需的，但在某些控制台中不得使用。 例如，macOS 控制台的上一个命令：

$ grpcurl -d '{ "name": "World" }' localhost:<port> greet.Greeter/SayHello
{
  "message": "Hello World"
}

gRPCui

gRPCui 是 gRPC 的交互式 Web UI。 gRPCui 是基于 gRPCurl 构建的。 gRPCui 提供了一个 GUI 来发现和测试 gRPC 服务，类似于 Swagger UI 等 HTTP 工具。

有关下载和安装 grpcui 的信息，请参阅 gRPCui GitHub 主页。

使用 grpcui

使用要与之交互的服务器地址作为参数来运行 grpcui：

$ grpcui localhost:<port>
gRPC Web UI available at http://127.0.0.1:55038/

在前面的示例中，将 <port> 指定为 gRPC 服务器的 localhost 端口号。 端口号是在 Properties/launchSettings.json 中创建和设置项目时随机分配的

该工具使用交互式 Web UI 启动浏览器窗口。gRPC 服务是使用 gRPC 反射自动发现的。

其他资源

• gRPCurl GitHub 主页
• gRPCui GitHub 主页
• Grpc.AspNetCore.Server.Reflection
• 在 ASP.NET Core 中测试 gRPC 服务
• 在测试中模拟 gRPC 客户端