gRPC

Google リモートプロシージャコール (gRPC) は、バイナリメッセージを使用してクライアントとサーバー間の通信を可能にする高性能な RPC フレームワークです。Spring Boot は、クライアントおよびサーバー両方の gRPC アプリケーションの開発とテストをサポートしています。

gRPC で使用される基盤となるメッセージ形式はプロトコルバッファであり、これにより様々なプログラミング言語でメッセージを作成および消費することが可能になります。

サービス定義

gRPC アプリケーションを開発するには、まず Protocol Buffers サービス定義ファイルが必要です。.proto ファイルは、アプリケーションが利用または提供できるサービスとメッセージを定義します。

Here’s an example of a typical .proto file that uses the proto3 revision (英語) of the protocol buffers language:

syntax = "proto3";

option java_package = "com.example.grpc.proto";
option java_multiple_files = true;

service HelloWorld {
    rpc SayHello (HelloRequest) returns (HelloReply) {}
}

message HelloRequest {
    string name = 1;
}

message HelloReply {
    string message = 1;
}

このファイルは、HelloReqest メッセージを受け取り、HelloReply メッセージを返す単一のメソッドを持つ HelloWorld サービスを定義します。HelloReqest メッセージには name 文字列フィールドが含まれます。HelloReply メッセージには message 文字列フィールドが含まれます。

java_package と java_multiple_files のオプションを除いて、.proto ファイルには Java プログラミング言語に特有のものは何も含まれていません。

Java コードの生成

.proto ファイルは言語に依存しないため、使用可能な Java コードに変換するプロセスが必要です。生成されたコードを使用して、実行中のサービスに対してリモートプロシージャ呼び出しを行うか、サービスを独自に実装して他のユーザーが呼び出せるようにすることができます。

コード生成に使用する具体的な手順は、使用するビルドシステムによって異なります。Spring Boot は Maven と Gradle の両方の protobuf プラグインをサポートしていますが、ご自身にとって最適なソリューションを自由に選択してください。

Maven プラグインの使用

Spring Boot には、io.github.ascopes:protobuf-maven-plugin および Maven プラグインの依存関係管理機能が含まれています。spring-boot-starter-parent POM を使用している場合は、すぐに使える適切な設定も提供されます。

以下は、プラグインを使用する典型的な Maven POM ファイルの例です。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
    <parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>4.1.0</version>
	</parent>
	<groupId>com.example</groupId>
	<artifactId>myproject</artifactId>
	<version>0.0.1-SNAPSHOT</version>

	<build>
		<plugins>
			<plugin>
				<groupId>io.github.ascopes</groupId>
				<artifactId>protobuf-maven-plugin</artifactId>
			</plugin>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

上記の POM は spring-boot-starter-parent を継承しているため、以下のようになります。

  • protoc バージョンの設定。

  • binary-maven プラグインの設定。

  • generate ゴールの実行構成。

.proto のファイルを src/main/proto に追加する必要があります。

If you don’t use spring-boot-starter-parent, or you want to configure the plugin directly, refer to the protobuf-maven-plugin documentation (英語) . If you use Spring Boot’s dependency management the ${protobuf-java.version} and ${grpc-java.version} properties will be useful.

Gradle プラグインの使用

Spring Boot には、com.google.protobuf:protobuf-gradle-plugin および Gradle プラグインの依存関係管理機能が含まれています。さらに、spring-boot-gradle-plugin は protobuf プラグインの存在を検知し、適切に設定を行います。

以下に、プラグインを使用した典型的な Gradle ファイルを示します。

plugins {
	id 'java'
	id 'org.springframework.boot' version '4.1.0'
	id 'io.spring.dependency-management' version '1.1.7'
	id 'com.google.protobuf' version '0.9.6'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
	toolchain {
		languageVersion = JavaLanguageVersion.of(17)
	}
}

repositories {
	mavenCentral()
}

この gradle ファイルは org.springframework.boot と com.google.protobuf の両方のプラグインを使用しているため、以下のようになります。

  • protoc バージョンの設定。

  • protoc-gen-grpc-java バージョンの設定。

.proto のファイルを src/main/proto に追加する必要があります。

If you don’t use org.springframework.boot plugin, or you want to configure the plugin directly, refer to the protobuf-gradle-plugin documentation [GitHub] (英語) .

