正如摘要所述，本文档旨在解决在使用 Quarkus 构建 REST API 时，由于返回 Multi<String> 类型并指定 APPLICATION_JSON 媒体类型，导致响应被额外数组包装的问题。我们将探讨如何通过使用 @Stream(Stream.MODE.RAW) 注解来避免这种不必要的包装，并理解其对响应格式和数据流处理的影响。
问题描述
在使用 Quarkus 开发 REST API 时，如果使用 Multi<String> 作为返回类型，并指定 APPLICATION_JSON 作为 Produces 的媒体类型，可能会遇到一个问题：即使返回的是有效的 JSON 字符串，Quarkus 也会自动将响应包装在一个额外的数组中。例如，以下代码：
@Path("/testData")
@GET
@Produces(MediaType.APPLICATION_JSON)
public Multi<String> 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 实现）直接将每个值写入到输出流，而无需进行任何格式化。
修改后的代码如下：
@Path("/testData")
@GET
@Produces(MediaType.APPLICATION_JSON)
@Stream(Stream.MODE.RAW)
public Multi<String> 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<String> 类型并指定 APPLICATION_JSON 媒体类型时，响应被额外数组包装的问题。在使用该注解时，需要注意其对数据格式和流处理方式的影响，并根据实际情况选择合适的方案。
