Java日志记录指南：SLF4J、Logback配置与最佳实践

java-logging by claude-dev-suite/claude-dev-suite

1 周安装量

GitHub

安装命令

npx skills add https://github.com/claude-dev-suite/claude-dev-suite --skill java-logging

开发代码规范 Spring Boot

🇨🇳中文介绍

Java 日志记录

架构概述

┌─────────────────────────────────────────────────────────────┐
│                    应用程序代码                             │
│              (仅使用 SLF4J API)                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      SLF4J 门面层                          │
│              (抽象层)                                       │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────────┐
        │ Logback  │   │ Log4j2   │   │ java.util    │
        │          │   │          │   │ .logging     │
        └──────────┘   └──────────┘   └──────────────┘

规则：始终针对 SLF4J API 进行编码。实现是运行时依赖项。

SLF4J API 使用

基础日志记录

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class UserService {
    private static final Logger log = LoggerFactory.getLogger(UserService.class);

    public User findUser(Long id) {
        log.debug("正在查找用户，ID: {}", id);

        try {
            User user = repository.findById(id);
            log.info("找到用户: {}", user.getEmail());
            return user;
        } catch (Exception e) {
            log.error("查找用户失败，ID: {}", id, e);
            throw e;
        }
    }
}

🇺🇸English

Java Logging

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Application Code                         │
│              (uses SLF4J API only)                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      SLF4J Facade                           │
│              (abstraction layer)                            │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────────┐
        │ Logback  │   │ Log4j2   │   │ java.util    │
        │          │   │          │   │ .logging     │
        └──────────┘   └──────────┘   └──────────────┘

Rule : Always code to SLF4J API. Implementation is a runtime dependency.

SLF4J API Usage

Basic Logging

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class UserService {
    private static final Logger log = LoggerFactory.getLogger(UserService.class);

    public User findUser(Long id) {
        log.debug("Finding user with id: {}", id);

        try {
            User user = repository.findById(id);
            log.info("User found: {}", user.getEmail());
            return user;
        } catch (Exception e) {
            log.error("Failed to find user with id: {}", id, e);
            throw e;
        }
    }
}

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

级别	用途	示例
`TRACE`	非常详细的调试信息	循环迭代、变量值
`DEBUG`	调试信息	方法进入/退出、查询参数
`INFO`	业务事件	用户登录、订单创建
`WARN`	潜在问题	使用了已弃用的 API、重试尝试
`ERROR`	需要关注的错误	捕获异常、操作失败

参数化消息（最佳实践）

// 良好 - 使用参数化日志记录（高效）
log.debug("正在处理用户 {}，角色 {}", userId, role);

// 不佳 - 字符串拼接（总是会被求值）
log.debug("正在处理用户 " + userId + "，角色 " + role);

// 对于开销大的操作，使用 isEnabled 检查
if (log.isDebugEnabled()) {
    log.debug("复杂数据: {}", computeExpensiveDebugInfo());
}

Spring Boot (logback-spring.xml)

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- 包含 Spring Boot 默认配置 -->
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>

    <!-- 属性 -->
    <property name="LOG_PATH" value="${LOG_PATH:-logs}"/>
    <property name="LOG_FILE" value="${LOG_FILE:-application}"/>

    <!-- 控制台输出器 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %highlight(%-5level) [%thread] %cyan(%logger{36}) - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- 滚动文件输出器 -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/${LOG_FILE}.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/${LOG_FILE}.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>30</maxHistory>
            <totalSizeCap>3GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <!-- 生产环境 JSON 输出器 -->
    <appender name="JSON" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/${LOG_FILE}-json.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/${LOG_FILE}-json.%d{yyyy-MM-dd}.log.gz</fileNamePattern>
            <maxHistory>7</maxHistory>
        </rollingPolicy>
        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
            <includeMdcKeyName>traceId</includeMdcKeyName>
            <includeMdcKeyName>userId</includeMdcKeyName>
        </encoder>
    </appender>

    <!-- 性能优化异步输出器 -->
    <appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
        <queueSize>512</queueSize>
        <discardingThreshold>0</discardingThreshold>
        <appender-ref ref="FILE"/>
    </appender>

    <!-- 日志记录器配置 -->
    <logger name="com.yourcompany" level="DEBUG"/>
    <logger name="org.springframework" level="INFO"/>
    <logger name="org.hibernate.SQL" level="DEBUG"/>
    <logger name="org.hibernate.type.descriptor.sql" level="TRACE"/>

    <!-- 根日志记录器 -->
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="ASYNC_FILE"/>
    </root>

    <!-- 环境特定配置 -->
    <springProfile name="prod">
        <root level="INFO">
            <appender-ref ref="JSON"/>
        </root>
    </springProfile>
</configuration>

application.yml 配置

