Spring Boot全局异常处理与日志监控全解析

更新时间：2025年08月15日 09:14:25 作者：学习编程的小羊

本文给大家介绍Spring Boot全局异常处理与日志监控全解析,通过实例代码给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友参考下吧

1. 背景与目标

生产环境中，异常无处不在。我们要解决三件事：

对外统一 JSON 错误格式，便于前端/客户端解析与展示；
在日志中携带可追溯的 requestId（MDC），便于从日志中串联一条请求的全部操作；
对异常做指标统计（例如按异常类型/状态码计数），能在监控平台（Prometheus/Grafana）上报警与分析。

2. 设计思路（要点）

使用 @RestControllerAdvice + @ExceptionHandler 进行全局捕获；
返回标准 ErrorResponse（包含时间戳、HTTP 状态码、业务错误码、message、path、requestId）；
在异常处理器里同时 log.error(...) 并把异常计数交给 MeterRegistry（Micrometer）；
通过 OncePerRequestFilter 在每个请求开始时生成 requestId 并放入 SLF4J 的 MDC（MDC.put("requestId", id)）；
配置 logback-spring.xml 把 %X{requestId} 输出到日志 pattern，建议也输出 JSON（视需求）。

3. 项目依赖（Maven）

<!-- pom.xml 依赖片段 -->
<dependencies>
    <!-- Spring Boot Starter Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- 日志 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-logging</artifactId>
    </dependency>
    <!-- Validation -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <!-- Actuator & Micrometer (Prometheus) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-prometheus</artifactId>
    </dependency>
</dependencies>

4. 通用错误响应 DTO

src/main/java/com/example/demo/api/ErrorResponse.java

package com.example.demo.api;
import java.time.Instant;
import java.util.Map;
public class ErrorResponse {
    private Instant timestamp;
    private int status;
    private String error;
    private String message;
    private String path;
    private String requestId;
    private Map<String, Object> details; // 可选扩展字段
    public ErrorResponse() {}
    public ErrorResponse(int status, String error, String message, String path, String requestId) {
        this.timestamp = Instant.now();
        this.status = status;
        this.error = error;
        this.message = message;
        this.path = path;
        this.requestId = requestId;
    }
    // getters & setters omitted for brevity
}

5. 自定义业务异常示例

src/main/java/com/example/demo/exception/BusinessException.java

package com.example.demo.exception;
public class BusinessException extends RuntimeException {
    private final String code;
    public BusinessException(String code, String message) {
        super(message);
        this.code = code;
    }
    public String getCode() {
        return code;
    }
}

6. 全局异常处理实现（日志 + 指标）

src/main/java/com/example/demo/exception/GlobalExceptionHandler.java

package com.example.demo.exception;
import com.example.demo.api.ErrorResponse;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Counter;
import jakarta.servlet.http.HttpServletRequest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.util.stream.Collectors;
@RestControllerAdvice
public class GlobalExceptionHandler {
    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
    private final MeterRegistry meterRegistry;
    // 一个简单的异常计数器前缀（可按异常 class、path、status 维度构造标签）
    private final Counter genericExceptionCounter;
    public GlobalExceptionHandler(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
        this.genericExceptionCounter = Counter.builder("exceptions.total")
                .description("Total number of handled exceptions")
                .register(meterRegistry);
    }
    // 业务异常处理
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ErrorResponse> handleBusiness(BusinessException ex, HttpServletRequest request) {
        String requestId = MDC.get("requestId");
        log.warn("BusinessException - requestId={}, path={}, code={}, msg={}",
                requestId, request.getRequestURI(), ex.getCode(), ex.getMessage());
        // 增加监控计数（按业务码）
        meterRegistry.counter("exceptions.by_code", "code", ex.getCode()).increment();
        ErrorResponse err = new ErrorResponse(
                HttpStatus.BAD_REQUEST.value(),
                "Business Error",
                ex.getMessage(),
                request.getRequestURI(),
                requestId
        );
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(err);
    }
    // 参数校验异常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException ex, HttpServletRequest request) {
        String requestId = MDC.get("requestId");
        String msg = ex.getBindingResult().getFieldErrors().stream()
                .map(fe -> fe.getField() + ":" + fe.getDefaultMessage())
                .collect(Collectors.joining("; "));
        log.info("Validation failed - requestId={}, path={}, errors={}", requestId, request.getRequestURI(), msg);
        meterRegistry.counter("exceptions.validation").increment();
        ErrorResponse err = new ErrorResponse(
                HttpStatus.BAD_REQUEST.value(),
                "Validation Error",
                msg,
                request.getRequestURI(),
                requestId
        );
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(err);
    }
    // 通用异常处理
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGeneric(Exception ex, HttpServletRequest request) {
        String requestId = MDC.get("requestId");
        log.error("Unhandled exception - requestId={}, path={}", requestId, request.getRequestURI(), ex);
        // 总量计数
        genericExceptionCounter.increment();
        // 按异常类计数标签
        meterRegistry.counter("exceptions.by_type", "type", ex.getClass().getSimpleName()).increment();
        ErrorResponse err = new ErrorResponse(
                HttpStatus.INTERNAL_SERVER_ERROR.value(),
                "Internal Server Error",
                "服务器繁忙，请稍后重试",
                request.getRequestURI(),
                requestId
        );
        // 在开发环境可以把 ex.getMessage() 或堆栈信息放到 details 中（生产环境慎用）
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(err);
    }
}

