别再System.out了！这份SpringBoot日志优雅指南，让你告别日志混乱

大家好，我是小悟。

一、需求描述

在实际开发中，日志系统需要满足以下需求：

1. 区分日志级别：DEBUG/INFO/WARN/ERROR 各司其职
2. 性能友好：避免日志序列化开销，支持异步输出
3. 链路追踪：一次请求全链路可追踪（RequestId）
4. 敏感信息脱敏：手机号、身份证等自动脱敏
5. 日志分类：业务日志、错误日志、慢SQL日志分开存储
6. 输出规范：JSON格式，便于ELK采集分析
7. 开发/生产环境差异化：开发环境输出控制台，生产环境输出文件

二、详细步骤与代码实现

1. 添加依赖

<!-- pom.xml -->
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- 性能优化：异步日志需要disruptor -->
    <dependency>
        <groupId>com.lmax</groupId>
        <artifactId>disruptor</artifactId>
        <version>3.4.4</version>
    </dependency>
    
    <!-- 链路追踪 -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-sleuth</artifactId>
        <version>3.1.5</version>
    </dependency>
    
    <!-- 简化代码：lombok -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

2. 配置文件（application.yml）

# application.yml
spring:
  application:
    name: demo-service
  
  # 链路追踪配置
  sleuth:
    web:
      enabled: true
    sampler:
      probability: 1.0  # 生产环境建议0.1

# 日志配置
logging:
  # 日志文件路径
  file:
    path: ./logs
    name: ${logging.file.path}/${spring.application.name}.log
  
  # 日志级别
  level:
    root: INFO
    com.example: DEBUG
    org.springframework.web: INFO
    org.hibernate: WARN
  
  # 日志格式
  pattern:
    console: "%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(%5p) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n%wEx"
    file: "%d{yyyy-MM-dd HH:mm:ss.SSS} %5p ${PID:- } --- [%t] %-40.40logger{39} : %m%n%wEx"

# 自定义日志配置
log:
  # 敏感字段列表
  sensitive-fields:
    - password
    - oldPassword
    - newPassword
    - idCard
    - phone
    - bankCard
    - token
    - secret

3. Logback配置（logback-spring.xml）

