异步请求 (Asynchronous Requests) _ Spring Framework 6.0.23-SNAPSHOT 中文文档(官方文档中文翻译) —

此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Framework 6.1.10！Spring中文文档

Spring MVC 与 Servlet 异步请求处理进行了广泛的集成：Spring中文文档

控制器方法中的 DeferredResult 和 Callable 返回值为单个异步提供基本支持返回值。Spring中文文档
控制器可以流式传输多个值，包括 SSE 和原始数据。Spring中文文档
控制器可以使用反应式客户端并返回响应式类型进行响应处理。Spring中文文档

有关这与 Spring WebFlux 有何不同的概述，请参阅下面的异步 Spring MVC 与 WebFlux 的比较部分。Spring中文文档

`DeferredResult`

在 Servlet 容器中启用异步请求处理功能后，控制器方法可以包装任何支持的控制器方法返回的值，如以下示例所示：DeferredResultSpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

@GetMapping("/quotes")
@ResponseBody
public DeferredResult<String> quotes() {
	DeferredResult<String> deferredResult = new DeferredResult<>();
	// Save the deferredResult somewhere..
	return deferredResult;
}

// From some other thread...
deferredResult.setResult(result);

@GetMapping("/quotes")
@ResponseBody
fun quotes(): DeferredResult<String> {
	val deferredResult = DeferredResult<String>()
	// Save the deferredResult somewhere..
	return deferredResult
}

// From some other thread...
deferredResult.setResult(result)

控制器可以从不同的线程异步生成返回值 — for 例如，响应外部事件（JMS 消息）、计划任务或其他事件。Spring中文文档

`Callable`

控制器可以用包装任何支持的返回值如以下示例所示：java.util.concurrent.CallableSpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

@PostMapping
public Callable<String> processUpload(final MultipartFile file) {
	return () -> "someView";
}

@PostMapping
fun processUpload(file: MultipartFile) = Callable<String> {
	// ...
	"someView"
}

然后，可以通过通过配置的 .TaskExecutorSpring中文文档

加工

以下是 Servlet 异步请求处理的非常简洁的概述：Spring中文文档

可以通过调用来将 A 置于异步模式。这样做的主要效果是 Servlet（以及任何过滤器）可以退出，但响应将保持打开状态，以便稍后完成处理。ServletRequestrequest.startAsync()Spring中文文档
对的调用返回，可用于进一步控制异步处理。例如，它提供了方法，它类似于 Servlet API 的转发，只是它允许在 Servlet 容器线程上处理应用程序恢复请求。request.startAsync()AsyncContextdispatchSpring中文文档
提供对当前的访问，您可以用于区分处理初始请求、异步请求 dispatch、a forward 和其他调度程序类型。ServletRequestDispatcherTypeSpring中文文档

DeferredResult处理工作如下：Spring中文文档

控制器返回 a 并将其保存在内存中可以访问它的队列或列表。DeferredResultSpring中文文档
Spring MVC 调用 .request.startAsync()Spring中文文档
同时，所有配置的过滤器退出请求处理线程，但响应保持打开状态。DispatcherServletSpring中文文档
应用程序设置 from 某个线程和 Spring MVC 将请求调度回 Servlet 容器。DeferredResultSpring中文文档
再次调用，并使用异步生成的返回值。DispatcherServletSpring中文文档

Callable处理工作如下：Spring中文文档

控制器返回 .CallableSpring中文文档
Spring MVC 调用并提交到 a 用于在单独的线程中进行处理。request.startAsync()CallableTaskExecutorSpring中文文档
同时，和所有过滤器退出 Servlet 容器线程，但回应仍然悬而未决。DispatcherServletSpring中文文档
最终生成一个结果，Spring MVC 将请求调回到 Servlet 容器以完成处理。CallableSpring中文文档
再次调用，并使用异步生成的返回值。DispatcherServletCallableSpring中文文档

