架构与系统设计 / 系统课时

链路标识与日志

链路标识与日志

本课解决同一请求跨越过滤器、控制器和业务服务后难以关联日志的问题。完成后,你将为每个请求生成或透传链路标识,输出可检索的结构化日志,并在记录商户、卡号等信息前完成脱敏。

学习目标

  • 使用请求头和 MDC 建立请求级链路标识
  • 采用固定字段输出便于检索的结构化日志
  • 对敏感字段执行最小化记录和统一脱敏

链路标识如何贯穿请求

链路标识通常通过 X-Trace-Id 请求头传入。服务收到请求后先校验该值;缺失或不合法时生成新标识,再写入 MDC。后续日志自动带上同一 traceId,响应头也返回该值,便于调用方报障时提供定位依据。

链路标识与日志上下文流转

MDC 基于线程上下文保存键值。Servlet 容器会复用工作线程,因此必须在 finally 中清理;否则下一次复用该线程的请求可能继承旧标识,造成日志串号。

实现 TraceId 过滤器

下面是可放入 Spring Boot 工程的完整过滤器。它只接受 16~64 位字母、数字、下划线和短横线,防止调用方把换行符或超长内容注入日志。

java
package com.example.pay.logging;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.UUID;
import java.util.regex.Pattern;

@Component
public class TraceIdFilter extends OncePerRequestFilter {
    public static final String HEADER_NAME = "X-Trace-Id";
    public static final String MDC_KEY = "traceId";

    private static final Pattern SAFE_TRACE_ID =
            Pattern.compile("^[A-Za-z0-9_-]{16,64}$");

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain)
            throws ServletException, IOException {

        String traceId = resolveTraceId(request.getHeader(HEADER_NAME));
        MDC.put(MDC_KEY, traceId);
        response.setHeader(HEADER_NAME, traceId);

        try {
            filterChain.doFilter(request, response);
        } finally {
            // Tomcat 会复用线程,请求结束必须清除上下文。
            MDC.remove(MDC_KEY);
        }
    }

    private String resolveTraceId(String candidate) {
        if (candidate != null && SAFE_TRACE_ID.matcher(candidate).matches()) {
            return candidate;
        }
        return UUID.randomUUID().toString().replace("-", "");
    }
}

该过滤器只覆盖当前服务内的 Servlet 调用。调用下游 HTTP 服务时,还需要在客户端拦截器中把 MDC 里的 traceId 写回 X-Trace-Id 请求头;消息队列则应把它放入消息头,并在消费完成后同样清理 MDC。

配置结构化日志格式

结构化日志的关键不是输出更多文字,而是让时间、级别、链路标识、业务字段和消息拥有固定键名。下面配置使用 Logback 的 %kvp 输出 SLF4J 2 的键值字段。

xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>

    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>time=%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX} level=%-5level traceId=%X{traceId:-} %kvp logger=%logger message=%msg%n</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

把文件保存为 src/main/resources/logback-spring.xml 后重启应用。验证时应看到每行都具有 time、level、traceId、logger 和 message 字段;通过 addKeyValue 添加的业务字段会出现在 %kvp 位置。

记录业务日志并脱敏

日志只记录定位问题所需的最小信息。订单号、请求标识通常可以完整记录;银行卡号、手机号、证件号、密钥、验证码和完整请求体不应直接写入日志。

下面示例提供统一脱敏函数,并使用 SLF4J 2 的键值日志记录支付受理事件。它是项目代码片段,需与 Spring Web 和前面的过滤器一起运行。

java
package com.example.pay.web;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@RestController
public class LoggingDemoController {
    private static final Logger log =
            LoggerFactory.getLogger(LoggingDemoController.class);

    @GetMapping("/demo/log")
    public Map<String, String> logPayment(
            @RequestParam String merchantNo,
            @RequestParam String cardNo) {

        log.atInfo()
                .addKeyValue("event", "payment.accepted")
                .addKeyValue("merchantNo", maskTail(merchantNo, 4))
                .addKeyValue("cardNo", maskCard(cardNo))
                .log("payment request accepted");

        return Map.of("status", "accepted");
    }

    private static String maskCard(String value) {
        if (value == null || value.length() < 10) {
            return "******";
        }
        return value.substring(0, 6)
                + "******"
                + value.substring(value.length() - 4);
    }

    private static String maskTail(String value, int visibleTail) {
        if (value == null || value.length() <= visibleTail) {
            return "****";
        }
        return "*".repeat(value.length() - visibleTail)
                + value.substring(value.length() - visibleTail);
    }
}

不要依赖开发人员每次手工判断是否脱敏。实际项目应把脱敏函数集中在公共模块,并在日志规范中明确哪些字段允许完整记录、部分记录或完全禁止记录。

验证链路标识与日志

启动应用后,使用固定链路标识调用测试接口:

bash
curl -i \
  -H "X-Trace-Id: trace-demo-20260803" \
  "http://localhost:<PORT>/demo/log?merchantNo=M123456789&cardNo=6222021234567890"

预期 HTTP 响应如下,<PORT> 以实际端口为准:

text
HTTP/1.1 200
X-Trace-Id: trace-demo-20260803
Content-Type: application/json

{"status":"accepted"}

控制台应出现与请求头相同的链路标识,且商户号和卡号已脱敏。时间、线程和类名可能随环境不同。

text
time=<TIME> level=INFO  traceId=trace-demo-20260803 event="payment.accepted" merchantNo="******6789" cardNo="622202******7890" logger=com.example.pay.web.LoggingDemoController message=payment request accepted

再发送不合法的链路标识时,响应头应返回服务端生成的 32 位标识,日志中也应使用该新值,而不是原始非法内容。

日志边界与检查清单

生产日志应避免记录完整请求体和响应体,特别是支付密码、验证码、授权令牌、银行卡安全码与私钥。确需排查报文时,应通过受控开关、字段白名单和短期保留策略处理,而不是永久开启全量打印。

一次请求至少应能通过 traceId、业务事件名、订单号和错误码完成检索。日志消息保持稳定,变化频繁的业务值放入键值字段,便于日志平台聚合与告警。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

链路标识与日志

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通