The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Back to Guides
このページを編集

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

  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

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

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

次を使用して 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.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-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 とプラグインのパッケージング (分類子を使用) により、不要なプラットフォームを個別に除外することはできません。

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

ステップ 1: protoc を除外する
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-grpc</artifactId>
    <exclusions>
        <exclusion>
            <groupId>com.google.protobuf</groupId>
            <artifactId>protoc</artifactId>
        </exclusion>
    </exclusions>
</dependency>
ステップ 2: quarkus.grpc.protoc-path プロパティーを渡す
mvn clean quarkus:dev -Dquarkus.grpc.protoc-path=/path/to/protoc
この方法を使用するには、 protoc をローカルにインストールする必要があります。 protoc アーティファクトはダウンロードされません。
残念ながら、これは protoc でのみ機能し、Java プラグインでは機能しません。Java プラグインは常にダウンロードされます。

関連コンテンツ

同じエクステンションについて

同じトピックについて

Quarkusはオープンです。このプロジェクトのすべての依存関係は、Apache Software License 2.0 または互換性のあるライセンスのもとで利用可能です。

このウェブサイトはJekyll で構築され、GitHub Pages にホストされ、完全にオープンソースです。改善したい場合は、ウェブサイトをフォークし、修正してみせてください。

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
CC by 3.0 | Privacy Policy Sponsored by