Quarkus REST API 返回 JSON 时避免额外的数组包装

正如摘要所述，本文档旨在解决在使用 Quarkus 构建 REST API 时，由于返回 Multi 类型并指定 APPLICATION_JSON 媒体类型，导致响应被额外数组包装的问题。我们将探讨如何通过使用 @Stream(Stream.MODE.RAW) 注解来避免这种不必要的包装，并理解其对响应格式和数据流处理的影响。

问题描述

在使用 Quarkus 开发 REST API 时，如果使用 Multi 作为返回类型，并指定 APPLICATION_JSON 作为 Produces 的媒体类型，可能会遇到一个问题：即使返回的是有效的 JSON 字符串，Quarkus 也会自动将响应包装在一个额外的数组中。例如，以下代码：

@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 文件包含以下 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) 注解。将该注解添加到 REST API 方法上，可以指示 Resteasy（Quarkus 使用的 REST 实现）直接将每个值写入到输出流，而无需进行任何格式化。

修改后的代码如下：

adobe.podcast

Adobe旗下的AI音频录制和编辑工具，一个为有故事的人提供的音频工具

下载

@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) 注解后，返回的响应将不再包含额外的数组包装，而是直接返回 /TestJSON.json 文件中的 JSON 内容。

原理解释

根据 Resteasy 的文档，当 REST API 方法没有使用 @Stream 注解时，Resteasy 会收集 Multi 发出的所有值，然后将它们包装到一个 java.util.List 实体中，并将其发送给客户端。这就是为什么响应会被额外的数组包装的原因。

@Stream(Stream.MODE.RAW) 注解改变了这种行为。它指示 Resteasy 直接将每个值写入到输出流，而无需等待 Multi 完成。这不仅避免了额外的数组包装，还可能影响数据的流处理方式。

注意事项

使用 @Stream(Stream.MODE.RAW) 注解时，需要注意以下几点：

• 数据格式: 确保 Multi 发出的每个值都是有效的 JSON 字符串，因为 Resteasy 不会进行任何格式化。
• 流处理: @Stream(Stream.MODE.RAW) 注解会改变数据的流处理方式。如果没有该注解，Resteasy 会等待 Multi 完成，然后一次性发送所有数据。使用该注解后，Resteasy 会立即发送每个值。这可能会影响性能，具体取决于数据的生成速度和网络带宽。
• 适用场景: @Stream(Stream.MODE.RAW) 注解最适合用于处理可以被分割成小块的数据，例如字符串、字节或缓冲区。

总结

通过使用 @Stream(Stream.MODE.RAW) 注解，可以有效地解决 Quarkus REST API 返回 Multi 类型并指定 APPLICATION_JSON 媒体类型时，响应被额外数组包装的问题。在使用该注解时，需要注意其对数据格式和流处理方式的影响，并根据实际情况选择合适的方案。