gRPC サーバーアプリケーションの作成

Spring Boot は、サーバーアプリケーションで使用できる spring-boot-grpc-server モジュールと spring-boot-starter-grpc-server スターター POM を提供します。

実際のサーバーコードを記述するには、.proto ファイルから生成された基本クラスを 1 つ以上拡張し、Spring Bean として公開する必要があります。Spring gRPC は、BindableService (英語) を実装する Bean を自動的に gRPC サーバーとして公開します。.proto で生成されたクラスはすべて BindableService (英語) を実装しているため、Bean として追加するだけで、gRPC 経由で公開できます。

For more details see the Spring gRPC documentation.

次の例は、上記の .proto ファイルに含まれる HelloWorld サービスをどのように実装できるかを示しています。この例では、@GrpcService (Javadoc) アノテーションを使用し、コードがコンポーネントスキャンによって検出されるパッケージ内にあることを前提としています。

  • Java

  • Kotlin

import io.grpc.stub.StreamObserver;

import org.springframework.grpc.server.service.GrpcService;

@GrpcService
public class MyHelloWorldService extends HelloWorldGrpc.HelloWorldImplBase {

	@Override
	public void sayHello(HelloRequest request, StreamObserver<HelloReply> responseObserver) {
		String message = "Hello '%s'".formatted(request.getName());
		HelloReply reply = HelloReply.newBuilder().setMessage(message).build();
		responseObserver.onNext(reply);
		responseObserver.onCompleted();
	}

}
import io.grpc.stub.StreamObserver
import org.springframework.grpc.server.service.GrpcService

@GrpcService
class MyHelloWorldService : HelloWorldGrpc.HelloWorldImplBase() {

	override fun sayHello(request: HelloRequest,  responseObserver: StreamObserver<HelloReply>) {
		val message = "Hello '${request.getName()}'"
		val reply = HelloReply.newBuilder().setMessage(message).build()
		responseObserver.onNext(reply)
		responseObserver.onCompleted()
	}

}

アプリケーションが spring-boot-starter-grpc-server を使用する場合、Netty がポート 9090 でリッスンするサーバー実装として使用されます。

You can test your application using grpcurl [GitHub] (英語) :

$ grpcurl -d '{"name":"Spring"}' -plaintext localhost:9090 HelloWorld.SayHello
{
  "message": "Hello 'Spring'"
}

Netty シェードサーバーへの切り替え

spring-boot-starter-grpc-server スターター POM に含まれる Netty のバージョンが、使用している他のライブラリと互換性がないことが判明した場合は、「シェーディング」バージョンに切り替えることができます。

切り替えるには、io.grpc:grpc-netty を除外して io.grpc:grpc-netty-shaded を含めることができます。例:

  • Maven

  • Gradle

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-grpc-server</artifactId>
	<exclusions>
		<!-- Exclude the gRPC Netty dependency -->
		<exclusion>
			<groupId>io.grpc</groupId>
			<artifactId>grpc-netty</artifactId>
		</exclusion>
	</exclusions>
</dependency>
<!-- Use gRPC Netty Shaded instead -->
<dependency>
	<groupId>io.grpc</groupId>
	<artifactId>grpc-netty-shaded</artifactId>
</dependency>
dependencies {
	implementation('org.springframework.boot:spring-boot-starter-grpc-server') {
		// Exclude the gRPC Netty dependency
		exclude group: 'io.grpc', module: 'grpc-netty'
	}
	// Use gRPC Netty Shaded instead
	implementation "io.grpc:grpc-netty-shaded"
}

サーブレットコンテナーへの切り替え

Netty ではなく、Tomcat などの通常のサーブレットコンテナーを使用して gRPC サービスを公開することも可能です。そのためには、サーブレットコンテナーが HTTP/2 をサポートするように設定する必要があります。

サーブレット gRPC 実装に切り替えるには、io.grpc:grpc-netty を除外し、io.grpc:grpc-servlet-jakarta を含めることができます。例:

  • Maven

  • Gradle

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-grpc-server</artifactId>
	<exclusions>
		<!-- Exclude the gRPC Netty dependency -->
		<exclusion>
			<groupId>io.grpc</groupId>
			<artifactId>grpc-netty</artifactId>
		</exclusion>
	</exclusions>
