Quarkus中返回Uni<Response>时File与AsyncFile的差异及选型

两个接口差异的原因 #

download1 高速传输的核心逻辑 #

当你用Response.ok(file)返回File对象时，Quarkus底层的JAX-RS实现（RESTEasy Reactive）会自动采用操作系统级别的零拷贝机制（sendfile）。这种方式直接让内核从磁盘读取数据并发送到网卡，完全跳过用户态的JVM内存拷贝，所以磁盘使用率高、下载速度快。同时，框架会自动获取文件大小并设置Content-Length响应头，浏览器能直接显示下载进度。

虽然你把返回值包装在了Uni中，但框架对File类型的响应实体做了专门优化：文件传输的阻塞I/O操作会被调度到Quarkus的I/O工作线程池，不会阻塞Vert.x的事件循环线程，完全符合非阻塞的要求，且不会把整个文件加载到内存。

download2 低速分块的问题所在 #

你用Vert.x AsyncFile作为响应实体时，框架无法识别并利用零拷贝机制，只能把它当作普通的异步输入流来处理：

• 无零拷贝支持：数据需要从内核态拷贝到JVM内存，再从JVM内存拷贝到网卡，额外的拷贝开销导致传输速度骤降。
• 分块传输的原因：你手动设置了X-File-Size但没有设置Content-Length，框架无法提前获知总文件大小，只能采用分块传输（Chunked Transfer Encoding），浏览器无法显示准确的下载进度。
• 不必要的阻塞操作：asyncFile.sizeBlocking()是同步阻塞调用，打破了Vert.x的异步流程，进一步影响性能。
• 默认缓冲区限制：AsyncFile的默认读取缓冲区较小，逐块读取的方式进一步限制了传输速率。

方案优劣对比 #

• download1 是更优的选择：
  • 利用零拷贝，传输效率接近硬件上限；
  • 自动设置Content-Length，浏览器体验更好；
  • 框架自动处理线程调度，无需手动管理异步流程；
  • 完全满足“不加载整个文件到内存”的需求。
• download2 不推荐使用：
  • 传输速度慢，资源利用率低；
  • 分块传输导致浏览器无法显示准确进度；
  • 代码复杂度更高，且存在不必要的阻塞操作。

第三种方案：虚拟线程（@RunOnVirtualThread） #

用@RunOnVirtualThread注解并直接返回Response而非Uni<Response>，是另一种优秀的选择：

@GET
@Path("/download3/{fileId}")
@Produces(MediaType.APPLICATION_OCTET_STREAM)
@RunOnVirtualThread
public Response download3(@RestPath String fileId) {
    File file = Paths.get(archivePath, fileId).toFile();
    if (file.exists()) {
        return Response.ok(file, MediaType.APPLICATION_OCTET_STREAM)
                .header("Content-Disposition", "attachment; filename=\"" + file.getName() + "\"")
                .build();
    } else {
        return Response.status(Response.Status.NOT_FOUND).entity("File not found").build();
    }
}

这种方案的优势：

• 代码写法更简洁直观，无需手动包装Uni；
• 虚拟线程会自动处理阻塞I/O操作，不会占用大量操作系统线程，资源利用率高；
• 同样能利用零拷贝机制，传输速度和download1一致；
• 完全符合Quarkus 3.x+对虚拟线程的优化支持，是阻塞I/O场景下的推荐写法。

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