Log4j入门教程：轻松掌握Java日志记录

写于2025年9月

大家好！今天我想和大家分享一下Log4j这个强大却又不复杂的日志记录工具。作为一名开发者，我曾经也是对日志这块儿一知半解，直到真正需要调试复杂问题时才意识到：哇，没有好的日志系统简直寸步难行！

为什么需要日志？

先问个问题 - 你是不是还在用System.out.println()来调试代码？（我们都经历过这个阶段！）但在实际项目中，这种方式简直就是灾难：

• 无法控制输出级别（全都跑出来了！）
• 没法把日志保存到文件（关了控制台就没了）
• 性能？格式？过滤？忘了它吧！

这就是为什么我们需要Log4j这样的专业日志框架！

Log4j是什么？

Log4j（Log for Java）是Apache软件基金会的一个开源项目，它提供了强大而灵活的日志记录功能。说白了，它就是一个能让你轻松管理、控制和输出日志信息的Java库。

注意：本文讨论的是Log4j 2，这是目前最新最安全的版本。老版本Log4j 1.x已经不再维护，存在安全隐患！！！

为什么选择Log4j？

• 超级灵活的配置方式
• 多种日志级别控制
• 可以同时输出到控制台、文件、数据库等
• 性能优秀（比起其他日志框架）
• 扩展性好（可以自定义很多东西）

开始使用Log4j

好了，废话不多说，我们来看看怎么在项目中使用Log4j 2！

第一步：添加依赖

如果你使用Maven，在pom.xml中添加：

xml <dependencies> <!-- Log4j核心包 --> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-api</artifactId> <version>2.20.0</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-core</artifactId> <version>2.20.0</version> </dependency> </dependencies>

使用Gradle的朋友可以这样：

groovy implementation 'org.apache.logging.log4j:log4j-api:2.20.0' implementation 'org.apache.logging.log4j:log4j-core:2.20.0'

第二步：创建配置文件

Log4j需要一个配置文件来告诉它怎么处理日志。最简单的方式是在src/main/resources目录下创建一个log4j2.xml文件：

```xml

```

这个配置文件做了什么？它创建了两个"输出目标"（Appenders）：

1. 一个输出到控制台
2. 一个输出到logs/app.log文件

两者使用的是不同的日志格式（Pattern）。

第三步：在代码中使用Log4j

好了，现在来实际写代码：

```java import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger;

public class MyApp { // 创建Logger实例 private static final Logger logger = LogManager.getLogger(MyApp.class);

} ```

运行这个程序，你会看到控制台输出日志，同时在项目根目录下会创建一个logs/app.log文件。

日志级别详解

Log4j有六个主要的日志级别（从低到高）：

1. TRACE：最详细的信息，一般用于深度调试
2. DEBUG：调试信息，开发时有用
3. INFO：一般信息，程序正常运行时的状态信息
4. WARN：警告信息，不影响使用，但最好关注
5. ERROR：错误信息，程序遇到了问题
6. FATAL：致命错误，导致程序中断

实际使用中，你可以设置一个"阈值"。比如设置为INFO级别，那么TRACE和DEBUG的日志就不会输出，只有INFO及以上级别的日志才会记录。这样在开发和生产环境可以使用不同的设置！

配置文件详解

Log4j的配置文件是整个系统的核心。我们来分解一下它的主要部分：

Appenders（输出目标）

Appender决定日志往哪里输出。常见的有：

• ConsoleAppender：输出到控制台
• FileAppender：输出到单个文件
• RollingFileAppender：支持日志文件滚动（按大小或时间）
• JDBCAppender：输出到数据库
• SMTPAppender：通过邮件发送日志
• SyslogAppender：发送到系统日志

Layouts（布局）

Layout决定日志的格式。最常用的是PatternLayout，它使用一种类似printf的格式串：

• %d{yyyy-MM-dd HH:mm:ss.SSS} - 日期时间
• %t - 线程名
• %-5level - 日志级别，左对齐5个字符
• %logger{36} - 记录器名称，最长36个字符
• %msg%n - 日志消息和换行符

Loggers（记录器）

Logger决定哪些类的日志使用什么级别。你可以为不同的包设置不同的日志级别。比如：

xml <Loggers> <Logger name="com.myapp.database" level="DEBUG"/> <Logger name="org.hibernate" level="WARN"/> <Root level="INFO"> <AppenderRef ref="Console"/> <AppenderRef ref="File"/> </Root> </Loggers>

这样配置会让你自己的数据库相关代码输出DEBUG级别的日志，Hibernate只输出WARN级别以上的日志，其他所有类输出INFO级别以上的日志。

实际应用案例

