Spring Boot 全局异常处理与日志监控实战

Spring Boot 全局异常处理与日志监控实战 | 极客日志

<!-- 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>

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
}

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;
    }
}

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);
    }
}

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");
        }
    }
}

# 暴露 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

<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)
	...

Spring Boot 全局异常处理与日志监控实战

1. 背景与目标

2. 设计思路（要点）

3. 项目依赖（Maven）

4. 通用错误响应 DTO

5. 自定义业务异常示例

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

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

8. 日志配置与示例输出

application.properties（关键项）

logback-spring.xml（pattern 示例）

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

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

10. 常见场景与处理建议

11. 小结与部署建议

更多推荐文章

相关免费在线工具

Spring Boot 全局异常处理与日志监控实战

1. 背景与目标

2. 设计思路（要点）

3. 项目依赖（Maven）

4. 通用错误响应 DTO

5. 自定义业务异常示例

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

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

8. 日志配置与示例输出

application.properties（关键项）

logback-spring.xml（pattern 示例）

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

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

10. 常见场景与处理建议

11. 小结与部署建议

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具