</dependency>
<!-- Use gRPC Servlet Jakarta instead -->
<dependency>
	<groupId>io.grpc</groupId>
	<artifactId>grpc-servlet-jakarta</artifactId>
</dependency>
dependencies {
	implementation('org.springframework.boot:spring-boot-starter-webmvc') {
	implementation('org.springframework.boot:spring-boot-starter-grpc-server') {
		// Exclude the gRPC Netty dependency
		exclude group: 'io.grpc', module: 'grpc-netty'
	}
	// Use gRPC Servlet Jakarta instead
	implementation "io.grpc:grpc-servlet-jakarta"
}
サーブレットコンテナーの依存関係を含めることを忘れないでください。たとえば、spring-boot-starter-tomcat を使用して、server.http2.enabled を true に設定します。
サーブレットコンテナーを使用する場合、特定の gRPC サーバー構成プロパティは関係なく無視されます。例: server.port が Web サーバーポートを設定するために使用されたため、spring.grpc.server.port は無視されます。

SSL サポート

SSL は、SSL バンドルを使用して grpc-netty サーバーと grpc-netty-shaded サーバーの両方で設定できます。SSL バンドルの宣言方法の詳細については、SSL core documentation を参照してください。

バンドルが定義されたら、gRPC サーバーアプリケーションで以下のプロパティを使用してバンドルを使用できます。

  • プロパティ

  • YAML

spring.grpc.server.ssl.bundle=mysslbundle
spring:
  grpc:
    server:
      ssl:
        bundle: mysslbundle

クライアント認証は、spring.grpc.server.ssl.client-auth を optional または require に設定することによっても構成できます。

たとえばテストを支援するために、サーバーの SSL サポートを一時的に無効にするには、spring.grpc.server.ssl.enabled を false に設定できます。

インプロセスサーバーの使用

クラスパスに io.grpc:grpc-inprocess の依存関係を追加し、spring.grpc.server.inprocess.name プロパティを定義することで、インプロセスサーバーを実行できます。このモードでは、通常のサーバーファクトリに加えて、インプロセスサーバーファクトリも自動的に構成されます。

ご提供いただいた名前は、in-process:<name> の形式でクライアントチャネルのターゲットとして使用できます。

リフレクション

When it’s available, Spring Boot will auto-configure the gRPC Reflection service (英語) . This allows clients to browse the metadata of your services and download their .proto files.

リフレクションサービスは、オプションの依存関係である io.grpc:grpc-services ライブラリに含まれています。自動構成を適用するには、プロジェクトにこの依存関係を追加する必要があります。

io.grpc:grpc-services ライブラリをお持ちで、リフレクションを自動構成したくない場合は、spring.grpc.server.reflection.enabled を false に設定できます。

サーバーの状態

gRPC サーバーは、標準サービス API(health/v1 [GitHub] (英語) )を使用して健全性情報を提供できます。これにより、クライアントはサーバーサービスの健全性を確認し、トラフィックを適切にルーティングできます。

Spring Boot は、独自の spring-boot-health モジュールと標準の gRPC ヘルスサービスとの間の橋渡し役を果たします。io.grpc:grpc-services モジュールと org.springframework.boot:spring-boot-health モジュールがクラスパス上に存在する場合、ヘルス情報が提供されます。

ヘルス指標を公開したくない場合は、spring.grpc.server.health.enabled を false に設定できます。

サービス別ヘルスマッピング

デフォルトでは、利用可能なすべてのヘルスインジケーターを使用して、サーバー全体のステータス("")に関するヘルス情報が提供されます。

It is also possible to provide fine-grained health information for specific services by including only a sub-set of health indicators. Custom mapping and ordering rules can also be defined on a per-service basis.

For example, the following configuration will provide health for “myservice” using only the db and redis indicators.

  • プロパティ

  • YAML

spring.grpc.server.health.service.myservice.include[0]=db
spring.grpc.server.health.service.myservice.include[1]=redis
spring:
  grpc:
    server:
      health:
        service:
          myservice:
            include:
            - db
            - redis
You can set spring.grpc.server.health.include-overall-health to false to disable the overall server status health if you only want to provide service-specific health.

プッシュ構成

Unlike web-based health checks, gRPC health information is periodically pushed rather than pulled. By default, the first health push happens 5 seconds after the application starts and then every subsequent 5 seconds.

To fine-tune this, you can use the following properties:

  • プロパティ

  • YAML

spring.grpc.server.health.schedule.period=5m
spring.grpc.server.health.schedule.delay=2s
spring:
  grpc:
    server:
      health:
        schedule:
          period: 5m
          delay: 2s
You can also set spring.grpc.server.health.schedule.enabled to false if want to send health updates in some other way.

Securing gRPC Server Applications

Netty Based Servers

Spring gRPC includes features that allow you to secure your Netty based server applications declaratively using Spring Security. This follows similar patterns to those you would use to secure a regular web application.

Spring Boot provides auto-configuration for both GrpcSecurity (Javadoc) and SecurityGrpcExceptionHandler (Javadoc) beans. Typically gRPC application are then secured using @PreAuthorize (Javadoc) annotations on your gRPC service beans, or a AuthenticationProcessInterceptor (Javadoc) bean.

For more details, please see the Spring gRPC documentation.

Servlet Container Based Servers

If your gRPC server is running within a standard Servlet Container, you can use typical web security configuration to secure your application. Spring Boot will auto-configre GrpcServerExecutorProvider (Javadoc) and SecurityContextServerInterceptor (Javadoc) beans to ensure that Spring Security works correctly.

Cross-Site Request Forgery (CSRF) protection is incompatible with the gRPC protocol and will be disabled by default for all gRPC requests. If you prefer to configure your own CSRF protection, you can switch this off by setting spring.grpc.server.security.csrf.enabled to false.

To help with manual Security configuration, Spring Boot provides request matchers for gRPC services. Matches are available for both servlet and reactive stacks. For example, the following will include all gRPC services with the exception of “special”.

  • Java

  • Kotlin

import org.springframework.boot.grpc.server.autoconfigure.security.web.servlet.GrpcRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) {
		http.securityMatcher(GrpcRequest.toAnyService().excluding("special"));
		http.authorizeHttpRequests((requests) -> requests.anyRequest().hasRole("GRPC_ADMIN"));
		http.httpBasic(withDefaults());
		return http.build();
	}

}
import org.springframework.boot.grpc.server.autoconfigure.security.web.servlet.GrpcRequest
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.Customizer.withDefaults
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.web.SecurityFilterChain

