当前位置:

首页 > 编程开发 > SpringBoot中全局日志记录与请求链路追踪实战教学

SpringBoot中全局日志记录与请求链路追踪实战教学

通过MDC与Filter为每个请求生成唯一TraceId,从而实现对请求的全链路追踪,便于快速定位问题;利用AOP自动记录接口入参、出参及耗时,有效减少手动日志,提升开发效率;结合敏感信息脱敏,保障数据安全,全面增强系统可观测性。

本文目录

    试想这样一个场景:用户反馈下单失败,客服丢给你一个订单号。你一头扎进日志,开始大海捞针——

    • 如果每个请求没有唯一标识,就得在一堆并发线程里手动拼凑属于那个用户的那一次调用,效率低到令人崩溃。
    • 如果接口跨了多个服务,还要跨机器、跨进程,把零散的日志片段像拼图一样拼起来,简直是一场噩梦。

    问题的症结很明确:我们需要一套机制,让日志不仅能“看”,还能“追”。通俗点讲,就是给每个请求发一张“身份证”,贯穿整个调用链路,自动记录它的来龙去脉,同时把敏感信息藏好——这其实是构建可观测性系统的第一步,也是生产级应用的基础设施。

    SpringBoot中全局日志记录与请求链路追踪实战教学

    一、 为什么需要全局日志和链路追踪?

    回到刚才的场景:用户反馈下单失败,客服给你一个订单号。你开始查日志……

    • 不带唯一标识:一堆杂乱的并发请求中,找到属于那个用户的那一次请求,如同大海捞针。
    • 接口多、服务多:涉及多个服务调用时,需要跨机器拼接日志片段,耗时又容易出错。

    为了解决这些问题,我们需要两个核心能力:

    1. 链路追踪 (TraceId):为每个请求生成唯一的 ID,贯穿整个处理流程,串联起所有相关日志。
    2. 全局日志:自动记录接口入参、出参、耗时,减少手动写 log.info(...) 的工作量。

    二、 核心组件:MDC (Mapped Diagnostic Context)

    MDC 是 Slf4j 提供的一个机制,它本质上是一个线程安全的 ThreadLocal。我们可以往里面放入键值对(比如 TraceId),然后在 Logback 配置中通过 %X{key} 的格式输出。这个设计很巧妙——它让日志与线程上下文绑定,自动实现“同一请求、同一 ID”的效果。

    1. 生成 TraceId

    需要写一个工具类来管理 TraceId,核心逻辑就是围绕 MDC 的 get、put、remove。

    public class TraceIdUtil {
        
        private static final String TRACE_ID_KEY = "traceId";
    
        /**
         * 获取当前线程的 TraceId
         */
        public static String getTraceId() {
            String traceId = MDC.get(TRACE_ID_KEY);
            return StringUtils.isEmpty(traceId) ? "" : traceId;
        }
    
        /**
         * 设置 TraceId
         */
        public static void setTraceId(String traceId) {
            MDC.put(TRACE_ID_KEY, traceId);
        }
    
        /**
         * 清除 TraceId (非常重要,防止线程池复用导致数据污染)
         */
        public static void removeTraceId() {
            MDC.remove(TRACE_ID_KEY);
        }
    }
    

    2. 通过 Filter 拦截请求并设置 TraceId

    在请求进入 Controller 之前,通过一个 Filter 来生成并设置 TraceId。这里有个细节:如果上游网关已经传了 TraceId(比如通过 HTTP 头 X-Trace-Id),我们直接复用;否则自己生成一个 UUID。

    @Slf4j
    @Component
    @Order(Ordered.HIGHEST_PRECEDENCE) // 确保最先执行
    public class TraceIdFilter implements Filter {
    
        @Override
        public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
            HttpServletRequest httpRequest = (HttpServletRequest) request;
            
            try {
                // 尝试从请求头获取 TraceId(适用于网关传递过来的场景)
                String traceId = httpRequest.getHeader("X-Trace-Id");
                if (StringUtils.isEmpty(traceId)) {
                    traceId = UUID.randomUUID().toString().replace("-", "");
                }
                TraceIdUtil.setTraceId(traceId);
                
                chain.doFilter(request, response);
            } finally {
                // 务必清理,防止内存泄漏或线程池复用导致的脏数据
                TraceIdUtil.removeTraceId();
            }
        }
    }
    

    3. 配置 Logback 输出格式

    在 pattern 中加入 %X{traceId},日志就会自动带上这个 ID。

    
        
        
            
                ${LOG_PATTERN}
            
        
        
            
        
    

    配置完成后,日志输出会变成类似这样:2023-10-01 12:00:00.001 [http-nio-8080-exec-1] [a1b2c3d4e5f6...] INFO c.e.controller.UserController - User created successfully。一眼就能看出哪个请求对应哪条日志,排查问题的效率直接翻倍。

    三、 AOP 实现全局接口日志

    MDC 帮我们串联了日志,但还有一个痛点:每个接口的入参、出参、耗时,难道都要手动写 log.info?当然不——用 AOP 一把梭,既优雅又省力。

    1. 引入依赖与启用 AOP

    确保引入了 spring-boot-starter-aop,并在启动类或配置类上加上 @EnableAspectJAutoProxy(Spring Boot 通常自动配置)。

    2. 编写日志切面

    定义一个切面,拦截所有 Controller 层的 public 方法。核心逻辑:在方法执行前后记录请求信息与响应信息,并计算耗时。

    @Slf4j
    @Aspect
    @Component
    public class ControllerLogAspect {
    
        // 定义切点:拦截 Controller 包下的所有方法
        @Pointcut("execution(public * com.example..controller..*.*(..))")
        public void controllerLog() {}
    
        @Around("controllerLog()")
        public Object doAround(ProceedingJoinPoint joinPoint) throws Throwable {
            long startTime = System.currentTimeMillis();
            
            // 获取请求信息
            ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
            HttpServletRequest request = attributes.getRequest();
            
            // 构建日志对象
            LogInfo logInfo = new LogInfo();
            logInfo.setTraceId(TraceIdUtil.getTraceId());
            logInfo.setMethod(request.getMethod());
            logInfo.setUrl(request.getRequestURI());
            logInfo.setIp(request.getRemoteAddr());
            logInfo.setClassMethod(joinPoint.getSignature().getDeclaringTypeName() + "." + joinPoint.getSignature().getName());
            
            // 获取入参,过滤掉 HttpServletRequest、HttpServletResponse 等无法序列化的参数
            Object[] args = joinPoint.getArgs();
            Object[] logArgs = Arrays.stream(args)
                    .filter(arg -> !(arg instanceof HttpServletRequest) && !(arg instanceof HttpServletResponse))
                    .toArray();
            logInfo.setArgs(logArgs);
            
            // 打印入参日志
            log.info("Request Info: {}", JSON.toJSONString(logInfo));
    
            Object result;
            try {
                result = joinPoint.proceed();
            } catch (Exception e) {
                // 记录异常日志(通常由全局异常处理器处理,这里也可以记录一份用于审计)
                log.error("Controller Exception: ", e);
                throw e;
            }
            
            // 计算耗时
            long costTime = System.currentTimeMillis() - startTime;
            logInfo.setCostTime(costTime);
            logInfo.setResult(result);
            
            // 打印出参日志
            log.info("Response Info ({}ms): {}", costTime, JSON.toJSONString(logInfo));
            
            return result;
        }
    
        @Data
        public static class LogInfo {
            private String traceId;
            private String method;
            private String url;
            private String ip;
            private String classMethod;
            private Object[] args;
            private Object result;
            private Long costTime;
        }
    }
    

    四、 敏感信息脱敏

    生产环境里,明文密码、身份证号、手机号等敏感信息绝对不能出现在日志里。怎么做?一种常见方案是在序列化输出时做脱敏处理,比如用 Jackson 自定义序列化器。

    自定义脱敏序列化器 (以 Jackson 为例)

    public class SensitiveDataSerializer extends JsonSerializer {
        @Override
        public void serialize(String value, JsonGenerator gen, SerializerProvider serializers) throws IOException {
            if (StringUtils.isEmpty(value)) {
                gen.writeNull();
                return;
            }
            // 简单的脱敏逻辑:保留前 3 后 4,中间星号
            if (value.length() > 8) {
                gen.writeString(value.substring(0, 3) + "****" + value.substring(value.length() - 4));
            } else {
                gen.writeString("****");
            }
        }
    }
    

    使用方式:在 DTO 的敏感字段上添加注解

    public class UserDTO {
        
        @JsonSerialize(using = SensitiveDataSerializer.class)
        private String phone;
        
        // ...
    }
    

    如果想更通用,也可以在 AOP 中通过正则替换整个 JSON 字符串后再打印,具体看项目需求。

    五、 最佳实践

    1. 异步日志 (AsyncAppender):生产环境日志量巨大,同步打印日志会阻塞业务线程。务必在 Logback 配置中使用 AsyncAppender 包装 Console 和 File Appender。
    2. 线程池透传 MDC:如果你的代码使用了 @Async 或自定义线程池,MDC 的值不会自动传递到子线程。需要实现 TaskDecorator 或 ThreadPoolTaskExecutor 的包装类,在提交任务时拷贝 MDC 上下文,执行完毕后恢复。
    3. 避免打印大对象:如果入参包含大文件流(MultipartFile)或巨大的列表,不要直接打印 JSON,会撑爆日志文件。在 AOP 中判断参数类型进行过滤。
    4. 日志级别控制:不要把所有日志都设为 INFO。开发环境可以是 DEBUG,生产环境建议 INFO 或 WARN,Error 必须报警。

    六、 总结

    通过 MDC + Filter + AOP 这套组合拳,我们实现了三个关键目标:

    1. 全链路追踪:每个请求都有唯一的 TraceId,串联起所有相关日志。
    2. 自动审计:无需修改业务代码,自动记录接口出入参和耗时。
    3. 数据安全:敏感信息脱敏,避免合规风险。

    这套方案已经是生产级 SpringBoot 应用的标配。掌握它,就等于给系统的可观测性打下了坚实的基础——排查问题时,你不再是那个“大海捞针”的苦命人,而是拿着 TraceId 精准定位问题的专家。

    本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系bd@zhengruan.com
    作者最新文章
    编程开发
    相关文章 更多
    SpringBoot中构建生产级日志系统的优雅指南
    SpringBoot中构建生产级日志系统的优雅指南

    基于SpringBoot构建生产级日志系统,需满足级别区分、性能优化、链路追踪、敏感信息脱敏、分类输出、JSON格式及环境差异化等需求。通过添加依赖、配置Logback异步输出、封装日志工具类及递归脱敏工具,实现高效规范的日志管理。

    QQ影音怎么加速播放视频课程
    QQ影音怎么加速播放视频课程

    播放时右键选播放速度,或点控制条倍速,1.25 到 1.5 倍看课最舒服;公式代码类内容别超过 1.25 倍。

    企业微信创建企业提示失败怎么办 实名与填写检查
    企业微信创建企业提示失败怎么办 实名与填写检查

    先看提示属于哪类:名称占用就加后缀,实名不一致就重填本人信息,证件不清晰就重拍。统一社会信用代码逐位核对,连续三次失败别改材料重投,直接联系客服人工核。

    Modern Web Guidance 的 legacy-scan 反转建议应该怎样判断?
    Modern Web Guidance 的 legacy-scan 反转建议应该怎样判断?

    说明源码提交对字符串、生成器和数组的识别边界,以及扫描命令与发行包核验限制。

    Codex 0.170.0 正式版的语音与连接更新,适用范围有哪些限制?
    Codex 0.170.0 正式版的语音与连接更新,适用范围有哪些限制?

    0.170.0 的语音更新限于终端通话协商能力的明确新增,同名工具服务器跨环境支持仍标注实验性质;连接部分则修复大请求回退、认证竞态和云端重连等具体问题。这份正式版公告不足以证明所有账户、所有客户端都已具备完整语音功能。

    Hy4 flash 三种权重怎么选,安装和授权要注意哪些条件?
    Hy4 flash 三种权重怎么选,安装和授权要注意哪些条件?

    了解Hy4 flash、FP8与base的适用任务,阅读官方安装及图文代码,并核对资源和MaaS许可条件。

    OpenAI Python SDK 3.55.0 升级看点:Live MCP 服务配置与预算接口变化
    OpenAI Python SDK 3.55.0 升级看点:Live MCP 服务配置与预算接口变化

    OpenAI Python SDK 3.55.0 升级看点:Live MCP 服务配置与预算接口变化。说明已核实的更新范围、类型兼容性和本地版本确认方法。

    OpenAI Java SDK 4.108.0 的两项新增能力适合哪些项目?
    OpenAI Java SDK 4.108.0 的两项新增能力适合哪些项目?

    OpenAI Java SDK 4.108.0 面向 Live MCP 工具接入与 Managed Agents 预算状态处理,说明新增模型、事件含义、正式发布范围和适用限制。

    Free Claude Code 6.19.37 如何兼顾网页搜索与普通工具调用?
    Free Claude Code 6.19.37 如何兼顾网页搜索与普通工具调用?

    Free Claude Code 6.19.37 在自动搜索时保留客户端工具及选择条件,代理执行搜索后仍返回普通调用。说明适用场景、历史信息保留、请求约束与第三方项目的版本边界。

    Google GenAI Go SDK 1.78.0 的 v1beta 配置优先级怎样判断?
    Google GenAI Go SDK 1.78.0 的 v1beta 配置优先级怎样判断?

    Google GenAI Go SDK 1.78.0 将 Gemini Developer API 默认改为 v1,可用 HTTPOptions.APIVersion 或环境变量保留 v1beta,Vertex AI 默认值不变。

    查看更多
    精品专题 更多
    装机必备
    装机必备

    正软商城装机必备专区,精选办公、浏览器、安全防护、影音播放、压缩解压、设计创作和系统工具等电脑常用正版软件,帮助用户快速完成新电脑软件配置。

    Windows
    Windows

    正软商城Windows软件专区,汇集适用于Windows电脑的办公、设计、安全防护、影音播放、开发工具和系统优化软件,提供软件介绍、系统要求、正版授权及购买下载服务。

    PDF教程
    PDF教程

    正软商城PDF教程频道提供PDF编辑、转换、合并、拆分、压缩及格式处理方法,同时介绍常用PDF软件和工具的使用技巧。

    Mac软件 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    Aperty macOS版
    Aperty macOS版
    macOS

    Aperty 是 Skylum 推出的 AI 人像修图软件,支持自然肤质修饰、瑕疵处理、面部与身体调整、预设及批量同步。

    WINDOWS 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    PixTV 网页版
    PixTV 网页版
    Windows

    PixTV 是一款在浏览器中使用的 AI 视觉内容创作平台,提供图片、视频、音频、文字生成、AI 分镜、局部重绘、提示词反推和无限画布等工具,适合短剧、漫剧、广告及社交媒体内容制作。