说明：

在处理器中我们同时 log 和 meterRegistry.counter(...).increment()，用于日志与监控；
MDC.get("requestId") 用于把请求的 requestId 写入返回体，方便客户端带回查日志。

7. 请求 ID 与 MDC 过滤器（保证每条请求都有 requestId）

src/main/java/com/example/demo/filter/RequestIdFilter.java

package com.example.demo.filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
import java.util.UUID;
@Component
public class RequestIdFilter extends OncePerRequestFilter {
    private static final String REQUEST_ID_HEADER = "X-Request-Id";
    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {
        try {
            String requestId = request.getHeader(REQUEST_ID_HEADER);
            if (requestId == null || requestId.isBlank()) {
                requestId = UUID.randomUUID().toString();
            }
            MDC.put("requestId", requestId);
            // 同时将 requestId 放回响应头，便于前端或网关追踪
            response.setHeader(REQUEST_ID_HEADER, requestId);
            filterChain.doFilter(request, response);
        } finally {
            MDC.remove("requestId");
        }
    }
}

说明：

每次请求都会生成（或沿用上游）X-Request-Id，并放到 MDC，日志 pattern 能输出 %X{requestId}；
响应中返回该 header，有利于客户端/运维串联。

8. 日志配置与示例输出

application.properties（关键项）

# 暴露 Actuator prometheus 端点
management.endpoints.web.exposure.include=health,info,prometheus,metrics
management.endpoint.prometheus.enabled=true
# 日志级别（根据环境调整）
logging.level.root=INFO
logging.level.com.example=DEBUG

logback-spring.xml（pattern 示例）

放在 src/main/resources/logback-spring.xml：

<configuration>
    <springProfile name="prod">
        <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <!-- 输出包含 requestId -->
                <pattern>%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX} [%thread] %-5level %logger{36} - %msg - requestId=%X{requestId}%n</pattern>
            </encoder>
        </appender>
        <root level="INFO">
            <appender-ref ref="STDOUT"/>
        </root>
    </springProfile>
    <springProfile name="!prod">
        <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg - requestId=%X{requestId}%n</pattern>
            </encoder>
        </appender>
        <root level="DEBUG">
            <appender-ref ref="STDOUT"/>
        </root>
    </springProfile>
</configuration>

日志示例（一条报错请求）

2025-08-10T18:34:10.123+03:00 [http-nio-8080-exec-1] ERROR com.example.demo.exception.GlobalExceptionHandler - Unhandled exception - requestId=2f1a8c7f-1d2b-4f0a-9b2a-123456789abc, path=/api/orders
java.lang.NullPointerException: ...
    at com.example.demo.service.OrderService.create(OrderService.java:45)
    ...

你会看到 requestId 出现在每条日志，便于用 grep 或日志平台（ELK/EFK）按 requestId 过滤整条调用链。

9. 将异常计数暴露到监控（Actuator + Micrometer）

前文 GlobalExceptionHandler 已经把计数器注册到 Micrometer：

exceptions.total
exceptions.by_code{code=...}
exceptions.by_type{type=...}

