日志输出优化实战：从“能用”到“好用”的全攻略

// 反例1：用ERROR记录预期内的失败（用户输入错误）
if (StringUtils.isEmpty(userId)) {
    log.error("用户ID为空，无法查询订单"); // 错误：用户输入错误属于预期内，应使用WARN
    return Result.fail("用户ID不能为空");
}

// 反例2：用INFO记录调试信息
log.info("查询订单入参：orderNo={}", orderNo); // 错误：入参记录属于调试信息，应使用DEBUG
Order order = orderService.getByOrderNo(orderNo);

// 正例
if (StringUtils.isEmpty(userId)) {
    log.warn("用户ID为空，拒绝查询订单，请求参数：{}", requestParams); // WARN记录预期内异常，附带参数
    return Result.fail("用户ID不能为空");
}

try {
    Order order = orderService.getByOrderNo(orderNo);
    log.info("订单查询成功，orderNo={}, userId={}", orderNo, userId); // INFO记录核心流程节点
} catch (Exception e) {
    log.error("订单查询失败，orderNo={}, userId={}", orderNo, userId, e); // ERROR记录异常，附带堆栈
    return Result.fail("查询失败");
}

<!-- 日志JSON格式化依赖 -->
<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>7.4.0</version>
</dependency>

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- 上下文名称：区分不同服务 -->
    <contextName>order-service</contextName>
    
    <!-- 定义日志输出格式：JSON格式 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
            <!-- 固定字段：服务名、日志级别、时间戳等 -->
            <includeMdcKeyName>requestId</includeMdcKeyName> <!-- 包含请求ID（链路追踪） -->
            <includeMdcKeyName>userId</includeMdcKeyName>     <!-- 包含用户ID -->
            <customFields>"service":"order-service","env":"prod"</customFields> <!-- 自定义固定字段 -->
            <fieldNames>
                <timestamp>timestamp</timestamp>
                <level>level</level>
                <message>message</message>
                <logger>logger</logger>
                <thread>thread</thread>
                <stack_trace>stackTrace</stack_trace>
            </fieldNames>
        </encoder>
    </appender>
    
    <!-- 根日志级别：生产环境设为INFO -->
    <root level="INFO">
        <appender-ref ref="CONSOLE" />
    </root>
    
    <!-- 自定义包日志级别：如mapper层设为WARN，减少冗余 -->
    <logger name="com.demo.mapper" level="WARN" additivity="false">
        <appender-ref ref="CONSOLE" />
    </logger>
</configuration>

{
  "service": "order-service",
  "env": "prod",
  "requestId": "req-20240520103000123",
  "userId": "1001",
  "timestamp": "2024-05-20T10:30:00.123+08:00",
  "level": "INFO",
  "message": "订单创建成功，orderNo=ORDER20240520001",
  "logger": "com.demo.controller.OrderController",
  "thread": "http-nio-8080-exec-2"
}

import org.slf4j.MDC;
import org.springframework.web.servlet.HandlerInterceptor;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.UUID;

// 自定义拦截器：生成requestId并放入MDC
public class LogInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // 生成唯一requestId
        String requestId = UUID.randomUUID().toString().replace("-", "");
        MDC.put("requestId", requestId);
        // 从请求头获取userId（如登录后放入）
        String userId = request.getHeader("userId");
        if (userId != null) {
            MDC.put("userId", userId);
        }
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        // 清除MDC，避免线程复用导致的参数污染
        MDC.clear();
    }
}

// 配置拦截器
@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new LogInterceptor()).addPathPatterns("/**");
    }
}

// 业务代码中使用（无需拼接requestId和userId）
@RestController
public class OrderController {
    private final Logger log = LoggerFactory.getLogger(OrderController.class);

    @PostMapping("/order/create")
    public Result createOrder(@RequestBody OrderCreateDTO dto) {
        try {
            String orderNo = orderService.create(dto);
            // 日志自动包含MDC中的requestId和userId
            log.info("订单创建成功，orderNo={}, 商品ID列表={}", orderNo, dto.getProductIds());
            return Result.success(orderNo);
        } catch (Exception e) {
            log.error("订单创建失败，请求参数={}", dto, e);
            return Result.fail("创建失败");
        }
    }
}

// 反例：即使日志级别是WARN，也会执行字符串拼接，产生性能损耗
log.debug("订单查询，orderNo=" + orderNo + ", userId=" + userId);

// 正例：使用占位符，日志级别不满足时不会执行参数拼接
log.debug("订单查询，orderNo={}, userId={}", orderNo, userId);

<!-- 异步日志配置 -->
<appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
    <discardingThreshold>0</discardingThreshold> <!-- 不丢弃日志（关键业务建议） -->
    <queueSize>1024</queueSize> <!-- 队列大小：根据并发量调整 -->
    <appender-ref ref="FILE" /> <!-- 关联文件输出appender -->
</appender>

<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/order-service.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
        <fileNamePattern>logs/order-service.%d{yyyy-MM-dd}.log</fileNamePattern>
        <maxHistory>30</maxHistory> <!-- 保留30天日志 -->
        <totalSizeCap>10GB</totalSizeCap> <!-- 日志总大小限制 -->
    </rollingPolicy>
    <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
        <maxFileSize>100MB</maxFileSize> <!-- 单个文件最大100MB -->
    </triggeringPolicy>
    <encoder>
        <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n&lt;/pattern&gt;
    &lt;/encoder&gt;
&lt;/appender&gt;

import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.databind.JsonSerializer;
import com.fasterxml.jackson.databind.SerializerProvider;
import java.io.IOException;

// 手机号脱敏序列化器
public class MobileDesensitizer extends JsonSerializer<String> {
    @Override
    public void serialize(String mobile, JsonGenerator gen, SerializerProvider serializers) throws IOException {
        if (mobile != null && mobile.length() == 11) {
            gen.writeString(mobile.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2"));
        } else {
            gen.writeString(mobile);
        }
    }
}

// 在DTO中使用
public class UserDTO {
    private String userId;
    
    @JsonSerialize(using = MobileDesensitizer.class)
    private String mobile; // 序列化时自动脱敏
    
    private String username;
    // 省略getter/setter
}

// 日志输出效果：mobile=138****1234
log.info("用户登录成功，用户信息={}", userDTO);

import ch.qos.logback.classic.pattern.ClassicConverter;
import ch.qos.logback.classic.spi.ILoggingEvent;
import java.util.regex.Pattern;

// 日志全局脱敏转换器：匹配手机号、身份证号
public class LogDesensitizerConverter extends ClassicConverter {
    // 手机号正则：11位数字
    private static final Pattern MOBILE_PATTERN = Pattern.compile("1[3-9]\\d{9}");
    // 身份证号正则：18位（含X）
    private static final Pattern ID_CARD_PATTERN = Pattern.compile("\\d{17}[0-9Xx]");

    @Override
    public String convert(ILoggingEvent event) {
        String message = event.getMessage();
        if (message == null) {
            return "";
        }
        // 手机号脱敏
        message = MOBILE_PATTERN.matcher(message).replaceAll("****");
        // 身份证号脱敏（保留前6后4）
        message = ID_CARD_PATTERN.matcher(message).replaceAll("$1****$2");
        return message;
    }
}

// 在logback-spring.xml中配置
<conversionRule conversionWord="msg" converterClass="com.demo.log.LogDesensitizerConverter" />