<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" scanPeriod="60 seconds">
    
    <!-- 引入Spring环境配置 -->
    <springProperty scope="context" name="APP_NAME" source="spring.application.name" defaultValue="app"/>
    <springProperty scope="context" name="LOG_PATH" source="logging.file.path" defaultValue="./logs"/>
    
    <!-- 彩色日志依赖 -->
    <conversionRule conversionWord="clr" converterClass="org.springframework.boot.logging.logback.ColorConverter"/>
    
    <!-- 日志格式 -->
    <property name="CONSOLE_LOG_PATTERN" 
              value="%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(%5p) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n%wEx"/>
    
    <property name="FILE_LOG_PATTERN" 
              value="%d{yyyy-MM-dd HH:mm:ss.SSS} %5p ${PID:- } --- [%t] %-40.40logger{39} : %m%n%wEx"/>
    
    <!-- JSON格式（用于生产环境ELK） -->
    <property name="JSON_LOG_PATTERN" 
              value='{"timestamp":"%d{yyyy-MM-dd HH:mm:ss.SSS}","level":"%p","app":"${APP_NAME}","traceId":"%X{traceId}","thread":"%t","logger":"%logger","message":"%m","exception":"%wEx"}%n'/>
    
    <!-- 控制台输出 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>${CONSOLE_LOG_PATTERN}</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>
    
    <!-- 异步控制台输出（性能优化） -->
    <appender name="ASYNC_CONSOLE" class="ch.qos.logback.classic.AsyncAppender">
        <discardingThreshold>0</discardingThreshold>
        <queueSize>1024</queueSize>
        <appender-ref ref="CONSOLE"/>
    </appender>
    
    <!-- 普通日志文件 -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/${APP_NAME}.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/${APP_NAME}.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>30</maxHistory>
            <totalSizeCap>10GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>${FILE_LOG_PATTERN}</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>
    
    <!-- 错误日志单独文件 -->
    <appender name="ERROR_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/${APP_NAME}-error.log</file>
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>ERROR</level>
        </filter>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/${APP_NAME}-error.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>90</maxHistory>
        </rollingPolicy>
        <encoder>
            <pattern>${FILE_LOG_PATTERN}</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>
    
    <!-- 业务日志文件 -->
    <appender name="BIZ_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/biz.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/biz.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>30</maxHistory>
        </rollingPolicy>
        <encoder>
            <pattern>${FILE_LOG_PATTERN}</pattern>
        </encoder>
    </appender>
    
    <!-- 异步文件输出（性能优化） -->
    <appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
        <queueSize>2048</queueSize>
        <discardingThreshold>0</discardingThreshold>
        <includeCallerData>true</includeCallerData>
        <appender-ref ref="FILE"/>
    </appender>
    
    <appender name="ASYNC_ERROR_FILE" class="ch.qos.logback.classic.AsyncAppender">
        <queueSize>1024</queueSize>
        <appender-ref ref="ERROR_FILE"/>
    </appender>
    
    <appender name="ASYNC_BIZ_FILE" class="ch.qos.logback.classic.AsyncAppender">
        <queueSize>1024</queueSize>
        <appender-ref ref="BIZ_FILE"/>
    </appender>
    
    <!-- 业务日志 Logger -->
    <logger name="BIZ_LOGGER" level="INFO" additivity="false">
        <appender-ref ref="ASYNC_BIZ_FILE"/>
    </logger>
    
    <!-- Root Logger -->
    <root level="INFO">
        <appender-ref ref="ASYNC_CONSOLE"/>
        <appender-ref ref="ASYNC_FILE"/>
        <appender-ref ref="ASYNC_ERROR_FILE"/>
    </root>
</configuration>

4. 日志工具类封装

package com.example.log.util;

import lombok.extern.slf4j.Slf4j;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;

import javax.servlet.http.HttpServletRequest;
import java.util.UUID;

/**
 * 日志工具类
 */
@Slf4j
@Component
public class LogUtil {
    
    // 业务日志专用Logger
    private static final Logger BIZ_LOGGER = LoggerFactory.getLogger("BIZ_LOGGER");
    
    /**
     * 获取当前请求的TraceId
     */
    public static String getTraceId() {
        try {
            ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
            if (attributes != null) {
                HttpServletRequest request = attributes.getRequest();
                String traceId = request.getHeader("X-Trace-Id");
                if (traceId == null || traceId.isEmpty()) {
                    traceId = UUID.randomUUID().toString().replace("-", "");
                }
                return traceId;
            }
        } catch (Exception e) {
            log.warn("获取TraceId失败", e);
        }
        return UUID.randomUUID().toString().replace("-", "");
    }
    
    /**
     * 业务日志（关键操作记录）
     */
    public static void bizLog(String operation, String userId, Object... params) {
        String traceId = getTraceId();
        String message = String.format("[BIZ][%s][%s][%s] params: %s", 
            traceId, operation, userId, params);
        BIZ_LOGGER.info(message);
    }
    
    /**
     * 接口调用日志（简洁版）
     */
    public static void apiLog(String apiName, long costTime, Object request, Object response) {
        if (costTime > 3000) {
            // 慢接口使用WARN级别
            log.warn("[API][{}] cost: {}ms, request: {}, response: {}", 
                apiName, costTime, request, response);
        } else {
            log.info("[API][{}] cost: {}ms", apiName, costTime);
        }
    }
    
    /**
     * 方法调用日志（带耗时）
     */
    public static void methodLog(String methodName, long startTime) {
        long cost = System.currentTimeMillis() - startTime;
        if (cost > 1000) {
            log.warn("[METHOD][{}] cost: {}ms", methodName, cost);
        } else {
            log.debug("[METHOD][{}] cost: {}ms", methodName, cost);
        }
    }
}

