gRPC code generation reference guide

本参考指南说明了如何配置 gRPC 代码生成。建议先阅读 official gRPC guide。

This reference guide explains how to configure gRPC code generation. It is recommended to read the official gRPC guide first.

Enabling gRPC code generation

默认情况下，位于 `src/main/proto`目录中的 `\*.proto`文件在构建过程中会被编译成 Java 源文件。

By default, \*.proto files located in the src/main/proto directory are compiled into Java sources during the build process.

Using Maven

若要启用 gRPC 代码生成，请将以下依赖添加到项目：

To enable gRPC code generation, add the following dependency to your project:

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

接下来，确保在 Quarkus Maven 插件中启用了 `generate-code`阶段：

Next, ensure that the generate-code phase is enabled in the Quarkus Maven plugin:

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

Using Gradle

对于 Gradle，将以下依赖添加到项目：

For Gradle, add the following dependency to your project:

implementation 'io.quarkus:quarkus-grpc'

Customizing the proto directory

默认情况下，会假定 .proto` files are located in the src/main/proto directory. You can configure this location using the quarkus.grpc.codegen.proto-directory property in your *build descriptor。

By default, it is assumed that the .proto files are located in the src/main/proto directory. You can configure this location using the quarkus.grpc.codegen.proto-directory property in your *build descriptor.

使用 Maven，添加以下配置：

With Maven, add the following configuration:

<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，使用以下配置：

With Gradle, use the following configuration:

quarkus {
    quarkusBuildProperties.put("quarkus.grpc.codegen.proto-directory", "${project.projectDir}/ext/proto")
}

Generating Descriptor Set

协议缓冲区不包含其自身的类型描述。因此，仅给定原始消息而没有定义其类型的对应 .proto 文件，则很难提取任何有用的数据。但是，.proto 文件的内容本身也可以是 represented using protocol buffers。

Protocol Buffers do not contain descriptions of their own types. Thus, given only a raw message without the corresponding .proto file defining its type, it is difficult to extract any useful data. However, the contents of a .proto file can itself be represented using protocol buffers.

默认情况下，Quarkus 不生成这些描述符。Quarkus 确实提供了用于生成它们的几个配置选项。这些选项将添加到 `application.properties`或 `application.yml`文件中：

By default, Quarkus does not generate these descriptors. Quarkus does provide several configuration options for generating them. These would be added to your application.properties or application.yml file:

quarkus.generate-code.grpc.descriptor-set.generate
- Set to true to enable generation
quarkus.generate-code.grpc.descriptor-set.output-dir
- Set this to a value relative to the project’s build directory (i.e. target for Maven, build for Gradle)
- Maven default value: target/generated-sources/grpc
- Gradle default value: $buildDir/classes/java/quarkus-generated-sources/grpc
quarkus.generate-code.grpc.descriptor-set.name
- Name of the descriptor set file to generate
- Default value: descriptor_set.dsc

Configuring gRPC code generation for dependencies

在代码生成过程中，你可能会拥有包含 .proto files you want to compile to Java sources. This section explains how to configure code generation to include these \.proto 文件的依赖项。

You may have dependencies that contain .proto files you want to compile to Java sources. This section explains how to configure code generation to include these \.proto files during code generation.

Proto files for imports

Protocol Buffers 规范提供了一种办法来导入 proto 文件。Quarkus 代码生成机制允许你通过在 application.properties 中设置 quarkus.generate-code.grpc.scan-for-imports 属性来控制要扫描以查找可能导入项的依赖项范围。你可以将该属性设为以下某个值：

The Protocol Buffers specification provides a way to import proto files. The Quarkus code generation mechanism lets you control the scope of dependencies to scan for possible imports by setting the quarkus.generate-code.grpc.scan-for-imports property in your application.properties. You can set it to one of the following values:

all - scan all dependencies
none - don’t scan dependencies, use only what is defined in src/main/proto or src/test/proto
groupId1:artifactId1,groupId2:artifactId2 - scan only the specified dependencies by group ID and artifact ID.

如果未指定，则该属性默认为 com.google.protobuf:protobuf-java。要覆盖它，请在 application.properties 中设置 quarkus.generate-code.grpc.scan-for-imports 属性。例如：

If not specified, the property defaults to com.google.protobuf:protobuf-java. To override it, set the quarkus.generate-code.grpc.scan-for-imports property in your application.properties. For example:

quarkus.generate-code.grpc.scan-for-imports=all

Proto files from dependencies

在某些情况下，你可能希望从其他项目中使用 proto 文件来生成 gRPC 存根。要执行此操作：

In some cases, you may want to use proto files from a different project to generate gRPC stubs. To do this:

Add a dependency on the artifact that contains the proto file to your project.
In application.properties, specify the dependencies you want to scan for proto files.

quarkus.generate-code.grpc.scan-for-proto=<groupId>:<artifactId>

该属性的值可以是 none（这是默认值），或由 groupId:artifactId 坐标分隔的逗号分隔列表。

The value of the property can be none, which is the default, or a comma-separated list of groupId:artifactId coordinates.

如果依赖项包含许多 proto 文件，并且你仅想为其中一部分生成类，则可以为每个依赖项指定 glob 模式。要匹配的路径相对于依赖项中的 src/main/resources 路径。例如：

If the dependency contains many proto files, and you want to generate classes for only a subset of them, you can specify glob patterns per dependency. The paths to match are relative to the src/main/resources path in the dependency. For example:

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

请注意，属性键中的 : 字符必须进行转义。

Note that : characters in the property keys must be escaped.

Skipping code generation

你可以使用以下内容跳过 gRPC 代码生成：

You can skip gRPC code generation using:

The grpc.codegen.skip system property: -Dgrpc.codegen.skip=true
The quarkus.grpc.codegen.skip property in your application.properties file: quarkus.grpc.codegen.skip=true

Generating Java files from proto with the protobuf-maven-plugin

或者，要为 proto 文件生成存根，你可以使用 protobuf-maven-plugin。但是，建议使用 Quarkus 支持，除非你有特定需要。

Alternatively, to generate stubs for proto files, you can use the protobuf-maven-plugin. However, it’s recommended to use Quarkus support unless you have a specific need.

若要执行此操作，请在 <properties> 部分中定义以下属性：

To do this, define the following properties in the <properties> section:

<grpc.version>{grpc-version}</grpc.version>
<protoc.version>{protoc-version}</protoc.version>

这些属性配置 gRPC 版本和 protoc 版本。

These properties configure the gRPC version and the protoc version.

然后，将 os-maven-plugin 扩展和 protobuf-maven-plugin 配置添加到 build 部分：

Then, add the os-maven-plugin extension and the protobuf-maven-plugin configuration to the build section:

<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	The `protobuf-maven-plugin` generates stub classes from your gRPC service definition (`proto` files).
2	Class generation uses the tool `protoc`, which is OS-specific. This is why we use the `os-maven-plugin` to target the executable compatible with the operating system.

注意：此配置指示 protobuf-maven-plugin 使用 Mutiny 生成默认 gRPC 类和类，以适应 Quarkus 开发体验。

Note: This configuration instructs the protobuf-maven-plugin to generate default gRPC classes and classes using Mutiny to fit with the Quarkus development experience.

在使用 protobuf-maven-plugin 代替 quarkus-maven-plugin 时，需要在每次更新 proto 文件时重新生成类（使用 mvn compile）。

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.

Using generated gRPC classes from dependencies

当从 proto 文件生成类的 gRPC 类在应用程序的依赖关系中时，依赖关系需要一个 Jandex 索引。您可以使用 jandex-maven-plugin 创建 Jandex 索引。有关此主题的更多信息，请参阅 CDI 指南的 Bean Discovery 部分。

When gRPC classes, which are classes generated from proto files, are in a dependency of the application, the dependency needs a Jandex index. You can create a Jandex index using the jandex-maven-plugin. More information on this topic can be found in the Bean Discovery section of the CDI guide.

<build>
    <plugins>
        <plugin>
            <groupId>io.smallrye</groupId>
            <artifactId>jandex-maven-plugin</artifactId>
            <version>{jandex-version}</version>
            <executions>
                <execution>
                <id>make-index</id>
                <goals>
                    <goal>jandex</goal>
                </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

如果您正在使用 Gradle，可以将以下配置用于：

If you are using Gradle, you can use the following configuration:

plugins {
    id 'org.kordamp.gradle.jandex' version '1.1.0'
}

建议将 proto 文件打包到依赖关系中，而不是生成的类，这样 Quarkus 就可以生成优化的类。有关更多信息，请参阅 dedicated section。

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 scan-for-proto for more information.

Argument files

当 protoc 命令行超出最大命令长度时，您可以要求 Quarkus 使用参数文件将参数传递到 protoc 命令。

When the protoc command line exceeds the maximum command length, you can ask Quarkus to use an argument file to pass the arguments to the protoc command.

若要启用此功能，请将 application.properties 文件中的 quarkus.generate-code.grpc.use-arg-file 属性设置为 true。

To enable this feature, set the quarkus.generate-code.grpc.use-arg-file property in your application.properties file to true.

如果您使用的是 Windows，并且命令行超过 8190 个字符，则 Quarkus 会自动使用参数文件将参数传递到 protoc 命令。

If you are on Windows, and the command line exceeds 8190 characters, Quarkus automatically uses an argument file to pass the arguments to the protoc command.