疯人院评价完整示例：3步搞定微服务日志痛点

刚转岗做后端开发时，我盯着屏幕上的报错日志抓狂了整整三天。明明照着教程一行行敲，单元测试全绿，一到生产环境就崩，连个像样的报错提示都没有。这种“看了一堆教程还是不会写项目”的无力感，每个从业务转技术或刚入行的朋友都懂。

问题出在哪？不是代码逻辑，是可观测性。在微服务架构里，一个请求可能穿过网关、用户服务、订单服务、支付服务，最后再回到数据库。中间任何一环断了，你根本不知道断在哪。这时候，你需要一套完整的日志追踪体系，而不是满屏的 System.out.println。

今天这篇文章，不讲虚无缥缈的理论，直接上完整示例。我们围绕“疯人院评价”这个业务场景（假设这是一个医疗心理评估系统的日志模块，用于记录评估过程中的关键数据流转），搭建一套可落地的日志追踪方案。你会看到，如何用标准化工具把混乱的日志理清楚，让排查时间从“小时级”降到“分钟级”。

概念速懂：为什么微服务需要“疯人院式”的日志管理

先别被“疯人院”这个词吓到，这里我们用它比喻高并发、高噪声、数据混乱的日志现场。在单体应用时代，日志文件按天切割，顺序排列，排查问题时 tail -f app.log 就能解决 80% 的问题。但到了微服务时代，情况彻底变了。

痛点一：日志分散。10 个微服务，10 台机器，10 个日志文件。用户报障说“下单失败”，你得登录 5 台机器，找 5 个文件，用 grep 搜同一个 TraceID，还要手动拼接时间戳。这简直是折磨。

痛点二：上下文丢失。日志里只有 ERROR: Order create failed，但没说是哪个用户、哪个订单、哪个上游服务传过来的脏数据。没有上下文，日志就是废纸。

痛点三：噪声太大。正常业务日志、调试日志、异常堆栈混在一起，关键错误被淹没在成千上万条 INFO 级别日志里。

所以，“疯人院评价”在这里其实是一个隐喻：我们需要一个“管理员”（日志系统），把混乱的“病人”（日志条目）分类、归档、标记重点，让“医生”（开发人员）能迅速找到病灶。

核心技术点有三个：

TraceID（追踪 ID）：贯穿整个请求链路的唯一标识，像快递单号，让你能追踪一个请求在所有服务间的流转轨迹。
MDC（Mapped Diagnostic Context）：SLF4J 提供的机制，可以在日志中自动注入线程上下变量（如 TraceID、UserID），不用每次手动拼接。
结构化日志：从纯文本转向 JSON 格式，便于日志收集器（如 Filebeat、Fluentd）解析和检索。

环境准备：别在烂泥地里盖楼

在动手写代码前，确保你的环境是干净的。很多教程直接甩代码，不交代依赖版本，导致读者复制粘贴后报错，这是最大的坑。

技术栈版本：

Java 17+
Spring Boot 3.1+
SLF4J 2.0+（注意：Spring Boot 3.x 已默认集成 Logback 1.4+，与 SLF4J 2.0 兼容）
Maven 3.8+

依赖引入：在 pom.xml 中，确保引入了 Spring Boot Starter Logging。如果你使用 WebFlux（响应式编程），依赖会略有不同，但本文以传统 Spring MVC 为例，这也是目前绝大多数企业微服务的主流选择。

<dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-logging</artifactId></dependency><!-- 如果需要 OpenTelemetry 自动注入 TraceID，可引入以下依赖 --><dependency><groupId>io.opentelemetry</groupId><artifactId>opentelemetry-spring-boot-starter</artifactId><version>1.31.0</version></dependency>
</dependencies>

关键配置：打开 application.yml，配置日志级别和格式。注意，生产环境建议设为 INFO，开发环境可设为 DEBUG。

logging:level:root: INFOcom.psychiatric.hospital: DEBUG # 替换为你的包名pattern:# 自定义日志格式，包含 TraceID 占位符console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"file: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} [%X{traceId}] - %msg%n"

这里 %X{traceId} 是关键，它从 MDC 中获取 traceId 并打印到日志里。如果 MDC 里没有这个 key，它会打印空字符串。

核心语法：MDC 与 TraceID 的注入原理

很多教程告诉你“要加 TraceID”，但没告诉你怎么加。手动在每行日志里 log.info("xxx, traceId={}", traceId) 是反模式，既冗余又容易漏。

正确的做法是利用 MDC 和 拦截器（Interceptor）。

原理简述：