在 Prometheus 中抓取 Spring Boot 的 /actuator/prometheus 指标，就能在 Grafana 中根据 exceptions.by_type 做报警规则。例如：如果 exceptions.by_type{type="NullPointerException"} 在 5 分钟内增幅过大，就触发报警。

10. 常见场景与处理建议

参数校验失败（MethodArgumentNotValidException）
- 建议把字段错误拼成单行 message（示例中已实现），并返回 400。
业务异常（自定义 BusinessException）
- 业务异常可携带 code，前端可根据 code 做差异化提示或重试策略；监控中也可以以 code 为标签统计。
第三方超时/HTTP 错误（RestTemplate/WebClient）
- 在调用处抛出有意义的自定义异常或将原异常包装后抛出；在全局异常处理器中根据异常类型映射为 502/504 等状态，并计数。
链路追踪（可选）
- 若有分布式追踪需求，可接入 OpenTelemetry/Zipkin/Jaeger，但仍保留 requestId 做本地快速查找。
安全注意
- 生产环境不要在 API 返回中包含完整堆栈或敏感字段（示例中仅返回通用 message）。可以在开发 profile 下增加 details。

11. 小结与部署建议

统一异常处理 可以显著提升前后端协作效率与错误可观察性；
MDC + requestId 是生产排查的第一要素，务必保证上游（网关）能传递 X-Request-Id，否则服务端生成并回传；
监控计数（Micrometer）使异常不再是“偶发的黑盒”，可以在 Grafana/Prometheus 上设定阈值与报警；
日志集中化 建议配合 ELK/EFK（或云日志）保存结构化日志（JSON）以便于按 requestId、code、type 聚合查询；
对外返回 应保持稳定的 JSON 格式与明确的状态码，避免泄露内部实现细节。

您可能感兴趣的文章:

使用Feign远程调用时,序列化对象失败的解决
这篇文章主要介绍了使用Feign远程调用时,序列化对象失败的解决方案，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2021-07-07
MyBatis实现多表联查的详细代码
这篇文章主要介绍了MyBatis如何实现多表联查，通过实例代码给大家介绍使用映射配置文件实现多表联查，使用注解的方式实现多表联查,需要的朋友可以参考下
2022-08-08
Java方法上注解值修改不成功的问题
这篇文章主要介绍了Java方法上注解值修改不成功的解决方法，本文结合实例代码给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下
2023-02-02
Java Spring boot实现生成二维码
大家好，本篇文章主要讲的是Java Spring boot实现生成二维码，感兴趣的同学赶快来看一看吧，对你有帮助的话记得收藏一下
2022-02-02
Spring项目中Ordered接口的应用之全局过滤器(GlobalFilter)的顺序控制
在Spring框架,尤其是Spring Cloud Gateway或Spring WebFlux项目中,Ordered接口扮演着重要的角色,特别是在实现全局过滤器(GlobalFilter)时,用于控制过滤器执行的优先级,下面将介绍如何在Spring项目中使用Ordered接口来管理Global Filter的执行顺序,需要的朋友可以参考下
2024-06-06
idea打开运行配置java web项目的全过程
这篇文章主要给大家介绍了关于idea打开运行配置java web项目的相关资料,有些时候我们用IDEA跑之前用eclipse中运行的项目的时候,总是不止所措,要不就是只展示html,要不就是不能部署成功,需要的朋友可以参考下
2023-08-08
mybatis动态新增(insert)和修改(update)方式
这篇文章主要介绍了mybatis动态新增(insert)和修改(update)方式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2024-05-05
Mybatis逆向工程时失败问题及解决
这篇文章主要介绍了Mybatis逆向工程时失败问题及解决方案,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2023-11-11
利用微信小程序+JAVA实现微信支付的全过程
微信支付是一种在线支付解决方案,允许用户通过微信内的支付功能进行付款,下面这篇文章主要给大家介绍了关于利用微信小程序+JAVA实现微信支付的相关资料,需要的朋友可以参考下
2024-08-08
总结Java中线程的状态及多线程的实现方式
Java中可以通过Thread类和Runnable接口来创建多个线程,线程拥有五种状态,下面我们就来简单总结Java中线程的状态及多线程的实现方式:
2016-07-07