5. 敏感信息脱敏工具

package com.example.log.util;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import javax.annotation.PostConstruct;
import java.util.*;
import java.util.regex.Pattern;

/**
 * 日志脱敏工具
 */
@Slf4j
@Component
public class DesensitizationUtil {
    
    @Value("${log.sensitive-fields:}")
    private List<String> sensitiveFields;
    
    private static final Set<String> SENSITIVE_FIELDS = new HashSet<>(Arrays.asList(
        "password", "oldPassword", "newPassword", "idCard", "phone", 
        "bankCard", "token", "secret", "authorization"
    ));
    
    private static final Pattern PHONE_PATTERN = Pattern.compile("(\\d{3})\\d{4}(\\d{4})");
    private static final Pattern ID_CARD_PATTERN = Pattern.compile("(\\d{4})\\d{10}(\\d{4})");
    private static final Pattern BANK_CARD_PATTERN = Pattern.compile("(\\d{4})\\d{10,12}(\\d{4})");
    
    private ObjectMapper objectMapper;
    
    @PostConstruct
    public void init() {
        this.objectMapper = new ObjectMapper();
        this.objectMapper.enable(SerializationFeature.INDENT_OUTPUT);
        if (sensitiveFields != null) {
            SENSITIVE_FIELDS.addAll(sensitiveFields);
        }
    }
    
    /**
     * 对象脱敏（JSON序列化前处理）
     */
    public String toJsonWithDesensitization(Object obj) {
        try {
            if (obj == null) {
                return "null";
            }
            Object desensitized = desensitize(obj);
            return objectMapper.writeValueAsString(desensitized);
        } catch (JsonProcessingException e) {
            log.error("JSON序列化失败", e);
            return obj != null ? obj.toString() : "null";
        }
    }
    
    /**
     * 递归脱敏
     */
    @SuppressWarnings("unchecked")
    private Object desensitize(Object obj) {
        if (obj == null) {
            return null;
        }
        
        if (obj instanceof Map) {
            Map<String, Object> map = (Map<String, Object>) obj;
            Map<String, Object> result = new HashMap<>();
            for (Map.Entry<String, Object> entry : map.entrySet()) {
                String key = entry.getKey();
                Object value = entry.getValue();
                
                if (SENSITIVE_FIELDS.contains(key.toLowerCase())) {
                    result.put(key, "***");
                } else {
                    result.put(key, desensitize(value));
                }
            }
            return result;
        }
        
        if (obj instanceof List) {
            List<Object> list = (List<Object>) obj;
            List<Object> result = new ArrayList<>();
            for (Object item : list) {
                result.add(desensitize(item));
            }
            return result;
        }
        
        // 字符串类型特殊处理
        if (obj instanceof String) {
            String str = (String) obj;
            // 手机号脱敏
            if (str.matches("^1[3-9]\\d{9}$")) {
                return PHONE_PATTERN.matcher(str).replaceAll("$1****$2");
            }
            // 身份证脱敏
            if (str.matches("^[1-9]\\d{5}(18|19|20)\\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])\\d{3}[\\dXx]$")) {
                return ID_CARD_PATTERN.matcher(str).replaceAll("$1**********$2");
            }
        }
        
        return obj;
    }
    
    /**
     * 快速脱敏手机号
     */
    public static String maskPhone(String phone) {
        if (phone == null || phone.length() != 11) {
            return phone;
        }
        return phone.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2");
    }
    
    /**
     * 快速脱敏身份证
     */
    public static String maskIdCard(String idCard) {
        if (idCard == null || idCard.length() < 18) {
            return idCard;
        }
        return idCard.replaceAll("(\\d{4})\\d{10}(\\d{4})", "$1**********$2");
    }
}

6. 全局日志拦截器（AOP实现）

package com.example.log.aspect;

import com.example.log.util.DesensitizationUtil;
import com.example.log.util.LogUtil;
import lombok.extern.slf4j.Slf4j;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;
import org.aspectj.lang.reflect.MethodSignature;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;

