在 ASP.NET Core 中使用 Postman 或 gRPCurl 测试 gRPC 服务

作者:James Newton-King

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

  • Postman 是一个 API 平台,具有用于调用 API 的交互式 UI。 Postman 可以在浏览器中运行,也可以下载到本地运行。 Postman 支持调用 gRPC 服务。
  • gRPCurl 是一种开源命令行工具,可提供与 gRPC 服务的交互。
  • gRPCui 基于 gRPCurl,并为 gRPC 添加开源交互式 Web UI。

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

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

注意

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

设置 gRPC 反射

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

  • 在服务器上设置 gRPC 反射。 gRPCurl 和 Postman 等工具使用反射来自动发现服务协定。
  • 手动将 .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 服务。 反射只支持服务发现,不会绕过服务器端安全设置。 受身份验证和授权保护的终结点需要调用方传递凭据才能成功调用终结点。

Postman

Postman 是一个 API 平台。 它支持在其许多功能中使用交互式 UI 调用 gRPC 服务。

若要下载和安装 Postman,请参阅下载 Postman 页面

使用 Postman

Postman 有一个用于调用 gRPC 服务的交互式 UI。 若要使用 Postman 调用 gRPC 服务,请执行以下操作:

  1. 选择“新建”按钮并选择“gRPC 请求”。
  2. 在服务器 URL 中输入 gRPC 服务器的主机名和端口。 例如,localhost:5000。 请勿在 URL 中包含 httphttps 架构。 如果服务器使用传输层安全性 (TLS),请选择服务器 URL 旁的挂锁,在 Postman 中启用 TLS。
  3. 导航到“服务定义”部分,然后选择服务器反射或导入应用的 proto 文件。 完成后,服务器 URL 文本框旁的下拉列表会列出可用的 gRPC 方法。
  4. 若要调用 gRPC 方法,请在下拉列表中选中它,选择“生成示例消息”,然后选择“调用”将 gRPC 调用发送到服务器。

Postman 中的 gRPC

此外,下方短视频介绍如何将 Postman 与 gRPC 结合使用

gRPCurl

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

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

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

gRPCurl 命令行

使用 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 服务,类似于 Postman 或 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 反射自动发现的。

gRPCui Web UI

其他资源

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

  • Postman 是一个 API 平台,具有用于调用 API 的交互式 UI。 Postman 可以在浏览器中运行,也可以下载到本地运行。 Postman 支持调用 gRPC 服务。
  • gRPCurl 是一种开源命令行工具,可提供与 gRPC 服务的交互。
  • gRPCui 基于 gRPCurl,并为 gRPC 添加开源交互式 Web UI。

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

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

注意

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

设置 gRPC 反射

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

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

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

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

  • 添加 Grpc.AspNetCore.Server.Reflection 包引用。
  • Startup.cs 中注册反射:
    • AddGrpcReflection 用于注册启用反射的服务。
    • MapGrpcReflectionService 用于添加反射服务终结点。
public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc();
    services.AddGrpcReflection();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseRouting();
    
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGrpcService<GreeterService>();

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

设置 gRPC 反射后:

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

Postman

Postman 是一个 API 平台。 它支持在其许多功能中使用交互式 UI 调用 gRPC 服务。

若要下载和安装 Postman,请参阅下载 Postman 页面

使用 Postman

Postman 有一个用于调用 gRPC 服务的交互式 UI。 若要使用 Postman 调用 gRPC 服务,请执行以下操作:

  1. 选择“新建”按钮并选择“gRPC 请求”。
  2. 在服务器 URL 中输入 gRPC 服务器的主机名和端口。 例如,localhost:5000。 请勿在 URL 中包含 httphttps 架构。 如果服务器使用传输层安全性 (TLS),请选择服务器 URL 旁的挂锁,在 Postman 中启用 TLS。
  3. 导航到“服务定义”部分,然后选择服务器反射或导入应用的 proto 文件。 完成后,服务器 URL 文本框旁的下拉列表会列出可用的 gRPC 方法。
  4. 若要调用 gRPC 方法,请在下拉列表中选中它,选择“生成示例消息”,然后选择“调用”将 gRPC 调用发送到服务器。

Postman 中的 gRPC

此外,下方短视频介绍如何将 Postman 与 gRPC 结合使用

gRPCurl

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

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

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

gRPCurl 命令行

使用 grpcurl

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

$ grpcurl -help

发现服务

使用 describe 谓词来查看服务器定义的服务:

$ grpcurl localhost:5001 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:5001 上运行 describe 谓词。
  • 打印 gRPC 反射返回的服务和方法。
    • Greeter 是应用实现的服务。
    • ServerReflection 是由Grpc.AspNetCore.Server.Reflection 包添加的服务。

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

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

调用 gRPC 服务

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

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

在上面的示例中:

  • -d 参数使用 JSON 来指定请求消息。 此参数必须位于服务器地址和方法名称之前。
  • 调用 greeter.Greeter 服务上的 SayHello 方法。
  • 以 JSON 的形式打印响应消息。

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

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

gRPCui

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

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

使用 grpcui

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

$ grpcui localhost:5001
gRPC Web UI available at http://127.0.0.1:55038/

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

gRPCui Web UI

其他资源