在 ASP.NET Core 中使用 gRPCurl 和 gRPCui 测试 gRPC 服务
此工具适用于 gRPC,让开发人员可以在不生成客户端应用的情况下测试服务:
本文介绍如何提供这种交互:
- 使用 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 服务。 反射只支持服务发现,不会绕过服务器端安全设置。 受身份验证和授权保护的终结点需要调用方传递凭据才能成功调用终结点。
反射服务安全性
gRPC 反射会返回一个可用 API 列表,其中可能包含敏感信息。 应注意限制对 gRPC 反射服务的访问。
通常只有在本地开发环境中才需要 gRPC 反射。 对于本地开发,仅当 IsDevelopment 返回 true 时,才应映射反射服务:
if (env.IsDevelopment())
{
app.MapGrpcReflectionService();
}
可以通过标准 ASP.NET Core 授权扩展方法(例如 AllowAnonymous
和 RequireAuthorization
)来控制对服务的访问。
例如,如果应用已配置为默认需要授权,则可使用 AllowAnonymous
配置 gRPC 反射终结点,以跳过身份验证和授权。
if (env.IsDevelopment())
{
app.MapGrpcReflectionService().AllowAnonymous();
}
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 反射自动发现的。
其他资源
此工具适用于 gRPC,让开发人员可以在不生成客户端应用的情况下测试服务:
本文介绍如何提供这种交互:
- 使用 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
包引用。 - 在
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 服务。 反射只支持服务发现,不会绕过服务器端安全设置。 受身份验证和授权保护的终结点需要调用方传递凭据才能成功调用终结点。
gRPCurl
gRPCurl 是由 gRPC 社区创建的命令行工具。 其功能包括:
- 调用 gRPC 服务,包括流式服务。
- 使用 gRPC 反射进行服务发现。
- 列出并描述 gRPC 服务。
- 适用于安全 (TLS) 和不安全(纯文本)服务器。
有关下载和安装 grpcurl
的信息,请参阅 gRPCurl GitHub 主页。
使用 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 服务,类似于 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 反射自动发现的。
其他资源
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