Back to Guides
このページを編集

gRPC code generation reference guide

このリファレンスガイドでは、gRPC コード生成を設定する方法について説明します。最初に gRPC 公式ガイド を読むことを推奨します。

gRPC コード生成の有効化

デフォルトでは、 src/main/proto ディレクトリーにある \*.proto ファイルは、ビルドプロセス中に Java ソースにコンパイルされます。

Maven の使用

gRPC コード生成を有効化するには、プロジェクトに以下の依存関係を追加します。

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-grpc</artifactId>
</dependency>

quarkus:generate-code ゴールは、quarkus パッケージングを使用する際に、Quarkus Maven プラグインのデフォルトライフサイクル中にデフォルトで実行され、コード生成を処理します。

Gradleの使用

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

implementation 'io.quarkus:quarkus-grpc'

Customizing the proto directory

デフォルトでは、 \*.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>
            <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 スタブを生成する必要があるかもしれません。 その場合は、以下を実行します。

  1. proto ファイルを含むアーティファクトへの依存関係をプロジェクトに追加します。

  2. 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

プロパティーキー内の : 文字は、エスケープする必要があることに注意してください。

Kotlinコード生成

protoc は、生成されたJavaコードに加えて Kotlinコードの生成 もサポートしています。

デフォルトでは、依存関係 io.quarkus:quarkus-kotlin が存在する場合、Kotlin コード生成が有効になります。

この機能を明示的に有効/無効にするには、 application.properties ファイルの quarkus.generate-code.grpc.kotlin.generate プロパティを true または false に設定します。

com.google.protobuf:protobuf-kotlin needs to be included as dependency in the project.

コード生成をスキップする

次を使用して gRPC コード生成をスキップできます。

  1. grpc.codegen.skip システムプロパティー: -Dgrpc.codegen.skip=true

  2. 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.81.0</grpc.version>
<protoc.version>4.35.0</protoc.version>

これらのプロパティーは、gRPC バージョンと protoc バージョンを設定します。

次に、 build セクションに eu.maveniverse.maven.nisse:plugin3 と protobuf-maven-plugin の設定を追加します：

<build>
    <plugins>
        <plugin>
            <groupId>eu.maveniverse.maven.nisse</groupId>
            <artifactId>plugin3</artifactId>
            <version>0.4.0</version>
            <executions>
                <execution>
                    <id>inject-properties</id>
                    <goals>
                        <goal>inject-properties</goal>
                    </goals>
                    <phase>validate</phase>
                </execution>
            </executions>
        </plugin>
        <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 クラス生成は protoc というツールを使用します。このため、Nisse Mavenプラグインを使用して、オペレーティングシステムと互換性のある実行可能ファイルをターゲットにしています。

注記: この設定は、Quarkus 開発エクスペリエンスに適合するように、 protobuf-maven-plugin にデフォルトの gRPC クラスと Mutiny を使用するクラスを生成するように指示します。

When using protobuf-maven-plugin, instead of the quarkus-maven-plugin, you need to re-generate classes (using mvn compile) every time you update the proto files.

Nisse Maven プラグインが正しいプロパティを生成するには、 nisse.compat.osDetector システム・プロパティが設定されているようにする必要があります。 これは、次の .mvn/maven.config ファイルを追加することで可能です：

-Dnisse.compat.osDetector=true

依存関係から生成された gRPC クラスを使用する

proto ファイルから生成されたクラスである gRPC クラスがアプリケーションの依存関係にある場合、依存関係には Jandex インデックスが必要です。 jandex-maven-plugin を使用して Jandex インデックスを作成できます。 このトピックの詳細は、CDI ガイドの Bean の検出 セクションを参照してください。

<build>
    <plugins>
        <plugin>
            <groupId>io.smallrye</groupId>
            <artifactId>jandex-maven-plugin</artifactId>
            <version>3.6.0</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 '2.3.0'
}
It is recommended to package the proto files in a dependency instead of the generated classes, so Quarkus can generate optimized classes. Refer to the dedicated section for more information.