@Configuration(proxyBeanMethods = false)
class MySecurityConfiguration {

	@Bean
	fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
		http.securityMatcher(GrpcRequest.toAnyService().excluding("special"))
		http.authorizeHttpRequests { requests -> requests.anyRequest().hasRole("GRPC_ADMIN") }
		http.httpBasic(withDefaults())
		return http.build()
	}

}

OAuth2 リソースサーバー

OAuth2 (英語) is a widely used authorization framework. Spring Boot’s OAuth2 Resource Server support in compatible with gRPC and may be configured in the usual way.

For details of how to configure an OAuth2 Resource Server to use with your gRPC server application, see the "OAuth2" セクション of under “Security”.

Writing a gRPC Client Application

Spring Boot provides a spring-boot-grpc-client module and a spring-boot-starter-grpc-client starter POM that you can use for client applications.

Clients can call remote gRPC services by importing one or more of the “stub” classes generated from their .proto file. You can use the @ImportGrpcClients (Javadoc) annotation to import the stub classes you want to use.

Each import includes a target which can either be a logical channel name, or the base URL of the remote server. We typically recommend using channel names rather than hard-coding targets.

Here’s a typical example:

  • Java

  • Kotlin

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.grpc.client.ImportGrpcClients;

@SpringBootApplication(proxyBeanMethods = false)
@ImportGrpcClients(target = "hello", types = HelloWorldGrpc.HelloWorldBlockingStub.class)
public class MyApplication {

	public static void main(String[] args) {
		SpringApplication.run(MyApplication.class, args);
	}

}
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.docs.features.springapplication.MyApplication
import org.springframework.boot.runApplication
import org.springframework.grpc.client.ImportGrpcClients

