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=mysslbundlespring:
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]=redisspring:
grpc:
server:
health:
service:
myservice:
include:
- db
- redisYou 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=2sspring:
grpc:
server:
health:
schedule:
period: 5m
delay: 2sYou 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()
}
}For reactive matches use org.springframework.boot.grpc.server.autoconfigure.security.web.servlet.GrpcRequest (Javadoc) 。 |
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=8MBspring:
grpc:
client:
channel:
myservice:
target: static://grpc.example.com:9090
inbound:
keepalive:
timeout: 40s
message:
max-size: 8MBUsing 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=truespring:
grpc:
client:
channel:
myservice:
target: static://grpc.example.com:9090
ssl:
enabled: trueMutual 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=mybundlespring:
grpc:
client:
channel:
myservice:
target: static://grpc.example.com:9090
ssl:
bundle: mybundleTo temporarily disable client SSL support, for example to aid with testing, you can set
|
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.
By default, using @AutoConfigureTestGrpcTransport (Javadoc) will:
Configure test
GrpcServerFactory(Javadoc) /GrpcChannelFactory(Javadoc) beansDisable any gRPC servelt registration.
Disable
GrpcServerFactory(Javadoc) bean auto-configuration.Disable
GrpcChannelFactory(Javadoc) bean auto-configuration.
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()
}
}
}