Привет, Хабр! Сегодня я поделюсь опытом работы с gRPC и расскажу как создать и протестировать gRPC-сервис в приложении на Spring Boot. Основная проблема — это отсутствие структурированной информации по корректному тестированию gRPC сервиса. Эта статья будет полезна для тех, кто только начинает знакомиться с gRPC и ищет руководство по написанию и тестированию сервисов.
Настройка проекта
Для начала настроим проект. Создадим отдельный модуль для proto-моделей и назовем его interface-grpc. Добавим необходимые зависимости в pom.xml для работы с gRPC:
<dependencies>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-stub</artifactId>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-protobuf</artifactId>
</dependency>
<dependency>
<groupId>jakarta.annotation</groupId>
<artifactId>jakarta.annotation-api</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<scope>compile</scope>
</dependency>
</dependencies>
В блоке build добавим плагин для генерации классов из proto-файла:
<build>
<extensions>
<extension>
<groupId>kr.motd.maven</groupId>
<artifactId>os-maven-plugin</artifactId>
</extension>
</extensions>
<plugins>
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<configuration>
<protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}</protocArtifact>
<pluginId>grpc-java</pluginId>
<pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
</configuration>
<executions>
<execution>
<goals>
<goal>compile</goal>
<goal>compile-custom</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
Написание gRPC Сервиса
Рассмотрим пример простого микросервиса для ветеринарной клиники. Создадим proto-файл для сущности "питомец":
syntax = "proto3";
package grpc.server.grpc_server.pet;
message CreatePetRequest {
Pet pet = 1;
message Pet {
string pet_name = 2;
string pet_type = 3;
string pet_birth_date = 4;
}
}
message CreatePetResponse{
int32 pet_id = 1;
}
message FindByIdPetRequest {
int32 pet_id = 1;
}
message FindByIdPetResponse {
Pet pet = 1;
message Pet {
string pet_name = 2;
string pet_type = 3;
}
}
message ErrorResponse {
string error_name = 1;
}
service PetService {
rpc CreatePet (CreatePetRequest) returns (CreatePetResponse);
rpc FindByIDPet (FindByIdPetRequest) returns (FindByIdPetResponse);
}
После создания proto-файла запустим сборку проекта, чтобы сгенерировать необходимые классы.
Реализация gRPC Сервиса в Spring Boot
Создадим ещё один модуль в нашем проекте – clinic-grpc-service. Pom-файл у меня выглядит следующим образом:
<dependencies>
<dependency>
<groupId>net.devh</groupId>
<artifactId>grpc-server-spring-boot-autoconfigure</artifactId>
</dependency>
<!--test -->
<dependency>
<groupId>net.devh</groupId>
<artifactId>grpc-client-spring-boot-autoconfigure</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>junit-jupiter</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-engine</artifactId>
<scope>test</scope>
</dependency>
Опишем сущности Pet и PetType, а также DTO классы. Затем реализуем интерфейс PetService с методами для сохранения и получения питомца.
Пример реализации PetRequestDTO и PetResponseDTO.
@Builder
public record PetRequestDTO(
@JsonProperty("pet_name") String petName,
@JsonProperty("pet_type") String petType,
@JsonProperty("pet_birth_date") String petBirthDate
){}
@Builder
public record PetResponseDTO(
@JsonProperty("pet_name") String petName,
@JsonProperty("pet_type") String petType
){}
Теперь создадим интерфейс PetService c двумя методами: на сохранение и получение сущности:
public interface PetService {
int createPet(PetRequestDTO pet);
PetResponseDTO findByIDPet(int id);
}
Наконец, мы подошли к самому интересному – давайте реализуем gRPC service GrpcPetServiceImpl, который будет наследовать автоматически созданный класс PetServiceGrpc.PetServiceImplBase. Реализуем методы createPet и findByIDPet.
На первый взгляд выглядит странно, что метод не возвращает ответ явно. Вместо этого, результат выполнения сохраняется во втором аргументе метода. Основная особенность gRPC в том, что методы могут возвращать не только один объект, а стримить поток данных. Поэтому результат выполнения методов (response) упаковывается в StreamObserver. После того как мы соберем response с помощью newBuilder(), мы можем отсылать наш ответ клиенту с помощью команды onNext(). Завершая отправку данных, мы должны закрыть поток посредством вызова метода onCompleted().
@GrpcService
@RequiredArgsConstructor
public class GrpcPetServiceImpl extends PetServiceGrpc.PetServiceImplBase {
private final PetService petService;
@Override
public void createPet(PetOuterClass.CreatePetRequest request,
StreamObserver<PetOuterClass.CreatePetResponse> responseObserver) {
PetRequestDTO petRequestDTO = PetRequestDTO.builder()
.petName(request.getPet().getPetName())
.petType(request.getPet().getPetType())
.petBirthDate(request.getPet().getPetBirthDate())
.build();
PetOuterClass.CreatePetResponse response = PetOuterClass.CreatePetResponse
.newBuilder()
.setPetId(petService.createPet(petRequestDTO))
.build();
responseObserver.onNext(response);
responseObserver.onCompleted();
}
@Override
public void findByIDPet(PetOuterClass.FindByIdPetRequest request,
StreamObserver<PetOuterClass.FindByIdPetResponse> responseObserver) {
PetResponseDTO pet = petService.findByIDPet(request.getPetId());
if (pet == null) {
Metadata.Key<PetOuterClass.ErrorResponse> errorResponseKey =
ProtoUtils.keyForProto(PetOuterClass.ErrorResponse.getDefaultInstance());
PetOuterClass.ErrorResponse errorResponse = PetOuterClass.ErrorResponse.newBuilder()
.setErrorName("This pet with id = " + request.getPetId() + " is not in the database")
.build();
Metadata metadata = new Metadata();
metadata.put(errorResponseKey, errorResponse);
responseObserver.onError(
NOT_FOUND.withDescription("This pet with id = " + request.getPetId() + " is not found")
.asRuntimeException(metadata)
);
return;
}
PetOuterClass.FindByIdPetResponse response = PetOuterClass.FindByIdPetResponse
.newBuilder()
.setPet(PetOuterClass.FindByIdPetResponse.Pet
.newBuilder()
.setPetName(pet.petName())
.setPetType(pet.petType())
.build())
.build();
responseObserver.onNext(response);
responseObserver.onCompleted();
}
}
Запустим наш сервис и протестируем его через консоль. Сохраним нашего питомца и потом получим его.
VetClinicApp % grpcurl -plaintext -d '{"pet":{"pet_name":"Joo","pet_type":"dog","pet_birth_date":"2023-09-01"}}' localhost:9090 ru.vyrostkov.grpc.server.grpc_server.pet.PetService/CreatePet
{
"pet_id": 1
}
VetClinicApp % grpcurl -plaintext -d '{"pet_id":1}' localhost:9090 ru.vyrostkov.grpc.server.grpc_server.pet.PetService/FindByIDPet
{
"pet": {
"pet_name": "Joo",
"pet_type": "dog"
}
}
Обработка ошибок в gRPC
Всё отлично, сервис работает. Что произойдёт, если мы запросим у сервиса объект, которого нет в базе? Сервис упадёт с ошибкой java.lang.NullPointerException: Cannot invoke "ru.vyrostkov.grpc.dto.PetResponseDTO.getPetName()" because "pet" is null.
Что бы такого не произошло, я добавил обработку ошибок. В proto-файле описал дополнительный message ErrorResponse. Это пример сообщения об ошибке, которое мы отправим клиенту в виде метаданных.
message ErrorResponse {
string error_name = 1;
}
Метаданные – это побочный канал, который позволяет клиентам и серверам предоставлять друг другу информацию, связанную с RPC.
Метаданные gRPC – это пара ключ-значение, которая отправляется с начальными или конечными запросами или ответами gRPC.
Для каждой пары ключ-значение метаданных ошибки создаём ключ Metadata.Key<PetOuterClass.ErrorResponse>, а значением будет являться ErrorResponse. После чего сохраняем пары ключ-значение в метаданных, вызывая metadata.put(Key,Value). И в конце вызываем responseObserver, чтобы установить условие ошибки, передавая в него StatusRuntimeException, в который мы прокинем метаданные в Status.
Metadata.Key<PetOuterClass.ErrorResponse> errorResponseKey =
ProtoUtils.keyForProto(PetOuterClass.ErrorResponse.getDefaultInstance());
PetOuterClass.ErrorResponse errorResponse = PetOuterClass.ErrorResponse.newBuilder()
.setErrorName("Информация, которую мы вернем клиенту в виде метаданных")
.build();
Metadata metadata = new Metadata();
metadata.put(errorResponseKey, errorResponse);
responseObserver.onError(
NOT_FOUND.withDescription("Описание ошибки")
.asRuntimeException(metadata)
);
Мы используем io.grpc.Status для указания статуса ошибки. Функция responseObserver::onError принимает Throwable-параметр, поэтому мы используем исключение asRuntimeException (метаданные) для преобразования Status в Throwable.
Если клиент отправляет неверный запрос – сервис вернёт исключение, а не упадёт с ошибкой.
m.vyrostkov@macbook-KL920DXTK4 VetClinicApp % grpcurl -plaintext -d '{"pet_id":2}' localhost:9090 ru.vyrostkov.grpc.server.grpc_server.pet.PetService/FindByIDPet
ERROR:
Code: NotFound
Message: This pet with id = 2 is not found
Тестирование
Теперь давайте покроем наш сервис тестами. Воспользуемся библиотеками mockito и spring-boot-test. Мы создали клиент с помощью аннотации @GrpcClient, через который будет осуществляться вызов непосредственно нашего gRPC сервиса. Также необходимо создать заглушку для petService.
Пример возможной реализации тестов может выглядеть следующим образом:
@SpringBootTest(properties = {
"grpc.server.inProcessName=test",
"grpc.server.port=9091",
"grpc.client.petService.address=in-process:test"
})
@SpringJUnitConfig(classes = {GrpcApplication.class})
@Log4j2
public class GrpcPetServiceImplTest {
@MockBean
PetService petService;
@GrpcClient("petService")
private PetServiceGrpc.PetServiceBlockingStub petServiceBlockingStub;
final int petId = 1;
Pet pet;
PetRequestDTO petRequestDTO;
PetResponseDTO petResponseDTO;
@BeforeEach
void setUp() {
pet = Pet
.builder()
.name("Bob")
.petType(PetType.builder().name("dog").build())
.birthDate(LocalDate.parse("2020-12-11"))
.build();
petRequestDTO = PetRequestDTO
.builder()
.petName("Bob")
.petType("dog")
.petBirthDate("2020-12-11")
.build();
petResponseDTO = PetResponseDTO
.builder()
.petName("Bob")
.petType("dog")
.build();
}
@Test
@DisplayName("JUnit grpc test for find pet by id")
public void findByIDPetTest() {
doReturn(petResponseDTO)
.when(petService)
.findByIDPet(anyInt());
PetOuterClass.FindByIdPetRequest request =
PetOuterClass.FindByIdPetRequest
.newBuilder()
.setPetId(petId)
.build();
PetOuterClass.FindByIdPetResponse response =
petServiceBlockingStub.findByIDPet(request);
assertThat(response).isNotNull();
assertThat(response.getPet().getPetName()).isEqualTo(pet.getName());
verify(petService).findByIDPet(petId);
}
@Test
@DisplayName("JUnit grpc test for find pet by id when pet not found")
public void PetNotFoundWhenFindByIDTest() throws Exception {
doReturn(null)
.when(petService)
.findByIDPet(anyInt());
PetOuterClass.FindByIdPetRequest request =
PetOuterClass.FindByIdPetRequest
.newBuilder()
.setPetId(petId)
.build();
StatusRuntimeException thrown =
Assertions.assertThrows(StatusRuntimeException.class, () ->
petServiceBlockingStub.findByIDPet(request));
assertThat(thrown.getStatus().getCode().toString())
.isEqualTo("NOT_FOUND");
assertThat(thrown.getMessage())
.isEqualTo("NOT_FOUND: This pet with id = 1 is not found");
Metadata metadata = Status.trailersFromThrowable(thrown);
PetOuterClass.ErrorResponse errorResponse =
metadata.get(ProtoUtils.keyForProto(
PetOuterClass.ErrorResponse.getDefaultInstance()
)
);
assertThat(errorResponse.getErrorName())
.isEqualTo("This pet with id = 1 is not in the database");
verify(petService).findByIDPet(petId);
}
}
Заключение
Мы покрыли наш gRPC сервис тестами, включая позитивные и негативные сценарии. Использование gRPC в Spring Boot позволяет создавать эффективные и масштабируемые микросервисы, а тестирование помогает обеспечить их надежную работу. В результате, разработчики получают инструмент для построения высокопроизводительных и надежных распределенных систем.
Надеюсь, эта статья поможет вам в изучении gRPC и улучшит ваши навыки разработки в Spring Boot.
GitHub проекта : https://github.com/mikhail-vyrostkov/VetClinicApp