SpringBoot中构建生产级日志系统的优雅指南

一、需求描述

在实际开发中，日志系统需要满足哪些需求？下面这些点基本是绕不开的：

• 区分日志级别：DEBUG/INFO/WARN/ERROR 各司其职，别混为一谈
• 性能友好：避免日志序列化带来的额外开销，同时支持异步输出
• 链路追踪：一次请求能全链路追踪，依赖一个 RequestId 就能串起来
• 敏感信息脱敏：手机号、身份证这类敏感数据得自动打码
• 日志分类：业务日志、错误日志、慢 SQL 日志最好分开存储，方便排查
• 输出规范：JSON 格式是标配，便于接入 ELK 做采集和分析
• 开发/生产环境差异化：开发环境直接输出到控制台，生产环境则落地到文件

这些需求看似琐碎，但落到工程实践里，就是一套完整的体系。接下来咱们逐步拆解，看看代码怎么落地。

二、详细步骤与代码实现

1. 添加依赖

先把基础依赖加进来。别小看这一步，少了 disruptor，异步日志的性能提升就大打折扣了。

    
        org.springframework.boot
        spring-boot-starter-web
    
    
    
        com.lmax
        disruptor
        3.4.4
    
    
    
        org.springframework.cloud
        spring-cloud-starter-sleuth
        3.1.5
    
    
    
        org.projectlombok
        lombok
        true
    

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）

Logback 的配置是核心。这里我们做了几件事：彩色控制台输出、普通日志文件、错误日志单独文件、业务日志独立文件，并且全部接入了异步输出（AsyncAppender）。注意那个 JSON 日志格式，直接给 ELK 用的。

    
    
    
    
    
    
    
    
    
    
    
    
        
            ${CONSOLE_LOG_PATTERN}
            UTF-8
        
    
    
    
        0
        1024
        
    
    
    
        ${LOG_PATH}/${APP_NAME}.log
        
            ${LOG_PATH}/${APP_NAME}.%d{yyyy-MM-dd}.log
            30
            10GB
        
        
            ${FILE_LOG_PATTERN}
            UTF-8
        
    
    
    
        ${LOG_PATH}/${APP_NAME}-error.log
        
            ERROR
        
        
            ${LOG_PATH}/${APP_NAME}-error.%d{yyyy-MM-dd}.log
            90
        
        
            ${FILE_LOG_PATTERN}
            UTF-8
        
    
    
    
        ${LOG_PATH}/biz.log
        
            ${LOG_PATH}/biz.%d{yyyy-MM-dd}.log
            30
        
        
            ${FILE_LOG_PATTERN}
        
    
    
    
        2048
        0
        true
        
    
    
        1024
        
    
    
        1024
        
    
    
    
        
    
    
    
        
        
        
    

4. 日志工具类封装

写一个 LogUtil 工具类，把常见的日志场景封装起来：获取 TraceId、记录业务日志、接口耗时、方法耗时。这样业务代码里只需要一行调用，非常清爽。

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 ja vax.servlet.http.HttpServletRequest;
import ja va.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. 敏感信息脱敏工具

脱敏是合规的硬要求。这里实现了一个递归脱敏工具，能处理 Map、List 嵌套，还能自动识别手机号、身份证等字符串格式并打码。

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 ja vax.annotation.PostConstruct;
import ja va.util.*;
import ja va.util.regex.Pattern;

/**
 * 日志脱敏工具
 */
@Slf4j
@Component
public class DesensitizationUtil {
    
    @Value("${log.sensitive-fields:}")
    private List sensitiveFields;
    
    private static final Set 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 map = (Map) obj;
            Map result = new HashMap<>();
            for (Map.Entry 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