Spring Boot 3.x 日志配置与 Logback 集成指南

一、Spring Boot 3.x 日志基础

Spring Boot 3.x 默认使用 Logback 作为日志框架，通过
spring-boot-starter-logging 自动引入。

1. 基本配置方式（application.properties/yml）

# 日志级别
logging.level.root=INFO
logging.level.org.springframework=WARN
logging.level.com.myapp=DEBUG

# 日志文件
logging.file.name=app.log
logging.file.path=/var/log

# 控制台与文件日志格式
logging.pattern.console=%d{yyyy-MM-dd HH:mm:ss} - %msg%n
logging.pattern.file=%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n

二、Logback 高级配置

1. 自定义 logback-spring.xml

在 src/main/resources 下创建 logback-spring.xml：

<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" scanPeriod="30 seconds">
    <!-- 环境变量 -->
    <springProperty scope="context" name="APP_NAME" source="spring.application.name" defaultValue="spring-boot-app"/>
    <springProperty scope="context" name="LOG_PATH" source="logging.file.path" defaultValue="./logs"/>
    <springProperty scope="context" name="LOG_LEVEL" source="logging.level.root" defaultValue="INFO"/>

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

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

    <!-- JSON 格式日志（用于 ELK/EFK） -->
    <appender name="JSON_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/${APP_NAME}.json</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/${APP_NAME}-%d{yyyy-MM-dd}.%i.json</fileNamePattern>
            <maxFileSize>50MB</maxFileSize>
            <maxHistory>30</maxHistory>
            <totalSizeCap>1GB</totalSizeCap>
        </rollingPolicy>
        <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder"/>
    </appender>

    <!-- 日志级别 -->
    <root level="${LOG_LEVEL}">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="FILE"/>
    </root>

    <!-- 特定包日志级别 -->
    <logger name="org.springframework" level="WARN"/>
    <logger name="com.myapp" level="DEBUG"/>
</configuration>

依赖（JSON日志）：

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

2. 多环境配置（Spring Profile）

<springProfile name="dev">
    <root level="DEBUG">
        <appender-ref ref="CONSOLE"/>
    </root>
</springProfile>

<springProfile name="prod">
    <root level="INFO">
        <appender-ref ref="FILE"/>
        <appender-ref ref="JSON_FILE"/>
        <appender-ref ref="ASYNC_FILE"/>
    </root>
</springProfile>

三、SQL 日志记录方式汇总

1. Hibernate / JPA

spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE

2. MyBatis

logging.level.com.myapp.mapper=DEBUG

3. Logback 直接配置

<logger name="org.hibernate.SQL" level="DEBUG"/>
<logger name="org.hibernate.type.descriptor.sql" level="TRACE"/>
<logger name="org.mybatis" level="DEBUG"/>
<logger name="java.sql" level="DEBUG"/>
<logger name="javax.sql" level="DEBUG"/>

4. 使用 p6spy（推荐）

依赖：

<dependency>
    <groupId>com.github.gavlyukovskiy</groupId>
    <artifactId>p6spy-spring-boot-starter</artifactId>
    <version>1.9.0</version>
</dependency>

配置：

spring.datasource.url=jdbc:p6spy:mysql://localhost:3306/mydb
logging.level.p6spy=INFO

spy.properties：

appender=com.p6spy.engine.spy.appender.Slf4JLogger
logMessageFormat=com.p6spy.engine.spy.appender.CustomLineFormat
customLogMessageFormat=%(executionTime)ms | %(category) | connection %(connectionId) | %(sqlSingleLine)

# 慢 SQL 记录（超过500ms）
executionThreshold=500
excludecategories=info,debug,result,batch

5. 使用 Datasource Proxy

依赖：

<dependency>
    <groupId>net.ttddyy</groupId>
    <artifactId>datasource-proxy</artifactId>
    <version>1.8</version>
</dependency>

配置 Bean：

@Bean
public DataSource dataSource(DataSource originalDataSource) {
    return ProxyDataSourceBuilder
            .create(originalDataSource)
            .name("ProxyDS")
            .countQuery()
            .logQueryBySlf4j(SLF4JLogLevel.INFO)
            .multiline()
            .jsonFormat()
            .build();
}

四、高级日志功能

1. MDC（请求链路追踪）

MDC.put("traceId", UUID.randomUUID().toString());
try {
    log.info("业务处理开始");
} finally {
    MDC.clear();
}

Logback pattern：

<pattern>%d{yyyy-MM-dd HH:mm:ss} [%X{traceId}] %-5level %logger{36} - %msg%n</pattern>

结合 Spring Cloud Sleuth / OpenTelemetry 可自动注入 traceId、spanId。

2. 异步日志（高并发场景推荐）

<appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
    <queueSize>1024</queueSize>
    <discardingThreshold>20</discardingThreshold>
    <includeCallerData>false</includeCallerData>
    <appender-ref ref="FILE"/>
</appender>

3. 日志告警与监控

（1）Sentry 告警

<dependency>
    <groupId>io.sentry</groupId>
    <artifactId>sentry-logback</artifactId>
    <version>6.25.0</version>
</dependency>

<appender name="SENTRY" class="io.sentry.logback.SentryAppender">
    <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
        <level>ERROR</level>
    </filter>
</appender>

（2）ELK / EFK 日志收集

• 使用 JSON 格式日志
• 配合 Filebeat/Fluentd 收集到 Elasticsearch
• Kibana/Graylog 分析

五、最佳实践

开发环境

• 控制台彩色日志（易调试）
• 开启全量 SQL 日志（p6spy）
• 关键业务流添加 TRACE 日志

测试环境

• 开启 SQL 慢查询统计
• 使用 JSON 日志，模拟生产采集

生产环境

• 日志级别：INFO+
• 使用异步日志，避免阻塞
• 使用 JSON 格式日志，支持 ELK/EFK
• 为关键业务添加审计日志
• 慢 SQL 告警，避免全量 SQL 打印

至此，你的文章已经变成一个 既有入门配置，又有高级实战与最佳实践 的完整版指南。