Java 中的 ResponseBodyEmitter：详解与实战

前言

在开发高并发应用或处理长时间任务时，服务端需要向客户端实时推送数据，而不是一次性将所有结果返回。Spring 提供了一种优雅的解决方案：ResponseBodyEmitter。它适用于需要逐步发送响应数据的场景，比如进度条更新、实时日志输出、消息流等。本文将深入讲解 ResponseBodyEmitter 的核心概念、使用场景、完整示例以及注意事项，帮助初学者快速掌握其使用方法。

什么是 ResponseBodyEmitter？

ResponseBodyEmitter 是 Spring MVC 提供的一个类，用于实现服务端向客户端分块推送响应数据。它是异步非阻塞的，可以在响应未完成时多次向客户端发送部分数据，而无需等待任务完成。

特性

异步非阻塞：支持异步任务，可以有效提高服务端吞吐量。
实时性：能够逐步将数据推送给客户端，适用于实时数据更新场景。
兼容性：基于标准的 HTTP 协议，客户端无需特殊支持。

ResponseBodyEmitter 的基本用法

核心方法

send(Object data)：向客户端发送数据，可以多次调用。
complete()：结束响应流，表示数据发送完毕。
onTimeout(Runnable callback)：设置超时回调函数。
onCompletion(Runnable callback)：设置完成回调函数。

典型使用场景

实时日志输出：将长时间运行任务的日志实时返回给客户端。
进度条更新：在任务执行过程中动态更新任务进度。
数据流式加载：用于大数据分片加载，比如分页查询实时返回结果。

实战：实现一个实时推送的示例

下面我们通过一个完整的例子，演示如何使用 ResponseBodyEmitter 实现任务进度实时推送功能。

示例代码

1. 创建 Controller

@RestController
@RequestMapping("/api/progress")
public class ProgressController {@GetMapping("/start")public ResponseBodyEmitter startTask() {// 创建一个 ResponseBodyEmitter 实例ResponseBodyEmitter emitter = new ResponseBodyEmitter();// 模拟一个耗时任务new Thread(() -> {try {for (int i = 1; i <= 100; i += 10) {// 向客户端发送进度emitter.send("Progress: " + i + "%\n");Thread.sleep(1000); // 模拟任务耗时}emitter.complete(); // 任务完成，关闭连接} catch (Exception e) {emitter.completeWithError(e); // 出现异常时通知客户端}}).start();return emitter; // 返回 Emitter}
}

2. 测试接口

可以使用 Postman、浏览器或客户端代码调用接口：
URL: http://localhost:8080/api/progress/start

客户端会逐步接收到如下响应：

Progress: 10%
Progress: 20%
Progress: 30%
...
Progress: 100%

深入分析

ResponseBodyEmitter 工作原理

服务端异步生成响应数据：任务执行时，调用 send() 方法将数据推送至客户端。
分块传输：数据以 HTTP 的**分块编码（Chunked Encoding）**方式传输，不会提前设置 Content-Length，而是分段发送数据块。
连接生命周期：通过 complete() 或 completeWithError() 控制连接的关闭。

重要注意事项

支持的客户端：大多数浏览器和 HTTP 客户端库支持分块传输，但某些老旧的客户端可能不支持。
超时设置：为了避免长连接占用资源，可以为 ResponseBodyEmitter 设置超时时间：
```
emitter.onTimeout(() -> emitter.complete());
```
线程安全：ResponseBodyEmitter 的 send() 方法是线程安全的，但需要注意控制任务线程的生命周期。
连接关闭：需要确保任务结束时调用 complete() 或 completeWithError()，否则可能导致资源泄露。