apache commons logging 仅为日志门面，不提供格式化功能，日志格式需在log4j2、logback或jul等具体实现中配置；其自动绑定优先级为log4j2→log4j1→slf4j→jul，未引入实现时回退至功能较弱的jul。
apache commons logging 本身不提供日志格式化功能，也不支持自定义输出格式——它只是一个日志门面（facade），负责桥接底层日志实现（如 log4j、logback、jul）。真正控制日志格式的是你实际使用的日志框架。因此，“apache 日志扩展模块自定义格式”这个说法容易引起误解，实践中需明确：配置日志格式，要落在 log4j2、logback 或 jul 等具体实现上，而非 commons logging。
确认底层日志实现是关键一步
Commons Logging 会自动发现并绑定 classpath 中可用的日志实现，优先级一般为：Log4j2 → Log4j1 → SLF4J → JUL。若未显式引入任何实现，它将回退到 JDK 自带的 java.util.logging（JUL），而 JUL 的格式定制能力较弱、配置繁琐。
- 检查项目依赖，确认实际生效的是哪个日志框架（例如 Maven 中是否有 log4j-core、log4j-api 或 logback-classic）
- 在类路径下查找对应配置文件：Log4j2 对应 log4j2.xml 或 log4j2.json；Logback 对应 logback.xml；JUL 对应 logging.properties
- 可通过代码验证：System.out.println(LogManager.getFactory()); 查看实际工厂类型
Log4j2 中自定义 PatternLayout（最常用场景）
Log4j2 提供强大灵活的 PatternLayout，通过 pattern 字符串控制每行日志内容与样式。常见占位符包括 %d（日期）、%p（级别）、%c（Logger 名）、%m（日志消息）、%ex（异常栈）等。
- 示例 pattern：%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5p %c{1} - %m%n
- 支持 ANSI 颜色（需启用 ConsoleAppender 的 follow="true" 和系统支持）：%d %highlight{%p}{FATAL=bg_red, ERROR=red, WARN=yellow, INFO=green, DEBUG=blue, TRACE=black}
- 可嵌入 MDC（Mapped Diagnostic Context）字段，如 %X{traceId} %X{userId}，前提是业务代码已调用 MDC.put("traceId", "xxx")
Logback 中使用 PatternLayoutEncoder
Logback 同样以 pattern 为核心，但配置结构略有不同：需在 appender 内嵌套 encoder 并指定 pattern。
- 典型配置片段：
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"><encoder><pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern></encoder></appender> - 支持转换器（converter）扩展，例如自定义时间格式、脱敏手机号：%replace(%msg){'1[3-9]\d{9}', '***'}
- 结合 AsyncAppender 可提升高并发下的日志性能，但注意异步上下文（如 MDC）需显式设置 includeCallerData="true" 或使用 LoggingEventAsyncDisruptor
避免踩坑：Commons Logging 的典型误区
开发者常因混淆门面与实现，导致格式配置无效或行为异常。
- 只引入 commons-logging 而未添加任意日志实现 → 实际走 JUL，pattern 配置被忽略
- 同时引入 Log4j2 和 Logback → 类路径冲突，可能触发警告甚至绑定失败，应排除其中一个
- 使用 LogFactory.getLog(Class) 获取 logger，却误以为能直接调用 setLevel() 或 addAppender() → 这些方法属于具体实现，Commons Logging 接口不提供
- MDC 在多线程/异步场景（如 CompletableFuture、@Async）中不自动传递 → 需借助 ThreadLocal 手动复制，或使用框架适配器（如 Spring 的 ThreadPoolTaskExecutor 设置 copyInheritableThreadLocals=true）
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
