Java 后端 / 系统课时
设计结构化日志
设计结构化日志
本课把普通文本日志改造成稳定的 JSON 事件,并为每次请求补充请求标识、业务字段和脱敏规则。完成后,日志可以被集中采集、按字段查询,并能在排障时串起同一次请求的关键步骤。
学习目标
- 设计适合检索和聚合的结构化日志字段
- 使用 MDC 为请求注入并传递统一请求标识
- 配置 JSON 输出、日志级别和敏感字段脱敏
先确定日志事件模型
结构化日志不是“把一整句文本放进 JSON”,而是把事件拆成稳定字段。至少应包含时间、级别、服务名、环境、线程、记录器、事件名称和 requestId;业务日志再补充 orderId、customerId、金额或结果码等可检索字段。
字段名一旦进入查询、告警和仪表盘,就应保持稳定。事件名称建议使用机器友好的固定值,例如 order_created,而把自然语言说明留在文档中。密码、令牌、证件号和完整银行卡号不得进入日志。

配置 JSON 输出与日志级别
先加入 Logstash Logback Encoder,它能把 MDC 和结构化参数写入 JSON。示例版本适用于 Spring Boot 3 常见的 Logback 1.4 环境。
<dependency>
<groupId>net.logstash.logback</groupId>
<artifactId>logstash-logback-encoder</artifactId>
<version>7.4</version>
</dependency>在 application.yml 中按包控制级别,避免把根级别长期设为 DEBUG。生产环境通常保留业务包 INFO,只对短期排障的目标包临时提升级别。
logging:
level:
root: INFO
com.example.order: INFO
org.springframework.web: WARN再创建 src/main/resources/logback-spring.xml。配置将日志写到标准输出,并对常见敏感字段执行掩码。
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<springProperty
scope="context"
name="appName"
source="spring.application.name"
defaultValue="order-service"/>
<appender name="JSON_STDOUT"
class="ch.qos.logback.core.ConsoleAppender">
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<customFields>
{"service":"${appName}","environment":"${APP_ENV:-local}"}
</customFields>
<includeMdc>true</includeMdc>
<jsonGeneratorDecorator
class="net.logstash.logback.mask.MaskingJsonGeneratorDecorator">
<defaultMask>***</defaultMask>
<path>password</path>
<path>token</path>
<path>authorization</path>
</jsonGeneratorDecorator>
</encoder>
</appender>
<root level="INFO">
<appender-ref ref="JSON_STDOUT"/>
</root>
</configuration>配置生效后,每条日志独占一行 JSON,便于采集器按行读取。掩码规则只能作为最后一道防线,业务代码仍不应主动记录完整请求对象或认证头。
注入并清理请求标识
过滤器优先接收上游传来的 X-Request-Id;值缺失或格式不合法时生成 UUID。请求结束后必须移除 MDC,防止线程复用导致标识串到下一次请求。
package com.example.logging;
import java.io.IOException;
import java.util.Optional;
import java.util.UUID;
import java.util.regex.Pattern;
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;
@Component
public class RequestIdFilter extends OncePerRequestFilter {
private static final String HEADER = "X-Request-Id";
private static final String MDC_KEY = "requestId";
private static final Pattern SAFE_VALUE =
Pattern.compile("[A-Za-z0-9._-]{8,64}");
@Override
protected void doFilterInternal(
HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain)
throws ServletException, IOException {
String requestId = Optional.ofNullable(request.getHeader(HEADER))
.filter(value -> SAFE_VALUE.matcher(value).matches())
.orElseGet(() -> UUID.randomUUID().toString());
MDC.put(MDC_KEY, requestId);
response.setHeader(HEADER, requestId);
try {
filterChain.doFilter(request, response);
} finally {
// Web 线程会复用,必须清理本次请求写入的上下文。
MDC.remove(MDC_KEY);
}
}
}MDC 默认依赖当前线程。若任务切换到 @Async、线程池或响应式链路,需要显式传播上下文,不能假设请求线程中的标识会自动出现在线程池日志里。
记录业务字段而不是拼接文本
使用结构化参数记录业务键值,事件名保持固定。下面的服务类不会记录密码、令牌或完整用户对象,只输出排障和统计真正需要的字段。
package com.example.order;
import static net.logstash.logback.argument.StructuredArguments.kv;
import java.math.BigDecimal;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
@Service
public class OrderAuditLogger {
private static final Logger log =
LoggerFactory.getLogger(OrderAuditLogger.class);
public void orderCreated(
long orderId,
long customerId,
BigDecimal amount) {
log.info(
"order_created",
kv("orderId", orderId),
kv("customerId", customerId),
kv("amount", amount));
}
}不要写成 log.info("用户 {} 创建订单 {}", user, order),因为对象的 toString() 可能意外包含手机号、地址或令牌。对金额、状态和结果码等字段,应使用统一名称与数据类型,避免同一个字段有时是数字、有时又是字符串。
运行并检查输出
启动应用后,向任一受保护的接口发送带请求标识的请求。下面以已有的订单查询接口为例:
curl -i -H 'X-Request-Id: req-20260806-0001' http://localhost:<PORT>/api/orders/<ID>预期结果:
HTTP/1.1 200
X-Request-Id: req-20260806-0001
Content-Type: application/json当业务代码记录订单事件时,控制台应出现类似的一行 JSON:
{"@timestamp":"<TIME>","level":"INFO","logger_name":"com.example.order.OrderAuditLogger","message":"order_created","service":"order-service","environment":"local","requestId":"req-20260806-0001","orderId":<ID>,"customerId":<ID>,"amount":99.90}实际时间、端口、ID 和字段顺序可能不同。验证重点是输出可被 JSON 解析、requestId 与响应头一致、业务字段保持独立类型,并且敏感字段不会以明文出现。