バージョン:

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>

Gradleの使用

Gradle の場合、プロジェクトに以下の依存関係を追加します。

implementation 'io.quarkus:quarkus-grpc'

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.59.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.1.6</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> を参照してください。

gRPC コード生成の有効化
- Maven の使用
- Gradleの使用
proto ディレクトリーのカスタマイズ
記述子セットの生成
依存関係の gRPC コード生成の設定
- インポート用の Proto ファイル
- 依存関係の Proto ファイル
コード生成をスキップする
- proto から protobuf-maven-plugin で Java ファイルを生成する
依存関係から生成された gRPC クラスを使用する