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 的典型误区

开发者常因混淆门面与实现，导致格式配置无效或行为异常。

立即学习“Java免费学习笔记（深入）”；

• 只引入 commons-logging 而未添加任意日志实现 → 实际走 JUL，pattern 配置被忽略
• 同时引入 Log4j2 和 Logback → 类路径冲突，可能触发警告甚至绑定失败，应排除其中一个
• 使用 LogFactory.getLog(Class) 获取 logger，却误以为能直接调用 setLevel() 或 addAppender() → 这些方法属于具体实现，Commons Logging 接口不提供
• MDC 在多线程/异步场景（如 CompletableFuture、@Async）中不自动传递 → 需借助 ThreadLocal 手动复制，或使用框架适配器（如 Spring 的 ThreadPoolTaskExecutor 设置 copyInheritableThreadLocals=true）