为何Quarkus应用同一RestApi在native与JVM模式下响应不同？

以下是一个带有响应式方法的Quarkus RestApi示例代码：

@Consumes
@Produces(MediaType.APPLICATION_JSON)
@Path("/api/v1/datasource")
public class DatasourceResource {

    @Inject
    DatabaseBoundary databaseBoundary;

    @POST
    @Path("/query")
    public Uni<Response> query(DatasourceQuery param) {
        DatasourceRecordDTO result = new DatasourceRecordDTO();
        result.setId("888");
        List<String> header = Arrays.asList("id", "name", "age");
        DatasourceRecordItem item = new DatasourceRecordItem();
        item.setKey("888");
        item.setValueList(Arrays.asList("123", "wkx", "26"));
        result.setHeader(header);
        result.setRows(List.of(item));

        result.setContent("ok");
        return Uni.createFrom().item(Response.ok(result).build());
    }
}

我尝试通过两种方式运行该应用：

• 在Intelij Idea中直接运行，或构建后运行quarkus-run.jar（JVM模式）
• 运行二进制可执行文件xxx-SNAPSHOT-runner，或构建镜像在docker/k8s中运行（Native模式）

第一种方式下，可得到包含内容的正确响应{xx:xx,xx:xx}；但第二种方式下，仅能得到空响应{}。

环境信息 #

• Quarkus版本：2.12.3.Final
• quarkus-resteasy-reactive-jackson版本：2.12.3.Final
• GraalVM版本：22.1.0-java11
• 系统：MacOS x86 64

我尝试将返回类型Uni<Response>替换为普通类型后，两种模式表现一致。因此想了解Native特性为何会导致Uni响应丢失？

核心原因：GraalVM Native镜像的反射元数据缺失 #

Quarkus Native模式依赖GraalVM将Java代码编译为原生二进制文件，这个过程会做激进的静态分析和死代码消除。Jackson序列化JSON时依赖反射识别DTO类的字段、getter/setter方法，但GraalVM默认不会主动将这些反射信息纳入原生镜像，除非明确配置。

当返回Uni<Response>时，Response是通用容器，构建期无法确定其内部包裹的具体DTO类型，导致GraalVM未生成对应反射元数据，Jackson在Native运行时无法访问DTO字段，最终序列化出空对象{}；而返回普通业务类型时，Quarkus的Reactive Jackson扩展能在构建期分析到返回类型，自动生成反射元数据，因此序列化正常。

具体解决方案 #

1. 给DTO添加反射注册注解
   在DatasourceRecordDTO和DatasourceRecordItem类上添加@RegisterForReflection注解，告知GraalVM将这些类纳入反射元数据范围：

   import io.quarkus.runtime.annotations.RegisterForReflection;
   
   @RegisterForReflection
   public class DatasourceRecordDTO {
       private String id;
       private List<String> header;
       private List<DatasourceRecordItem> rows;
       private String content;
       // getter/setter方法
   }
   
   @RegisterForReflection
   public class DatasourceRecordItem {
       private String key;
       private List<String> valueList;
       // getter/setter方法
   }
   

2. 显式标记Jackson序列化字段
   给DTO的字段添加@JsonProperty注解，强制Jackson识别需要序列化的字段：

   import com.fasterxml.jackson.annotation.JsonProperty;
   
   public class DatasourceRecordDTO {
       @JsonProperty
       private String id;
       @JsonProperty
       private List<String> header;
       @JsonProperty
       private List<DatasourceRecordItem> rows;
       @JsonProperty
       private String content;
       // getter/setter方法
   }
   

3. 调整返回类型（简化方案）
   将返回类型改为Uni<DatasourceRecordDTO>，让Quarkus在构建期直接识别到要序列化的业务类型，自动生成反射元数据：

   @POST
   @Path("/query")
   public Uni<DatasourceRecordDTO> query(DatasourceQuery param) {
       // 原构建result逻辑不变
       return Uni.createFrom().item(result);
   }
   

内容的提问来源于stack exchange，提问作者cfireworks