JBoss(Wildfly)中Spring SOAP接口超大请求异常处理方案咨询

解决JBoss/Wildfly中SOAP端点请求过大的友好异常处理问题 #

在处理SOAP接口的超大请求时，你会发现和REST接口的异常处理逻辑不一样——因为当请求大小超过max-post-size时，Wildfly的Undertow容器会先于你的SOAP端点代码拦截这个请求，直接返回默认的HTML错误页面，导致你的@Endpoint和Spring MVC的@ControllerAdvice都没机会介入。下面分两种核心方案来解决这个问题：

方案一：自定义Undertow容器的413错误响应（推荐，覆盖所有SOAP请求场景）

这个方案直接在容器层面拦截413（Payload Too Large）状态码，返回符合SOAP规范的错误响应，不需要修改业务代码。

1. 修改standalone.xml配置错误页面映射
   在undertow子系统的default-virtual-host下添加413错误页的映射，指向一个自定义的处理路径：

<subsystem xmlns="urn:jboss:domain:undertow:12.0" ...>
    <default-server name="default-server">
        <default-virtual-host name="default-host" enable-welcome-root="false">
            <!-- 保留现有配置 -->
            <error-page status-code="413">
                <location path="/soap-413-handler"/>
            </error-page>
        </default-virtual-host>
    </default-server>
</subsystem>

2. 创建Spring控制器返回SOAP Fault
   编写一个简单的@Controller来处理/soap-413-handler路径，生成标准的SOAP错误响应：

@Controller
public class SoapErrorHandlerController {

    @RequestMapping(value = "/soap-413-handler", produces = MediaType.TEXT_XML_VALUE)
    public ResponseEntity<String> handlePayloadTooLarge() {
        // 构造符合SOAP 1.1规范的Fault响应
        String soapFault = """
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
                <soapenv:Body>
                    <soapenv:Fault>
                        <faultcode>soapenv:Client</faultcode>
                        <faultstring>请求大小超过限制，最大允许50MB</faultstring>
                        <detail>
                            <error>当前请求超出了服务器配置的50MB上限，请压缩或拆分请求后重试</error>
                        </detail>
                    </soapenv:Fault>
                </soapenv:Body>
            </soapenv:Envelope>
            """;

        return ResponseEntity.status(HttpStatus.PAYLOAD_TOO_LARGE)
                .contentType(MediaType.TEXT_XML)
                .body(soapFault);
    }
}

这样，所有触发413的SOAP请求都会得到标准的XML错误响应，而不是默认的HTML页面。

方案二：通过Spring WS全局异常处理器处理（适用于请求到达端点后的异常）

如果你的SOAP请求包含附件或者需要在应用层更精细地控制错误逻辑，可以通过Spring WS的EndpointExceptionResolver来处理，但需要先确保Spring WS的消息读取阈值和容器配置一致，避免容器先拦截请求。

1. 统一配置Spring WS和容器的最大请求大小
   在Spring的WS配置类中，调整SOAP消息工厂的最大大小（和standalone.xml中的max-post-size="50000000"保持一致）：

@Configuration
@EnableWs
public class WebServiceConfig extends WsConfigurerAdapter {

    @Bean
    public SaajSoapMessageFactory soapMessageFactory() {
        SaajSoapMessageFactory messageFactory = new SaajSoapMessageFactory();
        SOAPMessageFactory1_1Impl saajFactory = new SOAPMessageFactory1_1Impl();
        // 设置最大附件大小（如果是带附件的SOAP请求）
        saajFactory.setMaxAttachmentSize(50000000);
        messageFactory.setMessageFactory(saajFactory);
        return messageFactory;
    }

    // 其他WS配置（比如WSDL定义等）...
}

2. 实现EndpointExceptionResolver捕获异常
   创建一个全局异常处理器，捕获请求大小超限相关的异常并返回SOAP Fault：

@Component
public class SoapGlobalExceptionResolver implements EndpointExceptionResolver {

    @Override
    public boolean resolveException(MessageContext messageContext, Object endpoint, Exception ex) {
        // 处理Spring或容器抛出的大小超限异常
        if (ex instanceof MaxUploadSizeExceededException 
            || ex.getCause() instanceof io.undertow.server.handlers.form.MaxEntitySizeExceededException) {
            
            SoapMessage response = (SoapMessage) messageContext.getResponse();
            SoapBody soapBody = response.getSoapBody();
            
            // 添加客户端Fault（符合SOAP规范）
            SoapFault fault = soapBody.addClientOrSenderFault(
                "请求大小超过50MB限制", 
                Locale.CHINESE
            );
            // 添加详细错误信息
            fault.addFaultDetail().addText("请检查请求内容大小后重试");
            
            return true; // 标记异常已处理
        }
        // 其他异常交给默认处理
        return false;
    }
}

这个方案适用于请求已经到达Spring WS端点处理阶段的场景，比如附件大小超限等情况。

注意事项

• 确保standalone.xml中的max-post-size和Spring WS配置的阈值一致，避免容器和应用层的拦截逻辑冲突。
• SOAP Fault的格式要严格符合你使用的SOAP版本（1.1或1.2），确保客户端能正确解析。

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