重构与日志：重构日志记录逻辑，提升可观测性

日志这东西，说起来简单，写起来容易，但真正用好它，其实挺难的。

我见过太多项目，日志打印得满天飞，线上出问题的时候，却找不到一条有用的信息。要么是信息太少，根本不知道发生了什么；要么是信息太多，把磁盘撑爆了，关键线索被淹没在汪洋大海里。

说白了，日志不是写给自己看的，是写给未来的「你」和「运维同事」看的。今天我们就聊聊，怎么通过重构，把日志这块烂摊子收拾干净，真正提升系统的可观测性。

1. 日志重构的核心目标

重构日志，不是为了把代码改得更漂亮。我个人习惯，先想清楚目标，再动手。日志重构的核心目标有三个：

• 可搜索性：出问题时，能快速定位到相关日志。
• 可理解性：日志内容，换一个人来看，也能秒懂。
• 可操作性：看到日志，就知道下一步该干什么。

2. 常见日志反模式

在动手重构之前，我们先看看那些「坏味道」。我在项目中遇到过太多这样的代码，每次看到都头皮发麻。

2.1 日志信息缺失

// 反例：只记录错误信息，没有上下文
try {
    processOrder(orderId);
} catch (Exception e) {
    log.error("处理订单失败");
}

你想想看，线上有100个订单处理失败，你只知道「处理订单失败」，但不知道是哪个订单、什么原因、当时的参数是什么。这日志等于白写。

2.2 日志级别混乱

// 反例：所有信息都打 INFO
log.info("用户登录成功：{}", userId);
log.info("数据库连接失败，重试第{}次", retryCount);
log.info("系统启动完成");

数据库连接失败这种严重问题，居然和用户登录成功混在一起。线上排查时，你根本分不清哪些是正常信息，哪些是异常信号。

2.3 日志内容冗余

// 反例：在循环中打印大量日志
for (int i = 0; i < 10000; i++) {
    log.debug("处理第{}条数据", i);
    process(data[i]);
}

这种代码，一旦开启DEBUG级别，磁盘IO直接被打满，系统性能急剧下降。我曾经见过一个项目，就是因为这种日志，导致生产环境频繁OOM。

3. 日志重构实战策略

好，现在进入正题。怎么重构？我一般会分三步走。

3.1 统一日志格式

首先，所有日志必须有一个统一的格式。我个人习惯使用结构化的日志格式，比如JSON。

// 重构后：结构化日志
{
  "timestamp": "2024-01-15T10:30:00.123Z",
  "level": "ERROR",
  "logger": "com.example.OrderService",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "订单处理失败",
  "context": {
    "orderId": "ORD-20240115-001",
    "userId": "USER-12345",
    "errorCode": "PAYMENT_TIMEOUT",
    "retryCount": 3
  }
}

这样做的好处很明显：

• 可以直接用日志分析工具（如ELK）进行搜索和聚合
• 可以快速过滤出特定traceId的所有日志
• 可以统计特定错误码的出现频率

3.2 规范日志级别

日志级别的使用，必须有一套明确的规范。我建议这样划分：

级别	使用场景	示例
ERROR	系统无法自动恢复的异常	数据库连接失败、第三方服务不可用
WARN	系统可以自动恢复的异常	重试成功、降级策略生效
INFO	关键业务流程的节点	用户注册成功、订单创建完成
DEBUG	开发调试时使用，生产环境关闭	方法入参、中间计算结果

3.3 引入链路追踪

在微服务架构中，一个请求会经过多个服务。如果没有链路追踪，你根本不知道这个请求到底经历了什么。

// 重构前：没有traceId
ServiceA: log.info("收到请求");
ServiceB: log.info("处理请求");
ServiceC: log.info("返回结果");

// 重构后：携带traceId
ServiceA: log.info("traceId={}, 收到请求", traceId);
ServiceB: log.info("traceId={}, 处理请求", traceId);
ServiceC: log.info("traceId={}, 返回结果", traceId);

嗯，这里要注意。traceId必须在入口处生成，然后通过HTTP头或RPC上下文传递到下游服务。我建议使用开源的链路追踪框架，比如SkyWalking或Zipkin，它们会自动帮你处理这些。

4. 日志重构的避坑指南

重构日志，看起来简单，但坑也不少。我把自己踩过的坑分享给你。

5. 日志重构的知识体系

为了让你更直观地理解日志重构的全貌，我画了一张图。

6. 总结

日志重构，说白了就是一次「信息治理」。把混乱的、无用的日志清理掉，留下结构化的、有价值的日志。

我个人觉得，日志重构的投入产出比非常高。花一天时间重构日志，可能在未来的一年里，每次排查问题都能节省半小时。这笔账，怎么算都划算。

记住，好的日志，是系统的「黑匣子」。它不会说话，但在关键时刻，能救你一命。