架构与系统设计 / 系统课时
链路标识与日志
链路标识与日志
本课解决同一请求跨越过滤器、控制器和业务服务后难以关联日志的问题。完成后,你将为每个请求生成或透传链路标识,输出可检索的结构化日志,并在记录商户、卡号等信息前完成脱敏。
学习目标
- 使用请求头和 MDC 建立请求级链路标识
- 采用固定字段输出便于检索的结构化日志
- 对敏感字段执行最小化记录和统一脱敏
链路标识如何贯穿请求
链路标识通常通过 X-Trace-Id 请求头传入。服务收到请求后先校验该值;缺失或不合法时生成新标识,再写入 MDC。后续日志自动带上同一 traceId,响应头也返回该值,便于调用方报障时提供定位依据。

MDC 基于线程上下文保存键值。Servlet 容器会复用工作线程,因此必须在 finally 中清理;否则下一次复用该线程的请求可能继承旧标识,造成日志串号。
实现 TraceId 过滤器
下面是可放入 Spring Boot 工程的完整过滤器。它只接受 16~64 位字母、数字、下划线和短横线,防止调用方把换行符或超长内容注入日志。
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 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 和前面的过滤器一起运行。
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);
}
}不要依赖开发人员每次手工判断是否脱敏。实际项目应把脱敏函数集中在公共模块,并在日志规范中明确哪些字段允许完整记录、部分记录或完全禁止记录。
验证链路标识与日志
启动应用后,使用固定链路标识调用测试接口:
curl -i \
-H "X-Trace-Id: trace-demo-20260803" \
"http://localhost:<PORT>/demo/log?merchantNo=M123456789&cardNo=6222021234567890"预期 HTTP 响应如下,<PORT> 以实际端口为准:
HTTP/1.1 200
X-Trace-Id: trace-demo-20260803
Content-Type: application/json
{"status":"accepted"}控制台应出现与请求头相同的链路标识,且商户号和卡号已脱敏。时间、线程和类名可能随环境不同。
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、业务事件名、订单号和错误码完成检索。日志消息保持稳定,变化频繁的业务值放入键值字段,便于日志平台聚合与告警。