理论讲完了，我们来看几个实际应用场景！

场景1：按日期滚动的日志文件

想让你的日志每天自动创建一个新文件？这样配置：

xml <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{yyyy-MM-dd}-%i.log"> <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/> <Policies> <TimeBasedTriggeringPolicy /> <SizeBasedTriggeringPolicy size="10 MB"/> </Policies> <DefaultRolloverStrategy max="20"/> </RollingFile>

这样设置后，日志文件会每天或者达到10MB时滚动一次，并且最多保留20个历史文件。

场景2：按不同服务分离日志

在微服务架构中，可能需要将不同服务的日志分开：

xml <Loggers> <Logger name="com.myapp.userservice" level="DEBUG"> <AppenderRef ref="UserServiceFile"/> </Logger> <Logger name="com.myapp.orderservice" level="DEBUG"> <AppenderRef ref="OrderServiceFile"/> </Logger> <Root level="INFO"> <AppenderRef ref="Console"/> <AppenderRef ref="MainLogFile"/> </Root> </Loggers>

场景3：异步日志提升性能

在高并发系统中，同步写日志可能成为性能瓶颈。使用异步方式可以显著提升性能：

```xml

```

进阶技巧

掌握了基础后，我们来看一些进阶用法！

1. 使用Markers标记特殊日志

Marker可以用来给日志加上特殊标记，便于过滤：

```java import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger; import org.apache.logging.log4j.Marker; import org.apache.logging.log4j.MarkerManager;

public class MarkerExample { private static final Logger logger = LogManager.getLogger(MarkerExample.class); private static final Marker SECURITY = MarkerManager.getMarker("SECURITY");

} ```

然后在配置中，你可以专门为这些标记了SECURITY的日志指定特殊处理：

xml <Logger name="com.myapp" level="INFO"> <AppenderRef ref="Console"/> <AppenderRef ref="SecurityLogFile" level="INFO" marker="SECURITY"/> </Logger>

2. 使用MDC传递上下文信息

MDC（Mapped Diagnostic Context）允许你把一些上下文信息（比如用户ID、请求ID）关联到日志中：

```java import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger; import org.apache.logging.log4j.ThreadContext; // MDC在Log4j2中叫ThreadContext

public class MDCExample { private static final Logger logger = LogManager.getLogger(MDCExample.class);

} ```

然后在PatternLayout中使用这些值：

xml <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} [reqId:%X{requestId} user:%X{userId}] - %msg%n"/>

日志会显示成这样： 10:15:23.456 [http-nio-8080-exec-1] INFO com.myapp.Controller [reqId:REQ123 user:USER456] - 开始处理请求

3. 自定义Log4j的日志级别

如果默认的日志级别不够用，你还可以定义自己的级别：

```java import org.apache.logging.log4j.Level; import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger; import org.apache.logging.log4j.core.config.Configurator;

public class CustomLevelExample { // 定义自己的级别，介于INFO和WARN之间 private static final Level NOTICE = Level.forName("NOTICE", 350);

} ```

常见问题与解决方案

问题1：日志配置文件不生效

检查： - 配置文件是否放在正确的位置（通常是classpath根目录） - 文件名是否正确（log4j2.xml、log4j2.json、log4j2.properties等） - XML语法是否有误

问题2：性能优化

• 使用异步Logger提高性能
• 避免在高频代码中使用logger.isDebugEnabled()判断
• 使用Log4j的Lambda表达式API减少参数构建开销

```java // 不好的写法 - 即使日志级别设置为ERROR，仍会进行字符串拼接 logger.debug("User data: " + createExpensiveUserString(user));

// 好的写法 - 使用参数占位符 logger.debug("User data: {}", createExpensiveUserString(user));

// 更好的写法 - 使用Lambda延迟计算 logger.debug("User data: {}", () -> createExpensiveUserString(user)); ```

问题3：日志文件权限

在Linux系统中，如果日志文件创建失败，可能是权限问题。确保应用有写入日志目录的权限。

总结

好了，以上就是Log4j 2的入门教程了！我们已经覆盖了：

• 基本概念和配置
• 不同级别的日志
• 多种输出方式
• 格式控制
• 高级特性和性能优化

掌握了这些，你就能在项目中轻松管理日志了。好的日志系统能让开发、测试和运维工作事半功倍！

记住一句话：程序出了问题，日志是你最好的朋友！所以从现在开始，用好Log4j，告别System.out.println吧！

你有什么关于Log4j的使用心得或疑问？欢迎在评论区留言讨论！

参考资源：

• Apache Log4j 2官方文档
• Log4j 2 API文档
• Log4j 2配置文档