import javax.servlet.http.HttpServletRequest;
import java.lang.reflect.Method;
import java.util.Arrays;
import java.util.stream.Collectors;

/**
 * Controller层日志切面
 */
@Slf4j
@Aspect
@Component
public class ControllerLogAspect {
    
    @Autowired
    private DesensitizationUtil desensitizationUtil;
    
    // 定义切点：所有Controller类下的方法
    @Pointcut("execution(* com.example..controller.*.*(..))")
    public void controllerPointcut() {}
    
    @Around("controllerPointcut()")
    public Object around(ProceedingJoinPoint joinPoint) throws Throwable {
        long startTime = System.currentTimeMillis();
        
        // 获取请求信息
        ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        HttpServletRequest request = attributes != null ? attributes.getRequest() : null;
        
        // 获取方法信息
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        Method method = signature.getMethod();
        String className = joinPoint.getTarget().getClass().getSimpleName();
        String methodName = method.getName();
        
        // 获取参数（脱敏处理）
        Object[] args = joinPoint.getArgs();
        String params = "";
        if (args != null && args.length > 0) {
            params = Arrays.stream(args)
                .map(arg -> desensitizationUtil.toJsonWithDesensitization(arg))
                .collect(Collectors.joining(", "));
        }
        
        // 请求信息日志
        if (request != null) {
            log.info("【请求开始】{} {} | 参数: {}", 
                request.getMethod(), request.getRequestURI(), params);
        } else {
            log.info("【方法调用】{}.{} 参数: {}", className, methodName, params);
        }
        
        Object result = null;
        try {
            result = joinPoint.proceed();
            long costTime = System.currentTimeMillis() - startTime;
            
            // 响应日志（脱敏处理）
            String responseJson = desensitizationUtil.toJsonWithDesensitization(result);
            log.info("【请求结束】{}.{} 耗时: {}ms | 响应: {}", 
                className, methodName, costTime, responseJson);
            
            // 慢请求告警
            if (costTime > 3000) {
                log.warn("【慢请求】{}.{} 耗时: {}ms", className, methodName, costTime);
            }
            
            return result;
        } catch (Exception e) {
            long costTime = System.currentTimeMillis() - startTime;
            log.error("【请求异常】{}.{} 耗时: {}ms 异常: {}", 
                className, methodName, costTime, e.getMessage(), e);
            throw e;
        }
    }
}

7. MDC链路追踪过滤器

package com.example.log.filter;

import lombok.extern.slf4j.Slf4j;
import org.slf4j.MDC;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.util.UUID;

/**
 * MDC过滤器：实现全链路追踪
 */
@Slf4j
@Component
@Order(1)
public class TraceIdFilter implements Filter {
    
    private static final String TRACE_ID = "traceId";
    
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        String traceId = httpRequest.getHeader("X-Trace-Id");
        
        if (traceId == null || traceId.isEmpty()) {
            traceId = UUID.randomUUID().toString().replace("-", "");
        }
        
        try {
            // 将traceId放入MDC，日志模板中可通过%X{traceId}引用
            MDC.put(TRACE_ID, traceId);
            MDC.put("clientIp", getClientIp(httpRequest));
            
            chain.doFilter(request, response);
        } finally {
            // 清理MDC，避免内存泄漏
            MDC.clear();
        }
    }
    
    private String getClientIp(HttpServletRequest request) {
        String ip = request.getHeader("X-Forwarded-For");
        if (ip == null || ip.isEmpty()) {
            ip = request.getRemoteAddr();
        }
        return ip != null ? ip.split(",")[0].trim() : "unknown";
    }
}

8. 业务中使用示例

package com.example.demo.controller;

import com.example.demo.service.UserService;
import com.example.log.util.LogUtil;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;
import java.util.HashMap;
import java.util.Map;

@Slf4j
@RestController
@RequestMapping("/api/user")
@RequiredArgsConstructor
public class UserController {
    