引数ファイル

protoc コマンドラインが最大コマンド長を超える場合、引数ファイルを使用して引数を protoc コマンドに渡すように Quarkus に要求できます。

この機能を有効にするには、 application.properties ファイル内の quarkus.generate-code.grpc.use-arg-file プロパティーを true に設定します。

Windows でコマンドラインが 8190 文字を超える場合、Quarkus は自動的に引数ファイルを使用して引数を protoc コマンドに渡します。

Local vs. Downloaded 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-aarch_64

com.google.protobuf:protoc:VERSION:exe:linux-aarch_64 および io.grpc:protoc-gen-grpc-java:VERSION:exe:linux-aarch_64

Linux/Power PC 64 ビット

linux-ppcle_64

com.google.protobuf:protoc:VERSION:exe:linux-ppcle_64 および io.grpc:protoc-gen-grpc-java:VERSION:exe:linux-ppcle_64

Linux/S390 64 ビット

linux-s390_64

com.google.protobuf:protoc:VERSION:exe:linux-s390_64 および io.grpc:protoc-gen-grpc-java:VERSION:exe:linux-s390_64

Linux/x86 32 ビット

linux-x86_32

com.google.protobuf:protoc:VERSION:exe:linux-x86_32 および io.grpc:protoc-gen-grpc-java:VERSION:exe:linux-x86_32

Linux/x86 64 ビット

linux-x86_64

com.google.protobuf:protoc:VERSION:exe:linux-x86_64 および io.grpc:protoc-gen-grpc-java:VERSION:exe:linux-x86_64

Mac osx/ARM64

osx-aarch_64

com.google.protobuf:protoc:VERSION:exe:osx-aarch_64 および io.grpc:protoc-gen-grpc-java:VERSION:exe:osx-aarch_64

Mac osx/x86 64 ビット

osx-x86_64

com.google.protobuf:protoc:VERSION:exe:osx-x86_64 および io.grpc:protoc-gen-grpc-java:VERSION:exe:osx-x86_64

Windows x86 32 ビット

windows-x86_32

com.google.protobuf:protoc:VERSION:exe:windows-x86_32 および io.grpc:protoc-gen-grpc-java:VERSION:exe:windows-x86_32

Windows x86 64 ビット

windows-x86_64

com.google.protobuf:protoc:VERSION:exe:windows-x86_64 および io.grpc:protoc-gen-grpc-java:VERSION:exe:windows-x86_64

protoc とプラグインのパッケージング (分類子を使用) により、不要なプラットフォームを個別に除外することはできません。

When using AArch64 on macOS be aware of this issue: meaning that the macOS x86_64 protoc and macOS aarch_64 protoc are the same - both are macOS x86_64. So you need to enable Rosetta (softwareupdate --install-rosetta) on your ARM based macOS if you want to generate protobuf classes.

ただし、 protoc 依存関係を完全に除外し、 quarkus.grpc.protoc-path システムプロパティーを使用して、マシンにインストールされている protoc 実行可能ファイルへのパスを設定することができます。 したがって、 protoc バリアントをダウンロードする必要はありません。

Step 1: Exclusion of protoc
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-grpc</artifactId>
    <exclusions>
        <exclusion>
            <groupId>com.google.protobuf</groupId>
            <artifactId>protoc</artifactId>
        </exclusion>
    </exclusions>
</dependency>
Step 2: Passing the quarkus.grpc.protoc-path property:
mvn clean quarkus:dev -Dquarkus.grpc.protoc-path=/path/to/protoc
Using this approach requires to have protoc installed locally. It will not download any protoc artifact.
Unfortunately, this only works for protoc and not for the Java plugin. The Java plugin is always downloaded.

Quarkus is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license. CC by 3.0

This website was built with Roq on Quarkus, is hosted on GitHub Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
Copyright © Quarkus. All rights reserved. For details on our trademarks, please visit our Trademark Policy and Trademark List. Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association.