logging:
  level:
    root: INFO
    com.yourcompany: DEBUG
    org.springframework.web: INFO
    org.hibernate.SQL: DEBUG
  pattern:
    console: "%d{HH:mm:ss.SSS} %highlight(%-5level) [%thread] %cyan(%logger{36}) - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n"
  file:
    name: logs/application.log
  logback:
    rollingpolicy:
      max-file-size: 100MB
      max-history: 30

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Properties>
        <Property name="LOG_PATH">logs</Property>
        <Property name="LOG_PATTERN">%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</Property>
    </Properties>

    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="${LOG_PATTERN}"/>
        </Console>

        <RollingFile name="File" fileName="${LOG_PATH}/app.log"
                     filePattern="${LOG_PATH}/app-%d{yyyy-MM-dd}-%i.log.gz">
            <PatternLayout pattern="${LOG_PATTERN}"/>
            <Policies>
                <SizeBasedTriggeringPolicy size="100MB"/>
                <TimeBasedTriggeringPolicy/>
            </Policies>
            <DefaultRolloverStrategy max="30"/>
        </RollingFile>

        <!-- 高性能异步输出器 -->
        <Async name="AsyncFile">
            <AppenderRef ref="File"/>
        </Async>
    </Appenders>

    <Loggers>
        <Logger name="com.yourcompany" level="debug"/>
        <Root level="info">
            <AppenderRef ref="Console"/>
            <AppenderRef ref="AsyncFile"/>
        </Root>
    </Loggers>
</Configuration>

结构化日志记录 (JSON)

<!-- 用于 Logback -->
<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>7.4</version>
</dependency>

MDC（映射诊断上下文）

import org.slf4j.MDC;

@Component
public class RequestLoggingFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
        try {
            MDC.put("traceId", generateTraceId());
            MDC.put("userId", getCurrentUserId());
            MDC.put("requestPath", ((HttpServletRequest) request).getRequestURI());

            chain.doFilter(request, response);
        } finally {
            MDC.clear();
        }
    }
}

结构化日志输出

import static net.logstash.logback.argument.StructuredArguments.*;

log.info("订单已处理",
    kv("orderId", order.getId()),
    kv("customerId", order.getCustomerId()),
    kv("amount", order.getTotal()),
    kv("currency", "USD"));

{
  "@timestamp": "2025-01-15T10:30:00.000Z",
  "level": "INFO",
  "logger": "com.example.OrderService",
  "message": "Order processed",
  "orderId": "ORD-12345",
  "customerId": "CUST-789",
  "amount": 99.99,
  "currency": "USD",
  "traceId": "abc123",
  "userId": "user456"
}

在所有地方使用 SLF4J API
使用参数化消息 log.info("用户 {}", userId)
包含关联 ID（traceId、requestId）
在适当的级别记录日志
在生产环境中使用异步输出器
配置日志轮转
使用 JSON 格式进行日志聚合

不要在日志消息中使用字符串拼接
不要记录敏感数据（密码、令牌、个人身份信息）
不要在紧密循环中记录日志而不进行级别检查
不要使用 System.out.println 进行日志记录
不要捕获并静默吞掉异常

// 不佳 - 记录敏感数据
log.info("用户登录: email={}, password={}", email, password);

// 良好 - 屏蔽敏感数据
log.info("用户登录: email={}", maskEmail(email));

// 辅助方法
private String maskEmail(String email) {
    int atIndex = email.indexOf('@');
    if (atIndex > 2) {
        return email.substring(0, 2) + "***" + email.substring(atIndex);
    }
    return "***";
}

何时不使用此技能

仅限 SLF4J API 的问题：使用 slf4j 技能处理 API 使用模式
Logback 配置细节：使用 logback 技能处理 XML 配置
Node.js/Python 项目：使用适合语言的日志记录技能
应用程序代码模式：专注于 SLF4J API，而非实现
框架迁移：查阅迁移专用指南

反模式	为何不好	解决方案
使用 System.out.println	无法控制、无法持久化、无法过滤	使用 SLF4J 日志记录器
在日志中使用字符串拼接	总是会被求值，性能影响	使用参数化日志记录：`log.info("用户 {}", id)`
在生产环境中不使用异步输出器	阻塞应用程序线程	使用 AsyncAppender 包装
在多线程应用程序中记录日志不使用 MDC	丢失请求上下文	使用 MDC 存储关联 ID
在生产环境中使用 DEBUG 级别	性能影响、磁盘使用	在生产环境中使用 INFO 或 WARN 级别
不屏蔽敏感数据	违反安全/合规要求	在记录日志前过滤密码、令牌、个人身份信息