@SpringBootApplication(proxyBeanMethods = false)
@ImportGrpcClients(target = "hello", types = [HelloWorldGrpc.HelloWorldBlockingStub::class])
class MyApplication

fun main(args: Array<String>) {
	runApplication<MyApplication>(*args)
}
If you don’t specify a target then “default” is used.
You can use the basePackageClasses or basePackages attribute of @ImportGrpcClients (Javadoc) to import all stubs in given package.

Channel Properties

When the target attribute of @ImportGrpcClients (Javadoc) uses a logical channel name, you’ll need to provide some properties so that Spring Boot can find the actual gRPC server to call.

To do that, you can add an entry using spring.grpc.channel.<name>.* properties. Typically, you’ll configure the actual real target, along with any other settings that are unique to the channel.

For example, the following will configure myservice to use the real target of static://grpc.example.com:9090. It also changes the keep-alive timeout and the maximum message size permitted:

  • プロパティ

  • YAML

spring.grpc.client.channel.myservice.target=static://grpc.example.com:9090
spring.grpc.client.channel.myservice.inbound.keepalive.timeout=40s
spring.grpc.client.channel.myservice.inbound.message.max-size=8MB
spring:
  grpc:
    client:
      channel:
        myservice:
          target: static://grpc.example.com:9090
          inbound:
            keepalive:
              timeout: 40s
            message:
              max-size: 8MB

Using Stub Beans

With your @ImportGrpcClients (Javadoc) annotations in place, and your properties written, you can use stubs as you would any other bean.

For example, here’s the HelloWorldStub being injected into a ApplicationRunner bean:

  • Java

  • Kotlin

import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.boot.docs.io.grpc.client.stubbeans.HelloWorldGrpc.HelloWorldBlockingStub;
import org.springframework.stereotype.Component;

@Component
class MyApplicationRunner implements ApplicationRunner {

	private final HelloWorldBlockingStub helloStub;

	MyApplicationRunner(HelloWorldGrpc.HelloWorldBlockingStub helloStub) {
		this.helloStub = helloStub;
	}

	@Override
	public void run(ApplicationArguments args) throws Exception {
		HelloRequest request = HelloRequest.newBuilder().setName("Spring").build();
		HelloReply reply = this.helloStub.sayHello(request);
		System.out.println(reply.getMessage());
	}

}
import org.springframework.boot.ApplicationArguments
import org.springframework.boot.ApplicationRunner


class MyApplicationRunner(val helloStub: HelloWorldGrpc.HelloWorldBlockingStub) : ApplicationRunner {

	override fun run(args: ApplicationArguments) {
		val request = HelloRequest.newBuilder().setName("Spring").build()
		val reply: HelloReply = helloStub.sayHello(request)
		println(reply.getMessage())
	}

}

Switching to Netty Shaded Client Transport

Under the hood, remote gRPC network calls are made using Netty. If you find that the version of Netty provided by the spring-boot-starter-grpc-client starter POM isn’t compatible with other libraries you use, you can switch to a “shaded” version.

切り替えるには、io.grpc:grpc-netty を除外して io.grpc:grpc-netty-shaded を含めることができます。例:

  • Maven

  • Gradle

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-grpc-client</artifactId>
	<exclusions>
		<!-- Exclude the gRPC Netty dependency -->
		<exclusion>
			<groupId>io.grpc</groupId>
			<artifactId>grpc-netty</artifactId>
		</exclusion>
	</exclusions>
</dependency>
<!-- Use gRPC Netty Shaded instead -->
<dependency>
	<groupId>io.grpc</groupId>
	<artifactId>grpc-netty-shaded</artifactId>
</dependency>
dependencies {
	implementation('org.springframework.boot:spring-boot-starter-grpc-client') {
		// Exclude the gRPC Netty dependency
		exclude group: 'io.grpc', module: 'grpc-netty'
	}
	// Use gRPC Netty Shaded instead
	implementation "io.grpc:grpc-netty-shaded"
}

SSL サポート

Client gRPC applications can connect to gRPC services using SSL/TSL encrypted connections. You can configure gRPC connections to use standard one-way-TLS, or mutual TLS

Standard one-way TLS

To use standard one-way TLS, you can set the ssl.enabled property to true in your channel properties. For example, the following will enabled an SSL/TLS connection for the myservice channel:

  • プロパティ

  • YAML

