Тестирование служб gRPC с помощью gRPCurl и gRPCui в ASP.NET Core

Автор: Джеймс Ньютон-Кинг (James Newton-King)

Для gRPC доступен инструментарий, позволяющий разработчикам тестировать службы без сборки клиентских приложений.

• gRPCurl — это программа командной строки с открытым кодом, которая обеспечивает взаимодействие со службами gRPC.
• gRPCui строится на основе gRPCurl и добавляет интерактивный веб-интерфейс с открытым кодом для gRPC.

В этой статье рассматриваются следующие задачи:

• настройка отражения сервера gRPC с помощью приложения gRPC ASP.NET Core;
• Взаимодействие с gRPC с помощью средств тестирования:
  • обнаружение и тестирование служб gRPC с помощью grpcurl;
  • взаимодействие со службами gRPC в браузере с помощью grpcui.

Примечание.

Дополнительные сведения о модульных тестах gRPC Services см. в статье Тестирование служб gRPC в ASP.NET Core.

Настройка отражения gRPC

Инструментарию должен быть известен контракт Protobuf служб, чтобы их можно было вызывать. Это можно сделать двумя способами.

• Настройка отражения gRPC на сервере. Средства, такие как gRPCurl, используют отражение для автоматического обнаружения контрактов службы.
• Добавьте файлы .proto в средство вручную.

Проще использовать отражение gRPC. Отражение gRPC добавляет в приложение новую службу gRPC, которую клиенты могут вызывать для обнаружения служб.

В gRPC ASP.NET Core есть встроенная поддержка отражения gRPC, обеспечиваемая пакетом Grpc.AspNetCore.Server.Reflection. Чтобы настроить отражение в приложении, выполните указанные ниже действия.

• Добавьте ссылку на пакет 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.

Например, если приложение настроено для авторизации по умолчанию, настройте конечную точку отражения gRPC, AllowAnonymous чтобы пропустить проверку подлинности и авторизацию.

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

gRPCurl

gRPCurl — это программа командной строки, разрабатываемая сообществом gRPC. Она обладает следующими возможностями:

• вызов служб gRPC, включая службы потоковой передачи;
• обнаружение служб с помощью отражения gRPC;
• формирование списка и описание служб gRPC;
• работа с безопасными (TLS) и небезопасными (обычными текстовыми) серверами.

Сведения о скачивании и установке grpcurl см. на домашней странице gRPCurl в GitHub.

Использование grpcurl

Аргумент -help описывает параметры командной строки grpcurl.

$ grpcurl -help

Обнаружение служб

Используйте команду describe для просмотра служб, определенных сервером. Укажите <port> в качестве номера порта localhost сервера gRPC. Номер порта назначается случайным образом, когда проект создается и задается в 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 );
}

Предшествующий пример:

• Выполняет команду describe на сервере localhost:<port>. Где <port> назначается случайным образом, когда проект сервера gRPC создается и задается в Properties/launchSettings.json.
• Выводит службы и методы, возвращаемые отражением 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

Вызовите службу gRPC, указав имена службы и метода вместе с аргументом JSON, который представляет сообщение запроса. Сообщение JSON преобразуется в Protobuf и отправляется службе.

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

В предыдущем примере:

• Аргумент -d задает сообщение запроса с помощью JSON. Этот аргумент должен предшествовать адресу сервера и имени метода.
• Вызывает метод SayHello для службы greeter.Greeter.
• Выводит ответное сообщение в формате JSON.
• Где <port> назначается случайным образом, когда проект сервера gRPC создается и задается в Properties/launchSettings.json.

В предыдущем примере используется \ для экранирования символа ". Экранирование " требуется в консоли PowerShell, но не должно использоваться в некоторых консолях. Например, предыдущая команда для консоли macOS:

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

gRPCui

gRPCui — это интерактивный пользовательский веб-интерфейс для gRPC. gRPCui основывается на gRPCurl. gRPCui предлагает графический интерфейс для обнаружения и тестирования служб gRPC, аналогичных средствам HTTP, таким как пользовательский интерфейс Swagger.

Сведения о скачивании и установке grpcui см. на домашней странице gRPCui в GitHub.

С использованием grpcui

Выполните команду grpcui, указав адрес нужного сервера в качестве аргумента:

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

В предыдущем примере укажите <port> в качестве номера порта localhost сервера gRPC. Номер порта назначается случайным образом, когда проект создается и задается в Properties/launchSettings.json.

Средство откроет окно браузера с интерактивным пользовательским веб-интерфейсом. Службы gRPC обнаруживаются автоматически с помощью отражения gRPC.

Дополнительные ресурсы

• Домашняя страница gRPCurl в GitHub
• Домашняя страница gRPCui в GitHub
• Grpc.AspNetCore.Server.Reflection
• Тестирование служб gRPC в ASP.NET Core
• Макет клиента gRPC в тестах