有关更多背景和上下文，您还可以阅读在 Spring MVC 3.2 中引入异步请求处理支持的博客文章。Spring中文文档

异常处理

使用时，可以选择是调用还是使用异常。在这两种情况下，Spring MVC 都会将请求调回到 Servlet 容器以完成处理。然后将其视为 controller 方法返回给定值，或者好像它产生了给定的异常。然后，异常将通过常规异常处理机制（例如，调用方法）。DeferredResultsetResultsetErrorResult@ExceptionHandlerSpring中文文档

当您使用时，会出现类似的处理逻辑，主要区别在于结果从或或引发异常。CallableCallableSpring中文文档

拦截

HandlerInterceptor实例的类型可以是，用于接收异步启动的初始请求的回调处理（而不是和）。AsyncHandlerInterceptorafterConcurrentHandlingStartedpostHandleafterCompletionSpring中文文档

HandlerInterceptor实现也可以注册 A 或 A ，以便更深入地与异步请求的生命周期（例如，处理超时事件）。有关详细信息，请参阅 AsyncHandlerInterceptor。CallableProcessingInterceptorDeferredResultProcessingInterceptorSpring中文文档

DeferredResult提供和回调。有关更多详细信息，请参阅 DeferredResult 的 javadoc。可以代替暴露额外的超时和完成回调的方法。onTimeout(Runnable)onCompletion(Runnable)CallableWebAsyncTaskSpring中文文档

异步 Spring MVC 与 WebFlux 的比较

Servlet API 最初是为通过 Filter-Servlet 进行单次传递而构建的链。异步请求处理允许应用程序退出 Filter-Servlet 链但请保留响应以供进一步处理。Spring MVC 异步支持是围绕该机制构建的。当控制器返回时，退出 Filter-Servlet 链，并释放 Servlet 容器线程。后来，当设置，进行调度（到同一 URL），在此期间控制器再次映射，但不是调用它，而是使用该值（就好像控制器返回了它一样）以恢复处理。DeferredResultDeferredResultASYNCDeferredResultSpring中文文档

相比之下，Spring WebFlux 既不是基于 Servlet API 构建的，也不需要这样的异步请求处理功能，因为它在设计上是异步的。异步处理内置于所有框架合同中，并通过所有框架合同获得内在支持请求处理的阶段。Spring中文文档

从编程模型的角度来看，Spring MVC 和 Spring WebFlux 都支持 asynchronous 和 Reactive Types 作为控制器方法中的返回值。 Spring MVC 甚至支持流式处理，包括无功背压。但是，个人与 WebFlux 不同，对响应的写入仍然阻塞（并在单独的线程上执行），它依赖于非阻塞 I/O，并且每次写入都不需要额外的线程。Spring中文文档

另一个根本区别是 Spring MVC 不支持异步或反应式控制器方法参数中的类型（例如、、等），它也没有明确支持异步和反应式类型作为模型属性。 Spring WebFlux 确实支持所有这些。@RequestBody@RequestPartSpring中文文档

最后，从配置的角度来看，必须在 Servlet 容器级别启用异步请求处理功能。Spring中文文档

HTTP 流

请参阅 Reactive 堆栈中的等效项Spring中文文档

可以将和用于单个异步返回值。如果要生成多个异步值并将这些值写入响应？本节介绍如何执行此操作。DeferredResultCallableSpring中文文档

对象

您可以使用返回值生成对象流，其中每个对象都使用 HttpMessageConverter 序列化，并写入响应，如以下示例所示：ResponseBodyEmitterSpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

@GetMapping("/events")
public ResponseBodyEmitter handle() {
	ResponseBodyEmitter emitter = new ResponseBodyEmitter();
	// Save the emitter somewhere..
	return emitter;
}

// In some other thread
emitter.send("Hello once");

// and again later on
emitter.send("Hello again");

// and done at some point
emitter.complete();

@GetMapping("/events")
fun handle() = ResponseBodyEmitter().apply {
	// Save the emitter somewhere..
}

