在Java应用开发中，合理的异常日志记录能够帮助开发者快速定位线上问题、还原故障发生场景，是系统可观测性的重要组成部分。很多开发者在记录异常日志时容易忽略关键信息，或者错误使用日志输出方法，导致排查问题时缺少必要的上下文。
Java异常日志记录的核心原则
记录异常日志的核心目标是让排查人员能够通过日志还原异常发生的完整场景，因此需要遵循几个基础原则：
- 记录完整的异常堆栈信息，不能只记录异常的消息描述
- 补充异常发生时的业务上下文，比如当前操作的用户ID、请求参数、业务状态等
- 避免记录冗余日志，同一异常不要在多个层级重复记录
- 根据异常的严重程度选择对应的日志级别，错误类异常使用ERROR级别，可预期的异常使用WARN级别
常用日志框架的选择与配置
Java生态中主流的日志框架组合是SLF4J作为日志门面，搭配Logback作为日志实现，这种组合既能保持日志接口的通用性，又能获得良好的性能和配置灵活性。
依赖引入
使用Maven引入相关依赖：
<!-- SLF4J 门面 -->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>1.7.36</version>
</dependency>
<!-- Logback 实现 -->
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<version>1.2.11</version>
</dependency>
Logback基础配置
在resources目录下创建logback.xml配置文件，定义日志输出格式和输出路径：
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<!-- 定义控制台输出 -->
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<!-- 定义文件输出 -->
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>logs/app.log</file>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<fileNamePattern>logs/app.%d{yyyy-MM-dd}.log</fileNamePattern>
<maxHistory>30</maxHistory>
</rollingPolicy>
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<!-- 设置根日志级别 -->
<root level="INFO">
<appender-ref ref="CONSOLE" />
<appender-ref ref="FILE" />
</root>
</configuration>
异常日志的正确记录方式
错误示例与问题分析
很多开发者会写出下面这样的异常日志记录代码：
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class UserService {
private static final Logger logger = LoggerFactory.getLogger(UserService.class);
public void updateUserStatus(Long userId, Integer status) {
try {
// 模拟数据库更新操作
throw new RuntimeException("更新用户状态失败");
} catch (Exception e) {
// 错误写法1：只记录异常消息，丢失堆栈
logger.error("更新用户状态异常：" + e.getMessage());
// 错误写法2：重复记录异常，上层调用可能还会记录一次
logger.error("用户ID：" + userId + "，状态：" + status + "，更新失败", e);
}
}
}
上面的代码存在两个问题：第一种写法只记录了异常的getMessage()内容，丢失了完整的堆栈轨迹，无法定位异常发生的具体代码位置；第二种写法虽然记录了堆栈，但是缺少必要的业务上下文，排查时不知道是哪个用户、什么状态的操作出现了问题。
正确记录方式示例
正确的异常日志记录需要同时包含业务上下文和完整异常堆栈：
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class UserService {
private static final Logger logger = LoggerFactory.getLogger(UserService.class);
public void updateUserStatus(Long userId, Integer status) {
try {
// 模拟数据库更新操作
throw new RuntimeException("更新用户状态失败");
} catch (Exception e) {
// 正确写法：先记录业务上下文，再把异常对象作为参数传入，日志框架会自动打印完整堆栈
logger.error("更新用户状态失败，用户ID：{}，目标状态：{}", userId, status, e);
}
}
}
这里使用了SLF4J的参数化日志输出，避免了字符串拼接的性能损耗，同时把异常对象作为最后一个参数传入，Logback会自动输出完整的异常堆栈信息。
不同场景下的日志记录实践
可预期的业务异常
对于业务层面的可预期异常，比如用户不存在、参数校验失败等，不需要记录完整堆栈，使用WARN级别即可：
public void queryUser(Long userId) {
try {
// 模拟查询用户操作
if (userId == null) {
throw new IllegalArgumentException("用户ID不能为空");
}
} catch (IllegalArgumentException e) {
// 业务异常不需要完整堆栈，记录关键信息即可
logger.warn("查询用户失败，原因：{}，用户ID：{}", e.getMessage(), userId);
}
}
第三方接口调用异常
调用第三方接口时出现异常，除了记录异常本身，还需要记录请求参数、接口地址等信息，方便定位是自身请求问题还是第三方服务问题：
import java.net.URI;
public class ThirdPartyService {
private static final Logger logger = LoggerFactory.getLogger(ThirdPartyService.class);
public void callRemoteApi(String apiUrl, String requestParam) {
try {
// 模拟接口调用
throw new RuntimeException("接口调用超时");
} catch (Exception e) {
logger.error("调用第三方接口异常，接口地址：{}，请求参数：{}", apiUrl, requestParam, e);
}
}
}
异常日志记录的常见误区
- 不要吞掉异常，即捕获异常后不记录日志也不重新抛出，这会导致问题完全无法排查
- 不要使用
e.printStackTrace()输出异常，这种方式输出的日志不受日志框架管理，无法控制输出格式和路径，生产环境不建议使用 - 不要在循环中记录大量异常日志，避免日志文件快速膨胀，必要时可以做日志限流
- 不要记录敏感信息，比如用户密码、身份证号、手机号等，避免信息泄露
日志级别的选择规范
不同日志级别对应不同的使用场景，合理选择级别能够提升日志的可读性：
| 日志级别 | 适用场景 |
|---|---|
| ERROR | 系统级错误、不可预期的异常、导致功能完全不可用的问题 |
| WARN | 可预期的业务异常、不影响核心功能的潜在风险、参数校验失败 |
| INFO | 核心业务流程的关键节点、重要的业务操作记录 |
| DEBUG | 开发调试时的详细信息，生产环境默认关闭 |
遵循以上规范记录Java异常日志，能够有效提升问题排查效率，减少故障定位的时间成本，是Java开发过程中需要养成的基础习惯。