spring.grpc.client.channel.myservice.target=static://grpc.example.com:9090
spring.grpc.client.channel.myservice.ssl.enabled=true
spring:
  grpc:
    client:
      channel:
        myservice:
          target: static://grpc.example.com:9090
          ssl:
            enabled: true

Mutual TLS

Mutual TLS (mTLS) is a security protocol that requires both the client and the server to present certificates to each other. To use mutual TLS, you can set the ssl.bundle property in your channel properties. See the SSL core features documentation for details on how to declare an SSL bundle.

Here is an example the configures the myservice channel to use the mybundle bundle for mutual TLS:

  • プロパティ

  • YAML

spring.grpc.client.channel.myservice.target=static://grpc.example.com:9090
spring.grpc.client.channel.myservice.ssl.bundle=mybundle
spring:
  grpc:
    client:
      channel:
        myservice:
          target: static://grpc.example.com:9090
          ssl:
            bundle: mybundle

To temporarily disable client SSL support, for example to aid with testing, you can set bypass-certificate-validation to true on your channel config:

  • プロパティ

  • YAML

spring.grpc.client.channel.myservice.bypass-certificate-validation=true
spring:
  grpc:
    client:
      channel:
        myservice:
          bypass-certificate-validation: true

Using In-Process Channels

You can communicate with an in-process server (i.e. not listening on a network port) by including the io.grpc.grpc-inprocess dependency on your classpath.

In this mode, the in-process channel factory is auto-configured in addition to the regular channel factories (e.g. Netty). To prevent users from having to deal with multiple channel factories, a composite channel factory is configured as the primary channel factory bean. The composite consults its composed factories to find the first one that supports the channel target.

To use the in-process server the channel target must be set to in-process:<name>

To disable the in-process channel factory, you can set the spring.grpc.client.inprocess.enabled property to false.

可観測性

Spring Boot provides auto-configuration of the ObservationGrpcClientInterceptor (英語) whenever Micrometer is available. This interceptor provides observability into your gRPC client applications.

If you use Micrometer, but prefer to not to use it for gRPC, you can set spring.grpc.client.observation.enabled to false.

Channel Customization

If you need to customize your gRPC channel beyond the basic properties, you can use a GrpcChannelBuilderCustomizer (Javadoc) . Each customizer is called with the logical target name and the ManagedChannelBuilder (英語) that will build the channel. There’s also a convenient matching(String pattern) factory method that will limit customizations to targets that match the given regex pattern.

A common customizer use-case is to add security interceptors to the builder. For example, here we’re adding the BearerTokenAuthenticationInterceptor (Javadoc) to the target matching “hello”:

  • Java

  • Kotlin

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.grpc.client.GrpcChannelBuilderCustomizer;
import org.springframework.grpc.client.interceptor.security.BasicAuthenticationInterceptor;

@Configuration(proxyBeanMethods = false)
public class MyGrpcConfiguration {

	@Bean
	GrpcChannelBuilderCustomizer<?> helloChannelCustomizer() {
		return GrpcChannelBuilderCustomizer.matching("hello",
				(builder) -> builder.intercept(new BasicAuthenticationInterceptor("user", "password")));
	}

}
import io.grpc.ManagedChannelBuilder
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.grpc.client.GrpcChannelBuilderCustomizer
import org.springframework.grpc.client.interceptor.security.BasicAuthenticationInterceptor
import java.util.function.Consumer

@Configuration(proxyBeanMethods = false)
class MyGrpcConfiguration {

	@Bean
	fun helloChannelCustomizer(): GrpcChannelBuilderCustomizer<*> {
		return GrpcChannelBuilderCustomizer.matching("hello", { builder ->
			builder.intercept(BasicAuthenticationInterceptor("user", "password"))
		})
	}

}

Testing gRPC Applications

To help test your gRPC client and server applications you can use the spring-boot-grpc-test module or the spring-boot-starter-grpc-client-test / spring-boot-starter-grpc-server-test starter POMs.

Using In-Process Test Transport

The @AutoConfigureTestGrpcTransport (Javadoc) annotation allows you to quickly replace gRPC communication channels with in-process channels specifically designed for testing. Unlike regular in-process channels, these test channels to not require any configuration.

