Java日志级别结构如何规整

本文目录导读：

1. 标准日志级别金字塔（最核心）
2. 框架层面的级别规整
3. 实际业务中的“规整”套路（反模式与最佳实践）
4. 工具：MDC 结构化日志（让级别规整更容易）
5. 团队规约：写在代码规范中
6. 一个规整的日志级别结构表

Java 日志级别的规整（结构设计）是构建可观测性系统的基础，一个好的日志级别结构不是简单的“INFO, WARN, ERROR”，而是需要根据你的日志框架、业务场景以及监控告警需求进行分层设计。

以下从标准级别定义、实际使用规范、框架差异和团队规约四个维度来拆解。

标准日志级别金字塔（最核心）

任何规整的日志系统都应该遵循清晰的“严重程度”分层,从低到高通常为：

核心原则：

• INFO 不要刷屏：每个请求只打印 1-3 行，而不是将循环体内的内容打印出来（那是 DEBUG 的事）。
• ERROR 是留给代码 Bug 和系统异常的：不要把业务校验失败（如“用户名已存在”）直接打成 ERROR（应打 WARN）。
• FATAL 现在很少用：现代框架（如 Log4j2, Logback）通常无 FATAL，直接用 ERROR + 自定义级别或通过告警条件区分。

框架层面的级别规整

不同 Java 日志框架的级别支持不同,需要统一适配：

规整建议：

• 统一使用 SLF4J 作为门面，避免直接依赖 Log4j 或 Logback 的 API。
• 如果你必须使用 FATAL，可以加到 Logback 的配置中（通过复制 ERROR 级 logger 并改名），但不推荐，更现代的做法是：在 ERROR 级日志中包含 "fatal" 关键词，由告警系统（如 Prometheus + AlertManager）做高优先级的规则匹配。

实际业务中的“规整”套路（反模式与最佳实践）

什么情况下打什么级别？

永远不要做这几件事（破坏结构）：

1. catch Exception 后只打 ERROR，却不传异常对象：

   // 错误：丢失堆栈信息
   logger.error("操作失败");
   // 正确：传入异常对象，打印完整堆栈
   logger.error("操作失败", exception);

2. 使用 logger.error 记录业务错误码：错误码应单独作为 MDC（Mapped Diagnostic Context）变量，而不是放在 message 里混淆。
3. 在循环内打 log：尤其是 INFO 级别，会直接打爆磁盘。
   • 规整做法：在循环外打汇总日志，或者抽样打印（每1000条打一次）。

工具：MDC 结构化日志（让级别规整更容易）

为了让“规整”能落地到数据结构中，推荐使用 MDC + JSON 格式，日志级别只是其中一个字段,这样便于查询和聚合。

推荐日志格式（结构化 JSON）：

{
  "@timestamp": "2025-04-11T10:15:30.123Z",
  "level": "ERROR",
  "logger": "com.your.service.OrderService",
  "thread": "http-nio-8080-exec-3",
  "traceId": "abc123def456",
  "userId": "u9999",
  "message": "订单创建失败",
  "stack_trace": "java.sql.SQLException: ...",
  "duration_ms": 350,
  "custom_context": {
    "orderId": "ORD12345",
    "sku": "SKU001"
  }
}

规整效果：

• 通过 level 字段可以快速筛选。
• 通过 traceId 可以将一次请求的所有日志串联。
• 通过 custom_context 直接携带业务参数（而不需要拼在 message 里）。

实现方式：

import org.slf4j.MDC;
// 在请求入口（Filter/Interceptor）设置
MDC.put("traceId", generateTraceId());
MDC.put("userId", request.getUserId());
// ...
// 日志框架会自动将 MDC 中的变量输出到 JSON 格式中
logger.warn("库存不足", orderId); // 此时日志会自动带上 traceId 和 userId
// 在请求结束后清除
MDC.clear();

团队规约：写在代码规范中

要真正“规整”，需要在团队 Git Hook 或 CI 中强制检查：

1. 禁用 System.out.println：通过 Checkstyle 或 Sonar 规则拦截。
2. 异常必须传第二个参数：

   // 坏
   logger.error(e.getMessage());
   // 好
   logger.error("业务描述", e);

3. 业务异常用 WARN，系统异常用 ERROR：强制在 Code Review 中审核。
4. 禁止在循环体内部打 INFO/ERROR：除非有明确的抽样策略（如 if (i % 1000 == 0)）。

一个规整的日志级别结构表

最终结论：规整的日志结构 = SLF4J 门面 + 严格级别语义 + JSON 结构化 + MDC 跟踪 + 异常堆栈完整。