Java日志封装应基于SLF4J门面，结合MDC实现上下文透传，提供语义化方法、结构化输出、敏感信息脱敏、分级开关与采样降噪，统一格式并确保线程安全。
在 Java 项目中，把日志封装进自定义工具类确实能统一格式、简化调用、避免重复代码，但关键不是“封装一个工具类”，而是让日志行为可配置、可扩展、不侵入业务逻辑，同时兼容主流日志框架（如 SLF4J + Logback / Log4j2）。
用 SLF4J 门面 + MDC 实现上下文透传
不要自己 new Logger 或硬编码日志实现，始终通过 SLF4J 的 LoggerFactory.getLogger(Class) 获取。封装的核心是利用 MDC（Mapped Diagnostic Context）注入请求 ID、用户 ID、traceId 等上下文信息，让每条日志自带业务维度：
- 在 Web 过滤器或 Spring 拦截器中生成并写入 MDC（如
MDC.put("traceId", UUID.randomUUID().toString())） - 在工具类中复用 MDC，无需每次手动传参；日志模板里直接用
%X{traceId}即可渲染 - 务必在请求结束时清空 MDC（
MDC.clear()），防止线程复用导致脏数据
定义语义化日志方法，屏蔽底层细节
工具类不暴露原始 logger，只提供带业务语义的静态方法，比如：
LogUtil.infoBiz("订单创建成功", Map.of("orderId", "1001", "userId", "U2024"))LogUtil.errorFlow("支付回调验签失败", e, Map.of("sign", "abc", "data", json))- 内部自动拼接结构化 key-value（JSON 或 key=value 格式），并确保异常堆栈完整输出
- 避免裸字符串拼接（如
"订单" + id + "创建成功"），全部走占位符（logger.info("订单{}创建成功", orderId)）以支持延迟求值
统一日志格式与输出渠道控制
格式统一靠 Logback/Log4j2 的 pattern 配置，工具类只需保证字段可被 pattern 解析：
立即学习“Java免费学习笔记（深入）”；
- 推荐 pattern 示例：
%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{traceId:-}] [%p] [%c{1}] - %m%n - 关键字段（traceId、level、class、message）固定位置，便于 ELK 或日志平台解析
- 敏感字段（如手机号、身份证）在工具类中做脱敏处理（如
mask("13812345678") → "138****5678"），不在日志配置里靠正则过滤（性能差且易漏）
支持分级开关与采样降噪
生产环境高频日志容易冲垮磁盘或日志服务，工具类需内置轻量级控制能力：
- 按业务模块或操作类型设置日志等级开关（如
if (LogSwitches.isOrderDebugOn()) { LogUtil.debug(...); }） - 对 info/warn 日志支持采样（如每 100 次只打 1 条），用简单计数器 + CAS 实现，不依赖外部组件
- error 日志默认全量，但可配置“相同异常类+相同消息”在 N 秒内去重合并（避免刷屏）
真正优雅的封装，不是把 logger 包一层就完事，而是把上下文管理、结构化输出、安全控制、性能兜底都沉淀到工具类里，让开发者只关心“我要记什么”，而不是“怎么记才不出错”。