Using test gRPC transport means that you don’t need to actually listen on a network port to start your application. This allows your tests to run quickly, whilst still ensuring that your application works as expected.

The following example shows how you can use @AutoConfigureTestGrpcTransport (Javadoc) to test a gRPC server application:

  • Java

  • Kotlin

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.grpc.test.autoconfigure.AutoConfigureTestGrpcTransport;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.grpc.client.ImportGrpcClients;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest
@AutoConfigureTestGrpcTransport
@ImportGrpcClients(types = HelloWorldGrpc.HelloWorldBlockingStub.class)
class MyGrpcTests {

	@Autowired
	private HelloWorldGrpc.HelloWorldBlockingStub helloStub;

	@Test
	void sayHello() {
		HelloRequest request = HelloRequest.newBuilder().setName("Spring").build();
		HelloReply reply = this.helloStub.sayHello(request);
		assertThat(reply.getMessage()).isEqualTo("Hello 'Spring'");
	}

}
import org.assertj.core.api.Assertions.assertThat
import org.jooq.DSLContext
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.grpc.test.autoconfigure.AutoConfigureTestGrpcTransport
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.grpc.client.ImportGrpcClients

@SpringBootTest
@AutoConfigureTestGrpcTransport
@ImportGrpcClients(types = [HelloWorldGrpc.HelloWorldBlockingStub::class])
class MyGrpcTests(@Autowired val helloStub: HelloWorldGrpc.HelloWorldBlockingStub) {

	@Test
	fun sayHello() {
		val request = HelloRequest.newBuilder().setName("Spring").build()
		val reply = helloStub.sayHello(request)
		assertThat(reply.getMessage()).isEqualTo("Hello 'Spring'")
	}

}

実行中のサーバーでのテスト

If you prefer to test your gRPC application by starting the real server and using the actual network connection, we recommend that you use random ports. This will ensure that you can run your tests in any environment, and that you won’t accidentally call real services.

To start a gRPC server using a random port, set spring.grpc.server.port to 0. You can use the @LocalGrpcServerPort (Javadoc) annotation to obtain the actual port that the server started on.

Here’s an example test:

  • Java

  • Kotlin

import io.grpc.ManagedChannel;
import io.grpc.netty.NettyChannelBuilder;
import org.junit.jupiter.api.Test;

import org.springframework.boot.docs.io.grpc.testing.localserverport.HelloWorldGrpc.HelloWorldBlockingStub;
import org.springframework.boot.grpc.test.autoconfigure.LocalGrpcServerPort;
import org.springframework.boot.test.context.SpringBootTest;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest(properties = "spring.grpc.server.port=0")
class MyGrpcIntegrationTests {

	@LocalGrpcServerPort
	private int port;

	@Test
	void sayHello() {
		String target = "localhost:%s".formatted(this.port);
		ManagedChannel channel = NettyChannelBuilder.forTarget(target).usePlaintext().build();
		try {
			HelloWorldBlockingStub hello = HelloWorldGrpc.newBlockingStub(channel);
			HelloRequest request = HelloRequest.newBuilder().setName("Spring").build();
			assertThat(hello.sayHello(request).getMessage()).isEqualTo("Hello 'Spring'");
		}
		finally {
			channel.shutdown();
		}
	}

}
import io.grpc.ManagedChannel
import io.grpc.netty.NettyChannelBuilder
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.springframework.boot.grpc.test.autoconfigure.LocalGrpcServerPort
import org.springframework.boot.test.context.SpringBootTest

@SpringBootTest(properties = ["spring.grpc.server.port=0"])
class MyGrpcIntegrationTests {

	@LocalGrpcServerPort
	var port = 0

	@Test
	fun sayHello() {
		val target = "localhost:${port}"
		val channel: ManagedChannel = NettyChannelBuilder.forTarget(target).usePlaintext().build()
		try {
			val hello: HelloWorldGrpc.HelloWorldBlockingStub = HelloWorldGrpc.newBlockingStub(channel)
			val request = HelloRequest.newBuilder().setName("Spring").build()
			assertThat(hello.sayHello(request).getMessage()).isEqualTo("Hello 'Spring'")
		} finally {
			channel.shutdown()
		}
	}
}