gRPC コード生成リファレンスガイド
このリファレンスガイドでは、gRPC コード生成を設定する方法について説明します。最初に gRPC 公式ガイド を読むことを推奨します。
gRPC コード生成の有効化
デフォルトでは、 src/main/proto
ディレクトリーにある \*.proto
ファイルは、ビルドプロセス中に Java ソースにコンパイルされます。
Maven の使用
gRPC コード生成を有効化するには、プロジェクトに以下の依存関係を追加します。
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-grpc</artifactId>
</dependency>
次に、Quarkus Maven プラグインで generate-code
フェーズが有効化されていることを確認します。
<plugin>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.platform.version}</version>
<extensions>true</extensions>
<executions>
<execution>
<goals>
<goal>build</goal>
<goal>generate-code</goal>
<goal>generate-code-tests</goal>
</goals>
</execution>
</executions>
</plugin>
proto ディレクトリーのカスタマイズ
デフォルトでは、 \*.proto
ファイルは src/main/proto
ディレクトリーにあると想定されます。
この場所は、ビルド記述子 の quarkus.grpc.codegen.proto-directory
プロパティーを使用して設定できます。
Maven では、以下の設定を追加します。
<plugin>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.platform.version}</version>
<extensions>true</extensions>
<executions>
<execution>
<goals>
<goal>build</goal>
<goal>generate-code</goal>
<goal>generate-code-tests</goal>
</goals>
<configuration>
<properties>
<quarkus.grpc.codegen.proto-directory>${project.basedir}/ext/proto</quarkus.grpc.codegen.proto-directory>
</properties>
</configuration>
</execution>
</executions>
</plugin>
Gradle では、以下の設定を使用します。
quarkus {
quarkusBuildProperties.put("quarkus.grpc.codegen.proto-directory", "${project.projectDir}/ext/proto")
}
記述子セットの生成
Protocol Buffers には、独自の型の説明は含まれていません。したがって、型が定義された対応する .proto ファイルがない raw メッセージのみが指定された場合、有用なデータを抽出することは困難です。ただし、.proto ファイルの内容自体は、 プロトコルバッファーを使用して表現 できます。
デフォルトでは、Quarkus はこれらの記述子を生成しません。Quarkus は、これらを生成するためのいくつかの設定オプションを提供します。これらは、 application.properties
または application.yml
ファイルに追加されます。
-
quarkus.generate-code.grpc.descriptor-set.generate
-
生成を有効にするには
true
に設定します。
-
-
quarkus.generate-code.grpc.descriptor-set.output-dir
-
これをプロジェクトのビルドディレクトリーを基準とした相対値に設定します (Maven の場合は
target
、Gradle の場合はbuild
)。 -
Maven のデフォルト値:
target/generated-sources/grpc
-
Gradle のデフォルト値:
$buildDir/classes/java/quarkus-generated-sources/grpc
-
-
quarkus.generate-code.grpc.descriptor-set.name
-
生成する記述子セットファイルの名前
-
デフォルト値:
descriptor_set.dsc
-
依存関係の gRPC コード生成の設定
Java ソースにコンパイルする *.proto
ファイルを含む依存関係がある可能性があります。
このセクションでは、コード生成中にこれらの \*.proto
ファイルを含めるようにコード生成を設定する方法について説明します。
インポート用の Proto ファイル
Protocol Buffers 仕様では、 proto
ファイルをインポートする方法が提供されています。
Quarkus コード生成メカニズムを使用すると、 application.properties
で quarkus.generate-code.grpc.scan-for-imports
プロパティーを設定することで、可能なインポートをスキャンする依存関係の範囲を制御できます。
以下のいずれかの値に設定できます。
-
all
- すべての依存関係をスキャンします。 -
none
- 依存関係をスキャンせず、src/main/proto
またはsrc/test/proto
で定義されているもののみを使用します。 -
groupId1:artifactId1,groupId2:artifactId2
- グループ ID とアーティファクト ID で指定された依存関係のみをスキャンします。
指定されていない場合、プロパティーはデフォルトで com.google.protobuf:protobuf-java
になります。
これをオーバーライドするには、 application.properties
で quarkus.generate-code.grpc.scan-for-imports
プロパティーを設定します。
以下に例を示します。
quarkus.generate-code.grpc.scan-for-imports=all
依存関係の Proto ファイル
場合によっては、別のプロジェクトの proto
ファイルを使用して gRPC スタブを生成する必要があるかもしれません。
その場合は、以下を実行します。
-
proto ファイルを含むアーティファクトへの依存関係をプロジェクトに追加します。
-
application.properties
で、proto ファイルをスキャンしたい依存関係を指定します。
quarkus.generate-code.grpc.scan-for-proto=<groupId>:<artifactId>
プロパティーの値は、デフォルト値である none
、または groupId:artifactId
座標のコンマ区切りリストになります。
依存関係に多数の proto ファイルが含まれており、それらのサブセットのみのクラスを生成する場合は、依存関係ごとに glob パターンを指定できます。
一致させるパスは、依存関係内の src/main/resources
パスからの相対パスです。
quarkus.generate-code.grpc.scan-for-proto-include."<groupId>:<artifactId>"=foo/**,bar/**,banana/a-proto.proto
quarkus.generate-code.grpc.scan-for-proto-exclude."<groupId>:<artifactId>"=foo/private/**,bar/another-proto.proto
プロパティーキー内の :
文字は、エスケープする必要があることに注意してください。
コード生成をスキップする
次を使用して gRPC コード生成をスキップできます。
-
grpc.codegen.skip
システムプロパティー:-Dgrpc.codegen.skip=true
-
application.properties
ファイルのquarkus.grpc.codegen.skip
プロパティー:quarkus.grpc.codegen.skip=true
proto から protobuf-maven-plugin で Java ファイルを生成する
または、 proto
ファイルのスタブを生成するには、 protobuf-maven-plugin
を使用できます。
ただし、特別なニーズがない限り、Quarkus サポートを使用することを推奨します。
これを行うには、 <properties>
セクションの以下のプロパティーを定義します。
<grpc.version>1.69.1</grpc.version>
<protoc.version>3.25.5</protoc.version>
これらのプロパティーは、gRPC バージョンと protoc
バージョンを設定します。
次に、 os-maven-plugin
エクステンションと protobuf-maven-plugin
設定を build
セクションに追加します。
<build>
<extensions>
<extension>
<groupId>kr.motd.maven</groupId>
<artifactId>os-maven-plugin</artifactId>
<version>${os-maven-plugin-version}</version>
</extension>
</extensions>
<plugins>
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId> (1)
<version>${protobuf-maven-plugin-version}</version>
<configuration>
<protocArtifact>com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier}</protocArtifact> (2)
<pluginId>grpc-java</pluginId>
<pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
<protocPlugins>
<protocPlugin>
<id>quarkus-grpc-protoc-plugin</id>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-grpc-protoc-plugin</artifactId>
<version>{quarkus-version}</version>
<mainClass>io.quarkus.grpc.protoc.plugin.MutinyGrpcGenerator</mainClass>
</protocPlugin>
</protocPlugins>
</configuration>
<executions>
<execution>
<id>compile</id>
<goals>
<goal>compile</goal>
<goal>compile-custom</goal>
</goals>
</execution>
<execution>
<id>test-compile</id>
<goals>
<goal>test-compile</goal>
<goal>test-compile-custom</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- ... -->
</plugins>
</build>
1 | protobuf-maven-plugin は、gRPC サービス定義 (proto ファイル) からスタブクラスを生成します。 |
2 | クラス生成では、OS 固有のツール protoc が使用されます。このため、オペレーティングシステムと互換性のある実行可能ファイルをターゲットにするには、 os-maven-plugin を使用します。 |
注記: この設定は、Quarkus 開発エクスペリエンスに適合するように、 protobuf-maven-plugin
にデフォルトの gRPC クラスと Mutiny を使用するクラスを生成するように指示します。
quarkus-maven-plugin の代わりに protobuf-maven-plugin を使用する場合は、 proto ファイルを更新するたびに (mvn compile を使用して) クラスを再生成する必要があります。
|
依存関係から生成された gRPC クラスを使用する
proto
ファイルから生成されたクラスである gRPC クラスがアプリケーションの依存関係にある場合、依存関係には Jandex インデックスが必要です。
jandex-maven-plugin
を使用して Jandex インデックスを作成できます。
このトピックの詳細は、CDI ガイドの Bean の検出 セクションを参照してください。
<build>
<plugins>
<plugin>
<groupId>io.smallrye</groupId>
<artifactId>jandex-maven-plugin</artifactId>
<version>3.2.7</version>
<executions>
<execution>
<id>make-index</id>
<goals>
<goal>jandex</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
Gradle を使用している場合は、以下の設定を使用できます。
plugins {
id 'org.kordamp.gradle.jandex' version '1.1.0'
}
Quarkus が最適化されたクラスを生成できるように、生成されたクラスではなく依存関係で proto ファイルをパッケージ化することを推奨します。
詳細は、<<scan-for-proto, dedicated section> を参照してください。
|
引数ファイル
protoc
コマンドラインが最大コマンド長を超える場合、引数ファイルを使用して引数を protoc
コマンドに渡すように Quarkus に要求できます。
この機能を有効にするには、 application.properties
ファイル内の quarkus.generate-code.grpc.use-arg-file
プロパティーを true
に設定します。
Windows でコマンドラインが 8190 文字を超える場合、Quarkus は自動的に引数ファイルを使用して引数を protoc
コマンドに渡します。
ローカルとダウンロードされた protoc
の比較
gRPC クラスを生成するために、Quarkus は com.google.protobuf
グループ ID の protoc
アーティファクトを使用します。
ただし、さまざまなプラットフォームのサポートを確実にするために、Quarkus は protoc
アーティファクトの可能な すべて のバリアントを自動的にダウンロードします。
さらに、Quarkus は protoc
と、Java で gRPC クラスを生成するために使用されるプラグインの両方をダウンロードします。
たとえば、Linux を使用している場合でも、Quarkus は Windows および MacOS 用の protoc
と Java プラグインアーティファクトをダウンロードします。
次の表は、 protoc
とプラグインアーティファクトのさまざまなバリアントを示しています。
Platform | Classifier | Dependencies |
---|---|---|
Linux/ARM64 |
|
|
Linux/Power PC 64 ビット |
|
|
Linux/S390 64 ビット |
|
|
Linux/x86 32 ビット |
|
|
Linux/x86 64 ビット |
|
|
Mac osx/ARM64 |
|
|
Mac osx/x86 64 ビット |
|
|
Windows x86 32 ビット |
|
|
Windows x86 64 ビット |
|
|
protoc
とプラグインのパッケージング (分類子を使用) により、不要なプラットフォームを個別に除外することはできません。
ただし、 protoc
依存関係を完全に除外し、 quarkus.grpc.protoc-path
システムプロパティーを使用して、マシンにインストールされている protoc
実行可能ファイルへのパスを設定することができます。
したがって、 protoc
バリアントをダウンロードする必要はありません。
protoc
を除外する<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-grpc</artifactId>
<exclusions>
<exclusion>
<groupId>com.google.protobuf</groupId>
<artifactId>protoc</artifactId>
</exclusion>
</exclusions>
</dependency>
quarkus.grpc.protoc-path
プロパティーを渡すmvn clean quarkus:dev -Dquarkus.grpc.protoc-path=/path/to/protoc
この方法を使用するには、 protoc をローカルにインストールする必要があります。 protoc アーティファクトはダウンロードされません。
|
残念ながら、これは protoc でのみ機能し、Java プラグインでは機能しません。Java プラグインは常にダウンロードされます。
|