如何抑制嵌入式Undertow中客户端断开时的堆栈跟踪信息？

我之前也碰到过这个糟心的情况——客户端突然断连，Undertow/XNIO就狂打一堆没用的堆栈日志，看着特别闹心。刚好你的需求和我当时的想法一致：默认屏蔽这些噪音，只有诊断模式开启时，输出简洁的异常终止提示和当前处理器信息。下面是我实践过的可行方案：

1. 自定义HttpHandler拦截业务处理中的断连异常 #

首先，我们可以在业务处理器外层包装一个自定义的HttpHandler，专门捕获客户端断连类的IOException，只在诊断模式下输出简洁日志：

import io.undertow.server.HttpHandler;
import io.undertow.server.HttpServerExchange;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.io.IOException;

public class ClientDisconnectHandler implements HttpHandler {
    private final HttpHandler nextHandler;
    private final boolean isDiagnosticMode;
    private static final Logger logger = LoggerFactory.getLogger(ClientDisconnectHandler.class);

    public ClientDisconnectHandler(HttpHandler nextHandler, boolean diagnosticMode) {
        this.nextHandler = nextHandler;
        this.isDiagnosticMode = diagnosticMode;
    }

    @Override
    public void handleRequest(HttpServerExchange exchange) throws Exception {
        try {
            // 调用下一个业务处理器
            nextHandler.handleRequest(exchange);
        } catch (IOException e) {
            // 判断是否是客户端主动断连的异常
            if (isClientDisconnectError(e)) {
                if (isDiagnosticMode) {
                    // 提取当前处理器的信息（路径+处理器类名）
                    String handlerDetails = String.format("请求路径: %s，处理器: %s",
                            exchange.getRequestPath(),
                            nextHandler.getClass().getSimpleName());
                    logger.info("客户端连接异常终止 | {}", handlerDetails);
                }
                // 消费异常，不再向上抛出，避免默认堆栈输出
                return;
            }
            // 非断连异常，正常抛出交给后续处理
            throw e;
        }
    }

    private boolean isClientDisconnectError(IOException e) {
        // 匹配常见的客户端断连异常消息，不同操作系统可能略有差异
        String errorMsg = e.getMessage();
        return errorMsg != null && (
                errorMsg.contains("Connection reset by peer") ||
                errorMsg.contains("Broken pipe") ||
                errorMsg.contains("Connection aborted") ||
                errorMsg.contains("Client closed connection")
        );
    }
}

然后在启动Undertow时，把这个handler加到处理器链的最前面：

// 假设你的业务处理器是yourBusinessHandler
HttpHandler wrappedHandler = new ClientDisconnectHandler(yourBusinessHandler, isDiagnosticModeEnabled());

Undertow server = Undertow.builder()
        .addHttpListener(8080, "0.0.0.0")
        .setHandler(wrappedHandler)
        .build();
server.start();

2. 拦截XNIO底层的断连异常 #

有些客户端断连异常会直接在XNIO的IO线程中抛出，不会传到HttpHandler层面，这时候我们需要自定义XNIO的异常处理器：

import org.xnio.ChannelExceptionHandler;
import org.xnio.OptionMap;
import org.xnio.Options;
import org.xnio.Xnio;
import org.xnio.XnioWorker;
import io.undertow.server.HttpServerExchange;
import java.io.IOException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class XnioDisconnectExceptionHandler implements ChannelExceptionHandler<Object> {
    private static final Logger logger = LoggerFactory.getLogger(XnioDisconnectExceptionHandler.class);
    private final boolean isDiagnosticMode;

    public XnioDisconnectExceptionHandler(boolean diagnosticMode) {
        this.isDiagnosticMode = diagnosticMode;
    }

    @Override
    public void handleException(Object channel, Throwable exception) {
        if (exception instanceof IOException && isClientDisconnectError((IOException) exception)) {
            if (isDiagnosticMode) {
                // 尝试从通道中获取关联的HttpServerExchange，提取处理器信息
                String handlerDetails = "未知处理器";
                if (channel instanceof org.xnio.channels.StreamChannel) {
                    HttpServerExchange exchange = ((org.xnio.channels.StreamChannel) channel)
                            .getAttribute(HttpServerExchange.class);
                    if (exchange != null) {
                        handlerDetails = String.format("请求路径: %s，处理器: %s",
                                exchange.getRequestPath(),
                                exchange.getHandler().getClass().getSimpleName());
                    }
                }
                logger.info("XNIO层面连接异常终止 | {}", handlerDetails);
            }
            // 消费异常，阻止默认堆栈输出
            return;
        }
        // 其他异常交给XNIO默认处理器处理
        Xnio.DEFAULT_EXCEPTION_HANDLER.handleException(channel, exception);
    }

    private boolean isClientDisconnectError(IOException e) {
        // 和上面的判断逻辑一致
        String errorMsg = e.getMessage();
        return errorMsg != null && (
                errorMsg.contains("Connection reset by peer") ||
                errorMsg.contains("Broken pipe") ||
                errorMsg.contains("Connection aborted") ||
                errorMsg.contains("Client closed connection")
        );
    }
}

然后创建自定义的XNIO Worker并设置这个异常处理器：

// 创建自定义XNIO Worker
XnioWorker customWorker = Xnio.getInstance().createWorker(OptionMap.builder()
        .set(Options.WORKER_IO_THREADS, 4) // 根据你的需求调整线程数
        .set(Options.WORKER_TASK_THREADS, 8)
        .getMap());

// 设置自定义异常处理器
customWorker.setExceptionHandler(new XnioDisconnectExceptionHandler(isDiagnosticModeEnabled()));

// 启动Undertow时使用这个Worker
Undertow server = Undertow.builder()
        .setWorker(customWorker)
        .addHttpListener(8080, "0.0.0.0")
        .setHandler(yourBusinessHandler)
        .build();
server.start();

3. 配合日志框架控制输出级别 #

最后，你可以通过日志框架（比如Logback/Log4j2）来进一步控制日志输出，确保默认情况下Undertow/XNIO的日志级别是WARN或更高级别，只有诊断模式开启时才调整为INFO：

以Logback为例，在logback.xml中添加：

<configuration>
    <!-- 默认配置：屏蔽Undertow/XNIO的DEBUG/INFO级别的噪音日志 -->
    <logger name="io.undertow" level="WARN" />
    <logger name="org.xnio" level="WARN" />
    
    <!-- 诊断模式开启时，打开我们自定义handler的INFO日志 -->
    <if condition='property("diagnostic.mode").equals("true")'>
        <then>
            <logger name="your.package.ClientDisconnectHandler" level="INFO" />
            <logger name="your.package.XnioDisconnectExceptionHandler" level="INFO" />
        </then>
    </if>

    <!-- 其他日志配置... -->
</configuration>

启动应用时，通过系统参数开启诊断模式：java -Ddiagnostic.mode=true -jar your-app.jar

这样一来，默认情况下客户端断连不会输出任何冗余堆栈，只有开启诊断模式时，才会输出一行清晰的提示信息，包含异常情况和当前处理器的详细内容。

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