Spring Boot中日志管理与异常处理实践指南-QQ沐编程

在开发和维护Spring Boot应用时，日志管理和异常处理是两个至关重要的环节。良好的日志记录能够帮助开发者快速定位问题，而完善的异常处理机制则能提升系统的健壮性和用户体验。本文将结合Spring Boot框架的特点，深入探讨日志管理的最佳实践和异常处理的高效策略，并提供具体的代码示例供参考。

一、日志管理实践

1. 日志框架的选择与配置

Spring Boot默认使用Logback作为日志框架，同时也支持Log4j2等其他框架。在pom.xml或build.gradle中，可以通过依赖管理选择日志实现：

<!-- Logback -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-logging</artifactId>
</dependency>

<!-- Log4j2 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>

2. 日志级别与格式化

日志级别（如DEBUG、INFO、WARN、ERROR）是控制日志输出的关键。通过application.properties或application.yml文件配置日志级别和输出格式：

logging:
  level:
    root: INFO
    com.example.demo: DEBUG
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"

日志格式说明：

%d：日期时间。
[%thread]：线程名称。
%-5level：日志级别（左对齐，占5位）。
%logger{36}：日志记录器名称（最多36字符）。
%msg%n：日志消息和换行符。

3. 日志文件分割策略

为了避免日志文件过大，需配置日志文件的滚动策略。以下示例基于Logback的logback-spring.xml配置：

<configuration>
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logs/demo-app.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>logs/demo-app.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
            <maxFileSize>10MB</maxFileSize>
            <maxHistory>30</maxHistory>
            <totalSizeCap>1GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
</configuration>

关键参数说明：

maxFileSize：单个文件最大容量。
maxHistory：保留的日志文件天数。
totalSizeCap：所有日志文件总容量上限。

4. 异步日志记录

异步日志可以减少日志写入对主线程性能的影响。在Logback中启用异步日志：

<configuration>
    <appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="FILE" />
        <queueSize>512</queueSize>
        <discardingThreshold>0</discardingThreshold>
    </appender>
</configuration>

5. MDC（Mapped Diagnostic Context）的使用

MDC允许在日志中附加上下文信息（如请求ID），便于追踪分布式系统中的请求链路：

import org.slf4j.MDC;

public class RequestFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
        String requestId = UUID.randomUUID().toString();
        MDC.put("requestId", requestId);
        try {
            chain.doFilter(request, response);
        } finally {
            MDC.clear();
        }
    }
}

日志格式中添加MDC字段：

<pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - [%X{requestId}] %msg%n</pattern>

二、异常处理实践

1. 全局异常处理器

通过@ControllerAdvice和@ExceptionHandler注解，可以集中处理所有异常，避免重复代码：

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleException(Exception ex) {
        ErrorResponse error = new ErrorResponse(
            LocalDateTime.now(),
            ex.getMessage(),
            "INTERNAL_SERVER_ERROR"
        );
        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleResourceNotFoundException(ResourceNotFoundException ex) {
        ErrorResponse error = new ErrorResponse(
            LocalDateTime.now(),
            ex.getMessage(),
            "RESOURCE_NOT_FOUND"
        );
        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }
}

自定义异常类示例：

public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) {
        super(message);
    }
}

2. 自定义错误码管理

通过枚举或常量类集中管理错误码，提升代码可维护性：

public enum ErrorCode {
    RESOURCE_NOT_FOUND("RESOURCE_NOT_FOUND", "Resource not found"),
    INVALID_INPUT("INVALID_INPUT", "Invalid input data"),
    INTERNAL_SERVER_ERROR("INTERNAL_SERVER_ERROR", "Internal server error");

    private final String code;
    private final String message;

    ErrorCode(String code, String message) {
        this.code = code;
        this.message = message;
    }

    public String getCode() {
        return code;
    }

    public String getMessage() {
        return message;
    }
}

3. 异常处理中的日志记录

在异常处理器中记录详细的错误信息，并结合MDC追踪上下文：

@ControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger logger = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleException(Exception ex) {
        String requestId = MDC.get("requestId");
        logger.error("Request ID: {} - Error occurred: {}", requestId, ex.getMessage(), ex);
        // 返回错误响应
    }
}

4. 错误响应结构设计

定义统一的错误响应格式，方便前端解析和处理：

public class ErrorResponse {
    private LocalDateTime timestamp;
    private String message;
    private String errorCode;

    // 构造方法、getter和setter
}

三、日志与异常处理的结合

1. 日志与异常关联

通过MDC将异常与日志绑定，便于快速定位问题：

try {
    // 可能抛出异常的代码
} catch (Exception ex) {
    String requestId = MDC.get("requestId");
    logger.error("Request ID: {} - Exception: {}", requestId, ex.getMessage(), ex);
    throw ex;
}