gRPC Spring Boot Starter

README: English | 中文

文档： English | 中文

特性

• Использование @GrpcService аннотации позволяет реализовать автоматическую конфигурацию и запуск gRPC Server.

• Использование @GrpcClient аннотации позволяет автоматически создавать и управлять вашими gRPC каналами и заглушками.

• Поддержка других вариантов grpc-java (например, Reactive gRPC (RxJava), grpc-kotlin и т. д.).

  • Серверная часть: подходит для всех вариантов grpc-java на основе io.grpc.BindableService.
  • Клиентская часть: требуется пользовательская реализация StubFactory, в настоящее время встроенная поддержка:
    • grpc-java;
    • (пожалуйста, сообщите нам о компонентах, которые не поддерживаются, мы можем добавить поддержку для них).

• Поддержка Spring-Security.

• Поддержка Spring Cloud.

  • Серверный компонент: добавьте информацию о порте gRPC в регистрационные данные службы. В настоящее время поддерживается из коробки:
    • Consul;
    • Eureka;
    • Nacos;
    • (просьба сообщить нам о неподдерживаемых компонентах, мы можем добавить их поддержку).
  • Клиентский компонент: считывает целевой адрес службы из Spring DiscoveryClient (все варианты).

• Поддержка Spring Sleuth в качестве решения для распределённой трассировки (если brave-instrument-grpc существует).

• Поддержка глобальных и настраиваемых перехватчиков gRPC для серверной и клиентской сторон.

• Поддержка метрик на основе micrometer / actuator.

• Также подходит для (non-shaded) grpc-netty.

Версия

Последняя версия — 2.15.0.RELEASE, совместима с Spring-Boot 2.7.16 и Spring-Cloud 2021.0.8. Однако она также совместима с различными другими версиями. Наш документ содержит обзор всех версий и соответствующих версий библиотек.

Примечание: этот проект также можно использовать без Spring-Boot, но вам необходимо вручную настроить некоторые компоненты.

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

gRPC сервер + клиент

Добавьте зависимость Maven с помощью следующей команды:

<dependency>
  <groupId>net.devh</groupId>
  <artifactId>grpc-spring-boot-starter</artifactId>
  <version>2.15.0.RELEASE</version>
</dependency>

Или добавьте зависимость Gradle:

dependencies {
  implementation 'net.devh:grpc-spring-boot-starter:2.15.0.RELEASE'
}

gRPC сервер

Добавьте зависимость Maven с помощью следующей команды:

<dependency>
  <groupId>net.devh</groupId>
  <artifactId>grpc-server-spring-boot-starter</artifactId>
  <version>2.15.0.RELEASE</version>
</dependency>

Или добавьте зависимость Gradle:

dependencies {
  implementation 'net.devh:grpc-server-spring-boot-starter:2.15.0.RELEASE'
}

На интерфейсе серверного сервиса добавьте аннотацию @GrpcService.

@GrpcService
public class GrpcServerService extends GreeterGrpc.GreeterImplBase {

    @Override
    public void sayHello(HelloRequest req, StreamObserver<HelloReply> responseObserver) {
        HelloReply reply = HelloReply.newBuilder().setMessage("Hello ==> " + req.getName()).build();
        responseObserver.onNext(reply);
        responseObserver.onCompleted();
    }

}

По умолчанию gRPC-сервер будет прослушивать порт 9090. Конфигурация портов и другие настройки могут быть изменены с помощью механизма свойств Spring.

Для сервера используется префикс grpc.server.

gRPC клиент

Чтобы добавить зависимость Maven, используйте следующую команду:

<dependency>
  <groupId>net.devh</groupId>
  <artifactId>grpc-client-spring-boot-starter</artifactId>
  <version>2.15.0.RELEASE</version>
</dependency>

Чтобы добавить зависимость Gradle, используйте следующий код:

dependencies {
  compile 'net.devh:grpc-client-spring-boot-starter:2.15.0.RELEASE'
}

Добавьте аннотацию @GrpcClient(serverName) к полю stub клиента gRPC.

• Не используйте @GrpcClient вместе с @Autowireed или @Inject.

@GrpcClient("gRPC server name")
private GreeterGrpc.GreeterBlockingStub greeterStub;

Примечание: можно использовать одно и то же имя сервера gRPC для нескольких каналов или разные заглушки (даже разные заглушки-перехватчики).

Затем вы можете отправлять запросы на сервер следующим образом:

HelloReply response = stub.sayHello(HelloRequest.newBuilder().setName(name).build());

Можно настроить целевой адрес каждого клиента отдельно. В некоторых случаях можно полагаться только на конфигурацию по умолчанию. Можно настроить URL-адрес по умолчанию с помощью класса Bean NameResolver.Factory. Если этот класс не настроен, будет использоваться схема по умолчанию и имя (например, dns:<name>):

Эти настройки и другие параметры можно изменить с помощью механизма свойств Spring. Для клиента используется префикс grpc.client.(serverName).

Использование (non-shaded) grpc-netty

Эта библиотека поддерживает grpc-netty и grpc-nety-shaded. Последний может предотвратить конфликты с несовместимыми версиями gRPC или разными версиями netty.

Примечание: если в classpath есть затенённый netty, он будет использовать wireline с незатенённым grpc-netty.

В Maven это можно сделать следующим образом:

<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-netty</artifactId>
    <version>${grpcVersion}</version>
</dependency>

<!-- For both -->
<dependency>
    <groupId>net.devh</groupId>
    <artifactId>grpc-spring-boot-starter</artifactId>
    <version>...</version>
    <exclusions>
        <exclusion>
            <groupId>io.grpc</groupId>
            <artifactId>grpc-netty-shaded</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<!-- For the server (only) -->
<dependency>
    <groupId>net.devh</groupId>
    <artifactId>grpc-server-spring-boot-starter</artifactId>
    <version>...</version>
    <exclusions>
        <exclusion>
            <groupId>io.grpc</groupId>
            <artifactId>grpc-netty-shaded</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<!-- For the client (only) -->
<dependency>
    <groupId>net.devh</groupId>
    <artifactId>grpc-client-spring-boot-starter</artifactId>
    <version>...</version>
    <exclusions>
        <exclusion>
            <groupId>io.grpc</groupId>
            <artifactId>grpc-netty-shaded</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Аналогично, в Gradle это делается следующим образом:

implementation "io.grpc:grpc-netty:${grpcVersion}"

implementation 'net.devh:grpc-spring-boot-starter:...' exclude group: 'io.grpc', module: 'grpc-netty-shaded' // For both
implementation 'net.devh:grpc-client-spring-boot-starter:...' exclude group: 'io.grpc', module: 'grpc-netty-shaded' // For the client (only)
implementation 'net.devh:grpc-server-spring-boot-starter:...' exclude group: 'io.grpc', module: 'grpc-netty-shaded' // For the server (only)

Примеры проектов

Дополнительные примеры можно найти здесь.

Устранение неполадок

За помощью обращайтесь к нашей документации.

Участие в проекте

Мы приветствуем ваш вклад в проект. Подробности см. в CONTRIBUTING.md.