Spring Boot 控制台为何不打印异常堆栈信息？

Question

Spring Boot 控制台不打印异常堆栈信息，常见于以下几种情况：一是全局异常处理器（如 `@ControllerAdvice` + `@ExceptionHandler`）捕获异常后未显式记录日志（如遗漏 `log.error("业务异常", e)`），导致堆栈被吞没；二是配置了 `server.error.include-stacktrace=never`（默认为 `on_param`），在非调试模式下主动屏蔽堆栈；三是自定义 `ErrorController` 或 `BasicErrorController` 时未调用 `getErrorAttributes()` 的 `includeStackTrace` 参数；四是日志框架（如 Logback）的 root logger 级别设为 `WARN` 或更高，而异常仅以 `ERROR` 级别输出但被过滤；五是异步线程（如 `@Async`、线程池）中抛出异常未被捕获或未配置 `AsyncUncaughtExceptionHandler`。排查时建议检查 `application.properties` 中错误配置、全局异常处理逻辑完整性及日志级别设置，必要时启用 `debug=true` 快速定位。

Answer 1

```html

一、现象定位：控制台“静默崩溃”——异常堆栈消失的表层信号

Spring Boot 应用在发生未预期异常时，控制台仅输出简短错误码（如 500 Internal Server Error）或空响应，却无任何堆栈跟踪（java.lang.NullPointerException: ... at com.example...）。此现象并非“无异常”，而是堆栈被系统性拦截、过滤或丢弃。对5年+开发者而言，这常是线上问题排查的第一道迷雾——表面平静，底层已崩。

二、配置层排查：server.error.* 的隐式开关

Spring Boot 内置错误处理机制受 application.properties 严格管控：

配置项	默认值	影响范围	风险说明
server.error.include-stacktrace	on_param	HTTP 响应体是否含堆栈（需显式传 ?trace=true）	设为 never 后，即使日志级别足够，控制台/HTTP响应均不显示堆栈
server.error.whitelabel.enabled	true	是否启用默认白页	禁用后若未配自定义 ErrorController，可能返回空白 404/500

三、逻辑层吞噬：全局异常处理器的“温柔陷阱”

使用 @ControllerAdvice + @ExceptionHandler 是最佳实践，但极易因疏忽导致堆栈丢失：

@ExceptionHandler(BusinessException.class)
public ResponseEntity<String> handleBusinessException(BusinessException e) {
    // ❌ 危险！仅返回消息，未记录堆栈
    return ResponseEntity.badRequest().body("业务失败：" + e.getMessage());
}

✅ 正确写法必须显式调用日志框架的带异常参数方法：

log.error("业务异常触发降级", e); // ✅ 第二个参数 e 是关键！

四、扩展层失联：自定义 ErrorController 的参数盲区

当继承 BasicErrorController 或实现 ErrorController 时，若忽略 includeStackTrace 参数，将彻底切断堆栈注入链：

@Override
public ModelAndView errorHtml(HttpServletRequest request, HttpServletResponse response) {
    // ❌ 错误：getErrorAttributes() 默认不包含堆栈
    Map<String, Object> errorAttributes = getErrorAttributes(
        new ServletWebRequest(request), ErrorAttributeOptions.defaults()
    );
    // ✅ 正确：显式开启
    Map<String, Object> attrs = getErrorAttributes(
        new ServletWebRequest(request), 
        ErrorAttributeOptions.of(ErrorAttributeOptions.Include.STACK_TRACE)
    );
}

五、日志层过滤：Logback/Log4j2 的“静音墙”

即使异常被正确抛出并捕获，若日志框架 root logger 级别设为 WARN，则 log.error(...) 调用仍会被丢弃：

<root level="WARN">
    <appender-ref ref="CONSOLE"/>
</root>

✅ 解决方案：将 root level 设为 ERROR，或为特定包（如 com.example）单独配置 DEBUG 级别。

六、异步层黑洞：@Async 与线程池的异常逃逸

异步方法中抛出异常不会传播至主线程，且默认不打印堆栈。Spring 提供 AsyncUncaughtExceptionHandler 接口用于兜底：

@Configuration
@EnableAsync
public class AsyncConfig implements AsyncConfigurer {
    @Override
    public AsyncUncaughtExceptionHandler getAsyncUncaughtExceptionHandler() {
        return (ex, method, params) -> {
            log.error("Async method {} threw exception with params {}", 
                      method, Arrays.toString(params), ex); // ✅ 必须传 ex
        };
    }
}

七、诊断流程图：结构化排查路径

graph TD
    A[控制台无堆栈] --> B{是否 HTTP 请求触发？}
    B -->|是| C[检查 server.error.include-stacktrace]
    B -->|否| D[检查日志级别与 Async 异常处理器]
    C --> E[是否配置了 @ControllerAdvice？]
    E -->|是| F[检查 @ExceptionHandler 是否 log.error(..., e)]
    E -->|否| G[检查是否自定义 ErrorController]
    G --> H[检查 getErrorAttributes 是否启用 STACK_TRACE]
    F --> I[确认 Logback root level ≥ ERROR]
    I --> J[启用 debug=true 验证启动阶段异常]

八、高阶验证：启用 debug=true 的双重价值

在 application.properties 中添加 debug=true 不仅开启 Spring Boot 自身的调试日志（如自动配置报告），更关键的是：强制 server.error.include-stacktrace=always，绕过所有配置干扰，快速验证是否为配置层问题。这是资深工程师的“黄金开关”。

九、生产加固建议：防御性日志与监控联动

除修复当前问题外，建议在团队规范中强制要求：
① 所有 @ExceptionHandler 方法必须含 log.error(msg, e)；
② 使用 slf4j 的 Marker 标记异常类型（如 MARKER_ERROR），便于 ELK 日志平台聚合分析；
③ 在 Prometheus + Grafana 中埋点统计 unhandled_exception_count，实现异常逃逸实时告警。

十、终极检查清单（可直接执行）

• ✅ 检查 application.properties 中是否存在 server.error.include-stacktrace=never
• ✅ 全局搜索 @ExceptionHandler，确认每个方法第二参数为 Exception e 且 log.error(..., e) 已调用
• ✅ 运行 mvn dependency:tree | grep logback 确认日志实现版本兼容性（Logback 1.4+ 对 MDC 支持更健壮）
• ✅ 在 @Async 方法内手动抛出 new RuntimeException("test")，观察是否进入 AsyncUncaughtExceptionHandler
• ✅ 启动时添加 JVM 参数 -Dlogging.level.org.springframework.boot.autoconfigure=DEBUG，捕获自动配置异常

```