问题	原因	解决方案
NoClassDefFoundError: StaticLoggerBinder	缺少 SLF4J 实现	添加 Logback 或 Log4j2 依赖项
多重绑定警告	类路径上有多个实现	只保留一个：Logback 或 Log4j2
日志未出现	错误的日志级别或缺少配置	检查 logback.xml 和日志级别
性能下降	同步输出器	使用 AsyncAppender 包装器
日志未轮转	缺少滚动策略	配置 RollingFileAppender
MDC 值未显示	模式缺少 %X{key}	在日志模式中添加 MDC 占位符

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class OrderService {
    public void processOrder(Order order) {
        log.info("Processing order: {}", order.getId());
    }
}

Level	Purpose	Example
`TRACE`	Very detailed debugging	Loop iterations, variable values
`DEBUG`	Debugging information	Method entry/exit, query params
`INFO`	Business events	User login, order placed
`WARN`	Potential issues	Deprecated API used, retry attempt
`ERROR`	Errors requiring attention	Exception caught, operation failed

log.trace("Entering loop iteration {}", i);
log.debug("Query parameters: userId={}, status={}", userId, status);
log.info("Order {} placed successfully", orderId);
log.warn("Payment retry attempt {} of {}", attempt, maxRetries);
log.error("Failed to process payment for order {}", orderId, exception);

Parameterized Messages (Best Practice)

// GOOD - uses parameterized logging (efficient)
log.debug("Processing user {} with role {}", userId, role);

// BAD - string concatenation (always evaluated)
log.debug("Processing user " + userId + " with role " + role);

// For expensive operations, use isEnabled check
if (log.isDebugEnabled()) {
    log.debug("Complex data: {}", computeExpensiveDebugInfo());
}

Logback Configuration

Spring Boot (logback-spring.xml)

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- Include Spring Boot defaults -->
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>

    <!-- Properties -->
    <property name="LOG_PATH" value="${LOG_PATH:-logs}"/>
    <property name="LOG_FILE" value="${LOG_FILE:-application}"/>

    <!-- Console Appender -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %highlight(%-5level) [%thread] %cyan(%logger{36}) - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Rolling File Appender -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/${LOG_FILE}.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/${LOG_FILE}.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>30</maxHistory>
            <totalSizeCap>3GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <!-- JSON Appender for Production -->
    <appender name="JSON" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/${LOG_FILE}-json.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/${LOG_FILE}-json.%d{yyyy-MM-dd}.log.gz</fileNamePattern>
            <maxHistory>7</maxHistory>
        </rollingPolicy>
        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
            <includeMdcKeyName>traceId</includeMdcKeyName>
            <includeMdcKeyName>userId</includeMdcKeyName>
        </encoder>
    </appender>

    <!-- Async Appender for Performance -->
    <appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
        <queueSize>512</queueSize>
        <discardingThreshold>0</discardingThreshold>
        <appender-ref ref="FILE"/>
    </appender>

    <!-- Logger Configuration -->
    <logger name="com.yourcompany" level="DEBUG"/>
    <logger name="org.springframework" level="INFO"/>
    <logger name="org.hibernate.SQL" level="DEBUG"/>
    <logger name="org.hibernate.type.descriptor.sql" level="TRACE"/>

    <!-- Root Logger -->
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="ASYNC_FILE"/>
    </root>

    <!-- Profile-specific configuration -->
    <springProfile name="prod">
        <root level="INFO">
            <appender-ref ref="JSON"/>
        </root>
    </springProfile>
</configuration>

application.yml Configuration

logging:
  level:
    root: INFO
    com.yourcompany: DEBUG
    org.springframework.web: INFO
    org.hibernate.SQL: DEBUG
  pattern:
    console: "%d{HH:mm:ss.SSS} %highlight(%-5level) [%thread] %cyan(%logger{36}) - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n"
  file:
    name: logs/application.log
  logback:
    rollingpolicy:
      max-file-size: 100MB
      max-history: 30

Log4j2 Configuration

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Properties>
        <Property name="LOG_PATH">logs</Property>
        <Property name="LOG_PATTERN">%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</Property>
    </Properties>

    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="${LOG_PATTERN}"/>
        </Console>

        <RollingFile name="File" fileName="${LOG_PATH}/app.log"
                     filePattern="${LOG_PATH}/app-%d{yyyy-MM-dd}-%i.log.gz">
            <PatternLayout pattern="${LOG_PATTERN}"/>
            <Policies>
                <SizeBasedTriggeringPolicy size="100MB"/>
                <TimeBasedTriggeringPolicy/>
            </Policies>
            <DefaultRolloverStrategy max="30"/>
        </RollingFile>

        <!-- Async for high performance -->
        <Async name="AsyncFile">
            <AppenderRef ref="File"/>
        </Async>
    </Appenders>

    <Loggers>
        <Logger name="com.yourcompany" level="debug"/>
        <Root level="info">
            <AppenderRef ref="Console"/>
            <AppenderRef ref="AsyncFile"/>
        </Root>
    </Loggers>