// In some other thread
emitter.send("Hello once")

// and again later on
emitter.send("Hello again")

// and done at some point
emitter.complete()

你也可以用作身体在一个，让你自定义响应的状态和标头。ResponseBodyEmitterResponseEntitySpring中文文档

当 an 抛出（例如，如果远程客户端消失），应用程序不负责清理连接，也不应调用或。相反，servlet 容器会自动启动错误通知，Spring MVC 会在其中进行调用。反过来，此调用会对应用程序执行最后一次调度，在此期间，Spring MVC 调用配置的异常解析程序并完成请求。emitterIOExceptionemitter.completeemitter.completeWithErrorAsyncListenercompleteWithErrorASYNCSpring中文文档

上交所

SseEmitter（）的子类提供对服务器发送事件的支持，其中从服务器发送的事件根据 W3C SSE 规范进行格式化。生成 SSE 从控制器流，返回，如以下示例所示：ResponseBodyEmitterSseEmitterSpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

@GetMapping(path="/events", produces=MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter handle() {
	SseEmitter emitter = new SseEmitter();
	// Save the emitter somewhere..
	return emitter;
}

// In some other thread
emitter.send("Hello once");

// and again later on
emitter.send("Hello again");

// and done at some point
emitter.complete();

@GetMapping("/events", produces = [MediaType.TEXT_EVENT_STREAM_VALUE])
fun handle() = SseEmitter().apply {
	// Save the emitter somewhere..
}

// In some other thread
emitter.send("Hello once")

// and again later on
emitter.send("Hello again")

// and done at some point
emitter.complete()

虽然 SSE 是流式传输到浏览器的主要选项，但请注意 Internet Explorer 不支持服务器发送的事件。考虑将 Spring 的 WebSocket 消息传递与 SockJS 回退传输（包括 SSE）一起使用广泛的浏览器。Spring中文文档

有关异常处理的说明，另请参阅上一节。Spring中文文档

原始数据

有时，绕过消息转换并直接流式传输到响应（例如，对于文件下载）很有用。可以使用返回值类型来执行此操作，如以下示例所示：OutputStreamStreamingResponseBodySpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

@GetMapping("/download")
public StreamingResponseBody handle() {
	return new StreamingResponseBody() {
		@Override
		public void writeTo(OutputStream outputStream) throws IOException {
			// write...
		}
	};
}

@GetMapping("/download")
fun handle() = StreamingResponseBody {
	// write...
}

你可以在 a 中使用作为身体自定义响应的状态和标头。StreamingResponseBodyResponseEntitySpring中文文档

反应类型

请参阅 Reactive 堆栈中的等效项Spring中文文档

Spring MVC 支持在控制器中使用反应式客户端库（另请阅读 WebFlux 部分中的响应式库）。这包括 from 和其他，例如 Spring Data 反应式数据存储库。在这种情况下，能够返回很方便控制器方法中的反应式类型。WebClientspring-webfluxSpring中文文档

反应式返回值的处理方式如下：Spring中文文档

适应单值 promise 类似于使用 .例子 include （Reactor）或（RxJava）。DeferredResultMonoSingleSpring中文文档
具有流媒体类型（如或）的多值流适用于，类似于使用或。示例包括（Reactor）或（RxJava）。应用程序也可以返回或 .application/x-ndjsontext/event-streamResponseBodyEmitterSseEmitterFluxObservableFlux<ServerSentEvent>Observable<ServerSentEvent>Spring中文文档
适用于具有任何其他媒体类型（如）的多值流 to，类似于使用 .application/jsonDeferredResult<List<?>>Spring中文文档

Spring MVC 通过 的 ReactiveAdapterRegistry 支持 Reactor 和 RxJava，这让它能够适应多个反应式库。spring-core

对于流式传输到响应，支持无功背压，但写入响应仍然阻塞，并且通过配置在单独的线程上运行，以避免阻塞上游源（例如从返回的）。默认情况下，用于阻塞写入，但事实并非如此适用于负载下。如果计划使用响应式流式传输，则应使用 MVC 配置来配置任务执行器。TaskExecutorFluxWebClientSimpleAsyncTaskExecutorSpring中文文档

Spring MVC 通过 的 ReactiveAdapterRegistry 支持 Reactor 和 RxJava，这让它能够适应多个反应式库。spring-core

上下文传播

通常通过传播上下文。这是透明的用于在同一线程上进行处理，但需要额外的异步处理工作跨多个线程。Micrometer Context Propagation 库简化了跨线程和跨上下文机制的上下文传播，例如作为值，反应器环境， GraphQL Java上下文，和其他人。java.lang.ThreadLocalThreadLocalSpring中文文档

如果类路径上存在 Micrometer Context Propagation，则当控制器方法返回一个反应式类型，例如或，所有值，其已注册，作为键值对写入 Reactor，使用 .FluxMonoThreadLocalio.micrometer.ThreadLocalAccessorContextThreadLocalAccessorSpring中文文档

对于其他异步处理方案，可以使用上下文传播库径直。例如：Spring中文文档

爪哇岛

// Capture ThreadLocal values from the main thread ...
ContextSnapshot snapshot = ContextSnapshot.captureAll();

// On a different thread: restore ThreadLocal values
try (ContextSnapshot.Scope scope = snapshot.setThreadLocals()) {
	// ...
}

有关详细信息，请参阅千分尺上下文的文档传播库。Spring中文文档

断开

请参阅 Reactive 堆栈中的等效项Spring中文文档

当远程客户机消失时，Servlet API 不会提供任何通知。因此，在流式传输到响应时，无论是通过 SseEmitter 还是响应式类型，定期发送数据都很重要，因为如果客户端已断开连接，则写入失败。发送可以采用以下形式：空（仅评论）SSE 事件或另一方必须解释的任何其他数据作为心跳和忽略。Spring中文文档

或者，考虑使用 Web 消息传递解决方案（例如 STOMP over WebSocket 或 WebSocket with SockJS）具有内置的心跳机制。Spring中文文档

配置

必须在 Servlet 容器级别启用异步请求处理功能。 MVC 配置还公开了异步请求的多个选项。Spring中文文档

Servlet 容器

Filter 和 Servlet 声明具有一个标志，需要将其设置为启用异步请求处理。此外，筛选器映射应为声明处理 .asyncSupportedtrueASYNCjakarta.servlet.DispatchTypeSpring中文文档

在 Java 配置中，当您用于初始化 Servlet 容器时，这是自动完成的。AbstractAnnotationConfigDispatcherServletInitializerSpring中文文档

在配置中，可以添加到 and 声明和添加到筛选器映射。web.xml<async-supported>true</async-supported>DispatcherServletFilter<dispatcher>ASYNC</dispatcher>Spring中文文档

Spring MVC

MVC 配置公开了以下与异步请求处理相关的选项：Spring中文文档

Java 配置：使用回调。configureAsyncSupportWebMvcConfigurerSpring中文文档
XML 命名空间：使用 .<async-support><mvc:annotation-driven>Spring中文文档

您可以配置以下内容：Spring中文文档

异步请求的默认超时值，如果未设置，则取决于在底层 Servlet 容器上。Spring中文文档
AsyncTaskExecutor用于在使用反应式类型进行流式传输时阻止写入，以及用于执行从控制器方法。如果您满足以下条件，我们强烈建议配置此属性流具有反应式类型或具有返回的控制器方法，因为默认情况下，它是一个 .CallableCallableSimpleAsyncTaskExecutorSpring中文文档
DeferredResultProcessingInterceptor实现和实现。CallableProcessingInterceptorSpring中文文档

请注意，您还可以在上设置默认超时值， a 和 .对于，您可以使用来提供超时值。DeferredResultResponseBodyEmitterSseEmitterCallableWebAsyncTaskSpring中文文档