Quarkus REST API 返回简洁 JSON 方法

正如摘要中所述，本文将探讨如何在使用 Quarkus 构建 REST API 时，避免返回 JSON 数据时出现额外的数组包装。当使用 Multi 作为返回类型，并指定 MediaType.APPLICATION_JSON 时，Quarkus 默认会将所有结果收集到一个列表中，然后将该列表作为 JSON 数组返回。这可能不是我们期望的行为，特别是当我们需要返回一个单独的 JSON 对象时。

问题描述

在 Quarkus REST API 中，如果使用 Multi 来返回 JSON 数据，可能会遇到响应被额外的数组包装的情况。例如，以下代码：

  @Path("/testData")
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  public Multi  test() throws IOException {
      return Multi.createFrom().items(IOUtils.toString(getClass().getResourceAsStream("/TestJSON.json"), StandardCharsets.UTF_8));
  }

假设 TestJSON.json 文件的内容如下：

{
  "isA": "customerDocument",
  "createdOn": "2022-10-10T12:29:43",
  "customerBody": {
    "customerList": [
      {
        "name": "Batman",
        "age": 45,
        "city": "gotham"
      }
    ]
  }
}

实际的响应结果会变成：

[
  {
    "isA": "customerDocument",
    "createdOn": "2022-10-10T12:29:43",
    "customerBody": {
      "customerList": [
        {
          "name": "Batman",
          "age": 45,
          "city": "gotham"
        }
      }
    }
  }
]

可以看到，原始的 JSON 对象被一个额外的数组包装。

解决方案

为了避免这种额外的数组包装，可以使用 @Stream(Stream.MODE.RAW) 注解。此注解指示 Resteasy 直接将每个值写入响应，而无需进行任何格式化。

  @Path("/testData")
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  @Stream(Stream.MODE.RAW)
  public Multi  test() throws IOException {
      return Multi.createFrom().items(IOUtils.toString(getClass().getResourceAsStream("/TestJSON.json"), StandardCharsets.UTF_8));
  }

通过添加 @Stream(Stream.MODE.RAW) 注解，Resteasy 将不会收集所有值并将它们包装到列表中。而是将每个字符串直接写入响应流，从而避免了额外的数组包装。

原理解析

根据 Resteasy 的文档，如果没有 @Stream 注解，Resteasy 会收集 Multi 中的所有值，然后将它们包装到一个 java.util.List 实体中，并将其发送到客户端。而使用 @Stream(Stream.MODE.RAW) 注解后，每个值都会在可用时直接写入网络，无需任何格式化。

注意事项

使用 @Stream(Stream.MODE.RAW) 注解不仅会改变响应的格式，还会影响 "reactivity"，即是否等待整个 Multi 完成生成值后再批量发送，还是逐个发送。这可能是一个重要的考虑因素，具体取决于应用程序的需求。

如果需要返回一个单独的 JSON 对象，并且不需要流式处理的特性，那么最好避免使用 Multi 作为返回类型。可以考虑直接返回一个 JSON 对象，例如使用 javax.json.JsonObject 或者自定义的 Java Bean。

总结

通过使用 @Stream(Stream.MODE.RAW) 注解，可以有效避免在使用 Quarkus 构建 REST API 时，Multi 返回类型导致的额外数组包装问题。这种方法提供了更灵活的流式响应处理，但也需要根据实际需求仔细考虑其影响。在选择返回类型时，应权衡流式处理的优势与直接返回 JSON 对象的简洁性。