</Configuration>

Structured Logging (JSON)

<!-- For Logback -->
<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>7.4</version>
</dependency>

MDC (Mapped Diagnostic Context)

import org.slf4j.MDC;

@Component
public class RequestLoggingFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
        try {
            MDC.put("traceId", generateTraceId());
            MDC.put("userId", getCurrentUserId());
            MDC.put("requestPath", ((HttpServletRequest) request).getRequestURI());

            chain.doFilter(request, response);
        } finally {
            MDC.clear();
        }
    }
}

Structured Log Output

import static net.logstash.logback.argument.StructuredArguments.*;

log.info("Order processed",
    kv("orderId", order.getId()),
    kv("customerId", order.getCustomerId()),
    kv("amount", order.getTotal()),
    kv("currency", "USD"));

{
  "@timestamp": "2025-01-15T10:30:00.000Z",
  "level": "INFO",
  "logger": "com.example.OrderService",
  "message": "Order processed",
  "orderId": "ORD-12345",
  "customerId": "CUST-789",
  "amount": 99.99,
  "currency": "USD",
  "traceId": "abc123",
  "userId": "user456"
}

Use SLF4J API everywhere
Use parameterized messages log.info("User {}", userId)
Include correlation IDs (traceId, requestId)
Log at appropriate levels
Use async appenders in production
Configure log rotation
Use JSON format for log aggregation

Don't use string concatenation in log messages
Don't log sensitive data (passwords, tokens, PII)
Don't log inside tight loops without level check
Don't use System.out.println for logging
Don't catch and swallow exceptions silently

// BAD - logs sensitive data
log.info("User login: email={}, password={}", email, password);

// GOOD - mask sensitive data
log.info("User login: email={}", maskEmail(email));

// Helper
private String maskEmail(String email) {
    int atIndex = email.indexOf('@');
    if (atIndex > 2) {
        return email.substring(0, 2) + "***" + email.substring(atIndex);
    }
    return "***";
}

When NOT to Use This Skill

SLF4J API-only questions : Use slf4j skill for API usage patterns
Logback configuration details : Use logback skill for XML config
Node.js/Python projects : Use language-appropriate logging skills
Application code patterns : Focus on SLF4J API, not implementation
Framework migration : Consult migration-specific guides

Anti-Pattern	Why It's Bad	Solution
Using System.out.println	No control, no persistence, no filtering	Use SLF4J logger
String concatenation in logs	Always evaluated, performance hit	Use parameterized logging: `log.info("User {}", id)`
Not using async appenders in production	Blocks application threads	Wrap with AsyncAppender
Logging without MDC in multi-threaded apps	Loses request context	Use MDC for correlation IDs
DEBUG level in production	Performance impact, disk usage	Use INFO or WARN in production
Not masking sensitive data	Security/compliance violation	Filter passwords, tokens, PII before logging

Quick Troubleshooting

Issue	Cause	Solution
NoClassDefFoundError: StaticLoggerBinder	Missing SLF4J implementation	Add Logback or Log4j2 dependency
Multiple bindings warning	Multiple implementations on classpath	Keep only one: Logback OR Log4j2
Logs not appearing	Wrong log level or missing config	Check logback.xml and log levels
Performance degradation	Synchronous appenders	Use AsyncAppender wrapper
Logs not rotating	Missing rolling policy	Configure RollingFileAppender
MDC values not showing	Pattern missing %X{key}	Add MDC placeholders to log pattern

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

109,600 周安装

Java日志记录指南：SLF4J、Logback配置与最佳实践

🇨🇳中文介绍

Java 日志记录

架构概述

SLF4J API 使用

基础日志记录

🇺🇸English

Java Logging

Architecture Overview

SLF4J API Usage

Basic Logging

相关 Skills

使用 Lombok

日志级别

参数化消息（最佳实践）

Logback 配置

Spring Boot (logback-spring.xml)

application.yml 配置

Log4j2 配置

log4j2-spring.xml

结构化日志记录 (JSON)

依赖项

MDC（映射诊断上下文）

结构化日志输出

最佳实践

应该做

不应该做

安全性

何时不使用此技能

反模式

快速故障排除

参考

With Lombok

Log Levels

Parameterized Messages (Best Practice)

Logback Configuration

Spring Boot (logback-spring.xml)

application.yml Configuration

Log4j2 Configuration

log4j2-spring.xml

Structured Logging (JSON)

Dependencies

MDC (Mapped Diagnostic Context)

Structured Log Output

Best Practices

DO

DON'T

Security

When NOT to Use This Skill

Anti-Patterns

Quick Troubleshooting

Reference

最新 Skills