    private final UserService userService;
    
    @PostMapping("/login")
    public Map<String, Object> login(@RequestBody @Valid LoginRequest request) {
        // 使用Lombok的@Slf4j
        log.info("用户登录请求: username={}", request.getUsername());
        
        long startTime = System.currentTimeMillis();
        try {
            UserVO user = userService.login(request);
            
            // 记录业务日志
            LogUtil.bizLog("用户登录", user.getId(), "login", request.getUsername());
            
            // 记录方法耗时
            LogUtil.methodLog("login", startTime);
            
            return Map.of("success", true, "data", user);
        } catch (Exception e) {
            log.error("用户登录失败: username={}, error={}", request.getUsername(), e.getMessage(), e);
            throw e;
        }
    }
    
    @PostMapping("/update")
    public Map<String, Object> updateUser(@RequestBody UserUpdateRequest request) {
        // 这里password字段会被自动脱敏
        log.info("更新用户信息: {}", request);
        
        userService.updateUser(request);
        return Map.of("success", true);
    }
}

// 请求对象示例
@Data
class LoginRequest {
    private String username;
    private String password;  // 会被脱敏
}

@Data
class UserUpdateRequest {
    private String userId;
    private String phone;
    private String idCard;
    private String password;
}

9. 异常统一处理中的日志

package com.example.demo.handler;

import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(BusinessException.class)
    public Result<?> handleBusinessException(BusinessException e) {
        // 业务异常：记录WARN级别即可
        log.warn("业务异常: code={}, message={}", e.getCode(), e.getMessage());
        return Result.error(e.getCode(), e.getMessage());
    }
    
    @ExceptionHandler(Exception.class)
    public Result<?> handleException(Exception e) {
        // 系统异常：记录ERROR级别，包含堆栈
        log.error("系统异常", e);
        return Result.error(500, "系统繁忙，请稍后重试");
    }
}

三、总结

最佳实践总结

原则	说明	示例
级别正确	DEBUG调试、INFO业务流程、WARN异常可恢复、ERROR系统错误	循环内用DEBUG，关键节点用INFO
参数占位	使用{}占位符，避免字符串拼接	log.info("user: {}", user)
异常记录	必须传入异常对象，输出堆栈	log.error("错误", e)
异步输出	生产环境必须配置AsyncAppender	使用Disruptor提升性能
链路追踪	使用MDC传递traceId	全链路可追踪
敏感脱敏	密码、手机号等必须脱敏	实现自定义脱敏工具
日志开关	使用isDebugEnabled()避免无效序列化	if(log.isDebugEnabled()){...}
合理采样	高频日志需采样	1%或千分之一

性能优化要点

1. 异步日志：AsyncAppender + Disruptor，QPS提升5-10倍
2. 条件日志 ：使用log.isDebugEnabled()避免参数计算
3. 合理级别：生产环境建议INFO，DEBUG仅开发/测试环境
4. 避免打印大对象：大List/大JSON需要截断或只打印长度

监控告警建议

• ERROR日志数量突增 → 钉钉/企微告警
• 慢请求日志（>3s） → 性能监控
• 特定业务日志（登录失败频繁） → 安全告警

日志规范Checklist

• 禁止使用System.out.println()
• 禁止打印密码、token等敏感信息
• 日志消息清晰，包含关键业务标识（userId、orderId）
• 异常日志必须包含堆栈信息
• 关键业务操作必须有业务日志
• 日志文件配置滚动策略和保留时长（建议30天）
• 生产环境关闭DEBUG日志

通过以上方案，可以实现生产级的日志系统，既保证性能又便于问题排查和监控告警。

谢谢你看我的文章，既然看到这里了，如果觉得不错，随手点个赞、转发、在看三连吧，感谢感谢。那我们，下次再见。

您的一键三连，是我更新的最大动力，谢谢

山水有相逢，来日皆可期，谢谢阅读，我们再会

我手中的金箍棒，上能通天，下能探海