请求进入 Gateway 或 Controller 时，生成一个全局唯一的 TraceID（如 UUID）。
将 TraceID 存入 MDC（基于 ThreadLocal）。
在调用链中，通过 HTTP Header 将 TraceID 传递给下游服务。
下游服务接收 Header，写入本地 MDC。
日志框架在打印日志时，自动从 MDC 读取 TraceID 并注入到日志模板中。
请求结束，必须清理 MDC，防止线程池复用导致的数据污染。

核心代码片段：

import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;@Component
public class TraceIdInterceptor implements HandlerInterceptor {private static final String TRACE_ID_KEY = "traceId";private static final String TRACE_ID_HEADER = "X-Trace-Id";@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {// 1. 从 Header 获取 TraceID，如果没有则生成新的String traceId = request.getHeader(TRACE_ID_HEADER);if (traceId == null || traceId.isEmpty()) {traceId = java.util.UUID.randomUUID().toString().replace("-", "");}// 2. 放入 MDC，供日志框架使用MDC.put(TRACE_ID_KEY, traceId);// 3. 回写 Header，便于后续排查response.setHeader(TRACE_ID_HEADER, traceId);return true;}@Overridepublic void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {// 4. 关键！请求结束后清理 MDC，防止线程池复用导致 TraceID 串号MDC.clear();}
}

注册拦截器：

@Configuration
public class WebConfig implements WebMvcConfigurer {@Autowiredprivate TraceIdInterceptor traceIdInterceptor;@Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(traceIdInterceptor).addPathPatterns("/**");}
}

下游服务如何接收？ 在 Feign Client 或 RestTemplate 的拦截器中，从当前 MDC 读取 TraceID，并放入 outgoing Header。这样，整个微服务链路的 TraceID 就串起来了。

完整代码示例：疯人院评价系统日志实战

假设我们有一个“疯人院评价”服务，接收患者评估数据，调用“诊断服务”获取初步结论，最后存入数据库。我们将实现一个完整的、可运行的日志追踪示例。

场景：

前端发起评估请求，携带患者 ID。
评价服务接收请求，记录开始时间。
调用诊断服务（模拟 Feign 调用）。
诊断服务返回结果，评价服务记录耗时。
存入数据库，记录最终状态。

Controller 层：

