Spring Boot使用Undertow服务器时如何支持异步请求，相关报错如何解决

错误根因 #

抛出UT010026异常的核心原因是Undertow对异步请求的校验规则比Tomcat更严格，要求请求处理全链路中涉及的所有Servlet、Filter组件都必须显式开启异步支持，只要存在任意一个组件未声明异步支持，就会禁止当前请求进入异步模式。
错误完整信息如下：

WARN 8252 --- [ XNIO-1 task-3] o.g.j.servlet.internal.ResponseWriter: Attempt to put servlet request into asynchronous mode has failed. Please check your servlet configuration - all Servlet instances and Servlet filters involved in the request processing must explicitly declare support for asynchronous request processing
java.lang.IllegalStateException: UT010026: Async is not supported for this request, as not all filters or Servlets were marked as supporting async
at io.undertow.servlet.spec.HttpServletRequestImpl.startAsync(HttpServletRequestImpl.java:1073)

配置步骤 #

1. 基础全局配置 #

在项目配置文件中添加全局异步支持配置：

• 若使用application.yml：

spring:
  mvc:
    async:
      supported: true
  # 项目集成Jersey需额外添加以下配置
  jersey:
    servlet:
      async-supported: true

• 若使用application.properties：

spring.mvc.async.supported=true
# 项目集成Jersey需额外添加以下配置
spring.jersey.servlet.async-supported=true

2. 自定义组件开启异步支持 #

如果项目中存在自定义的Filter、Servlet组件，需要单独配置异步支持属性：

• 基于注解注册的组件：

// 自定义Filter配置
@WebFilter(filterName = "customFilter", urlPatterns = "/*", asyncSupported = true)
public class CustomFilter implements Filter {
    // 过滤器业务逻辑
}

// 自定义Servlet配置
@WebServlet(urlPatterns = "/custom/*", asyncSupported = true)
public class CustomServlet extends HttpServlet {
    // Servlet业务逻辑
}

• 基于RegistrationBean手动注册的组件：

@Bean
public FilterRegistrationBean<CustomFilter> customFilterRegistration() {
    FilterRegistrationBean<CustomFilter> registration = new FilterRegistrationBean<>();
    registration.setFilter(new CustomFilter());
    registration.addUrlPatterns("/*");
    registration.setAsyncSupported(true); // 必须添加该配置
    return registration;
}

3. 第三方组件适配 #

如果引入的第三方Starter自带的Filter未开启异步支持，可通过以下方式强制修改配置：

@Autowired
public void setThirdPartyFilterAsyncSupport(FilterRegistrationBean<ThirdPartyFilter> registration) {
    registration.setAsyncSupported(true);
}

4. Undertow专属强制配置（特殊场景备用） #

如果以上配置都添加后仍报错，可手动定制Undertow服务器属性，强制全局开启异步支持：

@Bean
public UndertowServletWebServerFactory undertowServletWebServerFactory() {
    UndertowServletWebServerFactory factory = new UndertowServletWebServerFactory();
    factory.addDeploymentInfoCustomizers(deploymentInfo -> {
        deploymentInfo.setAsyncSupported(true);
        deploymentInfo.setAllowNonStandardWrappers(true);
    });
    return factory;
}

所有配置完成后重启服务即可正常处理异步请求。

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