Java 日志迁移变更单：从字符串拼接到参数化日志和 MDC traceId

Java 老项目里常见一种日志写法：把订单号、用户号、请求体直接用字符串拼起来，再交给日志框架输出。它能快速定位问题，但接口量和访问量上来后，问题会越来越明显：低级别日志被关闭时仍然先拼字符串，敏感字段容易被整段打出，跨服务排查时还缺少 traceId。

这篇按“迁移变更单”的方式，把日志写法从字符串拼接迁到 SLF4J 参数化日志，并补上 MDC traceId 和回归检查。目标不是重做日志平台，而是先把应用代码里的日志入口变得可控。

升级范围：先改业务日志写法，再补 traceId

第一轮迁移建议只覆盖三类日志：接口入口日志、关键业务状态日志、异常日志。不要一上来全量重写所有 debug 行，否则很容易把原本有用的排障信息改没。

迁移后的目标链路是：

HTTP 请求
  -> Filter 生成 traceId
  -> MDC 保存 traceId
  -> 业务代码使用参数化日志
  -> 日志模板输出 traceId 和关键字段

本次迁移只要求每条关键日志做到三点：字段名清楚、敏感字段先脱敏、同一次请求能用 traceId 串起来。

变更表：旧日志和新日志如何对应

旧代码风险：字符串拼接为什么会越写越乱

先看一段典型旧代码：

log.info("create order user=" + userId
        + ", order=" + orderId
        + ", amount=" + amount
        + ", body=" + requestBody);

try {
    orderService.create(orderId, userId, amount);
} catch (Exception e) {
    log.error("create order failed: " + e.getMessage());
}

这段代码有三个风险。第一，即使某个日志级别被关闭，字符串拼接已经发生了；第二，请求体可能包含手机号、地址、证件号等敏感字段；第三，异常日志只打印 message，真正的调用栈没有留下。

下面这张图把旧日志风险拆成检查项：拼接成本、敏感字段、缺 traceId、错误栈缺失。

新写法：参数化日志、脱敏字段和 MDC

迁移第一步，是把字符串拼接改成参数化日志：

log.info("create order userId={} orderId={} amount={}",
        maskUserId(userId), orderId, amount);

try {
    orderService.create(orderId, userId, amount);
} catch (Exception e) {
    log.error("create order failed orderId={} userId={}",
            orderId, maskUserId(userId), e);
}

注意异常对象要作为最后一个参数传入，这样日志框架才能保留完整堆栈。不要只取 e.getMessage()，否则后续排查只能看到一句错误信息。

第二步，在请求入口设置 traceId。下面示例用 Servlet Filter 表达核心逻辑：

public final class TraceIdFilter implements Filter {
    private static final String TRACE_ID = "traceId";

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        String traceId = UUID.randomUUID().toString().replace("-", "");
        MDC.put(TRACE_ID, traceId);
        try {
            chain.doFilter(request, response);
        } finally {
            MDC.remove(TRACE_ID);
        }
    }
}

如果使用 Logback，可以在日志模板中输出 MDC 字段：

%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level traceId=%X{traceId} %logger - %msg%n

这样业务代码不用层层传 traceId，日志里仍然能看到同一次请求的链路标识。

回归检查：确认性能、链路和错误栈都没丢

迁移完成后，至少做四组检查：关闭 info 级别时确认没有无意义拼接，正常请求确认 traceId 存在，异常请求确认错误栈完整，敏感字段确认已经脱敏。

可以准备下面几条检查命令和日志样例：

# 1. 正常请求
curl -H 'X-User-Id: 13800138000' http://127.0.0.1:8080/orders/1001

# 2. 异常请求
curl http://127.0.0.1:8080/orders/bad-id

# 3. 搜索同一条链路
grep 'traceId=9f2a' app.log

# 4. 检查敏感字段
grep '13800138000' app.log

期望日志类似这样：

2026-06-30 15:20:01.120 [http-nio-8080] INFO  traceId=9f2a7c order.api - create order userId=138****8000 orderId=1001 amount=199
2026-06-30 15:20:04.812 [http-nio-8080] ERROR traceId=9f2a7c order.api - create order failed orderId=bad-id userId=138****8000
java.lang.IllegalArgumentException: invalid order id

如果第一条 grep 能找到同一 traceId 的多行日志，说明链路标识已经串起来；如果第二条 grep 找不到完整手机号，说明脱敏规则生效；如果异常行后面有堆栈，说明错误信息没有在迁移中丢失。

迁移清单：按模块分批推进

最后给一份可执行的迁移清单：

• 先统计高频接口和线上常用排障日志，不要盲目全量替换。
• 把字符串拼接改为 {} 占位符，字段顺序保持和原日志接近。
• 敏感字段统一经过 mask 方法，不直接输出完整手机号、地址、证件号。
• 异常日志保留异常对象作为最后一个参数，保证错误栈可见。
• 在请求入口写入 MDC traceId，并在 finally 中清理。
• 更新日志模板，确认 %X{traceId} 已经出现在实际日志里。
• 用正常请求、异常请求、脱敏检查和 traceId 搜索做回归。

这类迁移最怕只做表面替换。真正有价值的结果，是日志在低成本、可追踪、可脱敏和可排障之间取得平衡。先从关键接口开始迁，确认回归检查过关，再把同一套写法推广到更多模块，会比一次性大改更稳。