@RestController
@RequestMapping("/evaluation")
public class EvaluationController {private final Logger log = LoggerFactory.getLogger(EvaluationController.class);@Autowiredprivate EvaluationService evaluationService;@PostMapping("/submit")public ResponseEntity<String> submitEvaluation(@RequestBody EvaluationRequest request) {// MDC 中已有 traceId，无需手动打印log.info("收到评估请求，患者ID: {}, 评估类型: {}", request.getPatientId(), request.getType());try {EvaluationResult result = evaluationService.processEvaluation(request);log.info("评估完成，患者ID: {}, 结果状态: {}", request.getPatientId(), result.getStatus());return ResponseEntity.ok("评估成功");} catch (Exception e) {// 异常日志必须打印完整堆栈，且包含上下文log.error("评估失败，患者ID: {}", request.getPatientId(), e);return ResponseEntity.status(500).body("评估失败: " + e.getMessage());}}
}

Service 层（核心逻辑）：

@Service
public class EvaluationService {private final Logger log = LoggerFactory.getLogger(EvaluationService.class);@Autowiredprivate DiagnosisFeignClient diagnosisClient; // 假设的 Feign 客户端@Autowiredprivate EvaluationRepository repository;public EvaluationResult processEvaluation(EvaluationRequest request) {long startTime = System.currentTimeMillis();// 1. 调用下游诊断服务log.debug("开始调用诊断服务，患者ID: {}", request.getPatientId());DiagnosisResponse diagnosis = diagnosisClient.getDiagnosis(request.getPatientId());// 2. 判断诊断结果if (diagnosis == null || !diagnosis.isValid()) {log.warn("诊断服务返回无效数据，患者ID: {}", request.getPatientId());throw new BusinessException("诊断数据无效");}// 3. 构建评价对象EvaluationResult result = new EvaluationResult();result.setPatientId(request.getPatientId());result.setDiagnosisCode(diagnosis.getCode());result.setRiskLevel(diagnosis.getRiskLevel());// 4. 持久化repository.save(result);long duration = System.currentTimeMillis() - startTime;// 关键：记录耗时，便于性能分析log.info("评估流程结束，患者ID: {}, 耗时: {}ms, 风险等级: {}", request.getPatientId(), duration, result.getRiskLevel());return result;}
}

Feign 拦截器（传递 TraceID）：

@Component
public class FeignTraceInterceptor implements RequestInterceptor {@Overridepublic void apply(RequestTemplate template) {// 从 MDC 获取 TraceIDString traceId = MDC.get("traceId");if (traceId != null) {template.header("X-Trace-Id", traceId);}}
}

运行效果：启动服务，发送一个 POST 请求到 /evaluation/submit。在控制台，你会看到类似以下的日志：

2023-10-27 10:00:01.123 [http-nio-8080-exec-1] INFO  c.p.h.e.EvaluationController - 收到评估请求，患者ID: P123, 评估类型: ANXIETY
2023-10-27 10:00:01.150 [http-nio-8080-exec-1] DEBUG c.p.h.e.EvaluationService - 开始调用诊断服务，患者ID: P123
2023-10-27 10:00:02.500 [http-nio-8080-exec-1] INFO  c.p.h.e.EvaluationService - 评估流程结束，患者ID: P123, 耗时: 1377ms, 风险等级: HIGH
2023-10-27 10:00:02.501 [http-nio-8080-exec-1] INFO  c.p.h.e.EvaluationController - 评估完成，患者ID: P123, 结果状态: SUCCESS

所有日志行都带有相同的线程名和隐式的 TraceID（如果在日志模板中配置了 %X{traceId}，它会显示在日志行中）。如果发生异常，log.error 会打印完整堆栈，并且 TraceID 依然在 MDC 中，你可以用这个 ID 去 Elasticsearch 中检索整个链路的所有日志。

常见报错：别踩这些坑

坑一：TraceID 为空。现象：日志里 TraceID 显示为空或 null。原因：

拦截器没有正确注册。
MDC 的 key 名称与日志模板中的 %X{key} 不一致。
在非 Web 环境（如定时任务、MQ 消费者）中，MDC 没有被初始化。解决：检查 application.yml 中的日志格式，确保 key 一致。对于非 Web 入口，需在代码入口手动 MDC.put。

坑二：线程池导致 TraceID 串号。现象：A 用户的请求日志里出现了 B 用户的 TraceID。原因：MDC.clear() 没有在 afterCompletion 中调用，或者在线程池任务中复用了线程，但没有清理 MDC。解决：

确保拦截器的 afterCompletion 中调用 MDC.clear()。
对于异步任务（@Async），需要在任务开始处重新设置 MDC，或使用 TaskDecorator 在提交任务时捕获 MDC 上下文，在任务执行时恢复。

@Component
public class MdcTaskDecorator implements TaskDecorator {@Overridepublic Runnable decorate(Runnable runnable) {Map<String, String> context = MDC.getCopyOfContextMap();return () -> {try {if (context != null) {MDC.setContextMap(context);}runnable.run();} finally {MDC.clear();}};}
}

坑三：日志量大，磁盘打满。现象：生产环境磁盘空间不足，服务崩溃。原因：日志级别设为 DEBUG，且未配置日志滚动策略。解决：

生产环境设为 INFO。
配置 Logback 的 RollingFileAppender，按天或按大小切割，并设置最大历史保留天数。
接入 ELK 或 Loki 等日志系统，本地只保留最近 3-7 天的日志。

坑四：敏感信息泄露。现象：日志中打印了患者的身份证号、病历详情等敏感信息。原因：开发者为了方便调试，直接打印了 Request 对象。解决：

建立日志规范，禁止打印敏感字段。
在序列化日志对象时，使用 @JsonIgnore 或自定义 Serializer 对敏感字段脱敏（如 138****1234）。
代码审查时，重点检查日志打印语句。

小结：从“疯人院”到“秩序”

微服务时代的日志管理，核心不是“记录更多”，而是“结构化”和“可追踪”。通过引入 TraceID、MDC 和结构化日志，我们可以将混乱的日志现场变得井然有序。

回顾一下我们做了什么：

理解痛点：微服务日志分散、上下文丢失、噪声大。
环境准备：确保 Spring Boot 和 SLF4J 版本兼容，配置日志格式。
核心语法：利用拦截器注入 TraceID 到 MDC，通过 Feign 拦截器传递 TraceID。
完整示例：在“疯人院评价”场景中，实现了从 Controller 到 Service 到下游服务的完整日志追踪链路。
避坑指南：解决了 TraceID 为空、线程池串号、磁盘打满、敏感信息泄露等常见问题。

这套方案不仅适用于“疯人院评价”系统，也适用于任何微服务架构。你可以直接参考 Spring Cloud 官方源码仓库中的 spring-cloud-sleuth（虽然 Sleuth 已归档，但 OpenTelemetry 是新的标准）或 opentelemetry-java-instrumentation 项目，它们提供了更成熟的自动注入能力。

技术没有银弹，但好的日志体系能让你的排查效率提升十倍。不要等到线上出事了才后悔没做好日志规范，现在就开始改造你的项目吧。

你在项目里踩过这个坑吗？评论区聊聊，比如你是怎么解决线程池 MDC 串号问题的，或者你们团队有什么独特的日志脱敏技巧。互相交流，才能少踩坑。