SpringBoot3日志实战：Logback配置与MybatisPlus SQL日志排查

系列第02篇，接着上篇搭好的SpringBoot3 + MybatisPlus骨架，今天把日志这层彻底补上。日志这东西平时不起眼，真出问题的时候比什么都管用——SQL慢不慢、接口报错在哪、参数到底传成了什么，全得靠它说话。这篇从框架选型讲到logback-spring.xml实战配置，再讲到MybatisPlus的SQL日志怎么打、怎么关，顺带把分页失效和单页500条限制这两个和日志排查强相关的坑一起讲了。适合刚搭好SpringBoot3项目、日志还停留在IDE控制台随手打印的朋友，也适合已经上线但日志乱成一锅粥的团队参考。

1. 日志框架选型：SpringBoot3下的logback与log4j2

1.1 SpringBoot3默认日志栈是怎么拼起来的

先说结论：SpringBoot3默认用的是SLF4J门面 + Logback实现，这套组合从SpringBoot1.x一路走到3.x，没有变过。SpringBoot3基于SpringFramework6和JDK17，日志上面最大的变化是SLF4J升级到了2.x，Logback升级到了1.4.x，但传统API基本兼容，老配置里那些%d、%level占位符写法照搬就能用。

很多刚转SpringBoot3的同学会疑惑：明明是spring-boot-starter-web引入的依赖，日志功能怎么来的？实际上spring-boot-starter-web会传递引入spring-boot-starter-logging，它替你管理好了SLF4J、Logback、Log4j-to-SLF4J桥接这些东西。也就是说，你引入Web起步依赖那一刻，日志框架已经默默初始化完毕。

这里有个常见的认知误区：日志插件Logback本身是自动装配的，logback-spring.xml文件只是对格式化、存储位置、滚动策略做定制，并不是说你不写这个XML文件项目就没有日志。默认情况下SpringBoot已经把INFO级别以上的日志输出到控制台了。

1.2 想切log4j2？先想清楚你到底需要什么

网络热词里“springboot3 log4j2”被频繁搜索，说明很多人主动想换掉Logback。Logback和Log4j2的性能对比，网上测出来Log4j2在异步模式下稍微占优，但在绝大多数业务系统里，这个差距远没有“前端慢50ms”来得明显。我见过太多项目为了“性能好”换了日志框架，结果配置折腾一周，收益约等于零。

如果你非换不可，操作也不难：排除spring-boot-starter-logging，引入spring-boot-starter-log4j2。Maven里大概是这样的写法：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <exclusions> <exclusion> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-logging</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-log4j2</artifactId> </dependency>

切过去以后，log4j2-spring.xml就是你的主配置。但注意，SpringBoot3下Log4j2的版本要选2.17.x以上，避免已知的高危漏洞。我的建议是：除非团队里已经有成熟的Log4j2配置资产，或者明确测出Logback成为性能瓶颈，否则这条迁移路可以不走。能用一个框架解决的问题，没必要引入第二套配置心智负担。

2. logback-spring.xml配置实战：一套能直接Copy的模板

2.1 一份经得起生产环境拷打的配置模板

我对日志配置的要求向来是三条：控制台要清爽、文件要按天滚动、大流量下不能阻塞业务线程。下面这份配置是我在多个SpringBoot3项目中复用过的模板，直接贴出来，关键节点加了注释。

<?xml version="1.0" encoding="UTF-8"?> <configuration> <!-- 日志文件根目录，支持外部传入，不传默认用本地logs目录 --> <property name="LOG_HOME" value="${LOG_HOME:-./logs}" /> <!-- 单条日志格式：时间 线程 级别 logger名称 消息 --> <property name="PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{40} - %msg%n" /> <!-- 控制台输出 --> <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>${PATTERN}</pattern> <charset>UTF-8</charset> </encoder> </appender> <!-- 全量日志文件，按天滚动，保留30天 --> <appender name="FILE_ALL" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>${LOG_HOME}/app.log</file> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <fileNamePattern>${LOG_HOME}/app.%d{yyyy-MM-dd}.log</fileNamePattern> <maxHistory>30</maxHistory> <totalSizeCap>5GB</totalSizeCap> </rollingPolicy> <encoder> <pattern>${PATTERN}</pattern> <charset>UTF-8</charset> </encoder> </appender> <!-- 异步输出，降低日志对业务线程的阻塞 --> <appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender"> <queueSize>1024</queueSize> <discardingThreshold>0</discardingThreshold> <neverBlock>true</neverBlock> <appender-ref ref="FILE_ALL" /> </appender> <root level="INFO"> <appender-ref ref="CONSOLE" /> <appender-ref ref="ASYNC_FILE" /> </root> </configuration>

LOG_HOME用${LOG_HOME:-./logs}这种写法，意思是优先读取外部环境变量LOG_HOME，取不到就回退到项目运行目录下的logs文件夹。这个写法非常实用，开发环境不用配置，生产环境在启动脚本里export LOG_HOME=/data/logs/xxx即可。

文件名我故意用了logback-spring.xml而不是logback.xml。这个细节很关键：logback-spring.xml会被SpringBoot的日志初始化器接管，能识别springProfile标签做多环境切换，而logback.xml是Logback原生配置，SpringBoot的扩展能力它用不了。

2.2 滚动策略到底怎么选，别等磁盘满了才后悔

很多团队的日志轮转策略是随便写的，最常见的坑就是只配置了maxHistory=30，但是每天一个文件1GB，30天就是30GB，磁盘照样被塞爆。所以我在第15行加了totalSizeCap，它的作用是所有归档文件总大小超过5GB时，删除最老的归档文件。

TimeBasedRollingPolicy+maxHistory+totalSizeCap三个参数建议一起配置。fileNamePattern中%d{yyyy-MM-dd}决定了按天滚动，如果想要按小时滚动，写%d{yyyy-MM-dd-HH}即可。这里有个细节：按小时滚动时，maxHistory的“30”表示30小时而不是30天，别理解岔了。

异步Appender是我一定要加的。同步写日志时，业务线程要等磁盘IO完成才能继续跑，高峰期一个接口打几十条日志，延迟基本肉眼可见。AsyncAppender把日志事件先塞进内存队列，后台线程消费写文件。队列默认queueSize=256，业务系统建议调到1024以上，否则有日志丢失风险。neverBlock=true意味着队列满了直接丢日志也不阻塞业务，这个取舍在日志系统里是合理的——查询日志永远是辅助手段，不是业务流程的组成部分。

2.3 多环境配置：开发打Debug，生产打Info

有了logback-spring.xml，多环境切换就非常简单。开发环境想看SQL、看调试信息，生产环境只留INFO以上，用springProfile标签隔离：

<springProfile name="dev,test"> <logger name="com.example" level="DEBUG" /> </springProfile> <springProfile name="prod"> <logger name="com.example" level="INFO" /> </springProfile>

application.yml里对应设置spring.profiles.active: dev就能激活。这套机制比代码里判断环境再手动改日志级别优雅得多，配置和代码完全解耦。我还习惯在启动参数上加--logging.level.com.example=DEBUG临时调整级别，排查问题时不用改文件重启，命令行覆盖优先于XML配置，这个优先级关系值得记一下。

3. MybatisPlus的SQL日志打印：两种姿势，各踩一次坑

3.1 姿势一：log-impl=StdOutImpl，开发环境速成

MybatisPlus打印SQL最粗暴的方式，是在application.yml里指定日志实现：

mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

效果是每条SQL执行时，控制台直接输出Preparing:和Parameters:两行。我当年第一次配完看这个输出，直呼真香，但很快发现两个问题：

第一，StdOutImpl是往标准输出里直接打印，不走Logback的Appender。这意味着你前面精心配置的文件滚动、异步队列对它完全无效，SQL日志只会出现在控制台，线上环境根本捞不到。

第二，它会打印所有Mapper方法的SQL，包括那些非查询的内部辅助SQL。日志量在并发稍高的时候直接爆炸，我见过一个线上事故，就是因为有人把这个配置发布到了生产，日志文件一天涨了几十GB。

所以这个配置的正确使用场景只有一个：本地开发。上线前必须注释掉，或者用springProfile把这段配置限定在dev环境。

3.2 姿势二：logger级别控制，让SQL日志进文件

真正适合生产环境的做法，是把Mapper包名的日志级别设为DEBUG，让SQL输出走Logback统一管理。在application.yml里这样写：

logging: level: com.example.demo.mapper: debug

这样MybatisPlus会发现Mapper接口的logger是DEBUG级别，自动用Slf4jLogger输出SQL到Logback链路——文件、滚动、异步全部生效。日志格式里能看到这样的输出：

2026-03-22 14:30:01.123 [http-nio-8080-exec-2] DEBUG com.example.demo.mapper.UserMapper.selectPage - ==> Preparing: SELECT id,name,age FROM user WHERE deleted=0 LIMIT ?,? 2026-03-22 14:30:01.125 [http-nio-8080-exec-2] DEBUG com.example.demo.mapper.UserMapper.selectPage - ==> Parameters: 0(Long), 10(Long)

这个姿势的好处是：SQL日志和业务日志在同一个文件里，排查问题时前后文都在，能一眼看清一个请求的完整调用链。生产环境把com.example.demo.mapper改成INFO级别，SQL日志自动消失，不需要改代码。

有一点需要注意：log-impl不配置时，MybatisPlus默认走SLF4J探测机制，也就是只要Mapper的logger级别是DEBUG就能打SQL。但如果你在配置里设置了log-impl: StdOutImpl，它就会跳过这个探测，直接往控制台打，文件日志方案就不生效了。两种方式不要混用。

3.3 Preparing和Parameters到底在告诉你什么

看SQL日志不要只看SQL文本，Parameters那行信息密度更高。它显示的是PreparedStatement绑定参数的实际值和类型全限定名，比如0(Long)表示第一个分页参数是Long类型的0。

这个对排查问题非常有用。我一朋友排查一个诡异的“查不到数据”问题，看SQL文本怎么看都对，后来看了一眼Parameters才发现，代码里把String "1"传给了Integer字段，Mybatis做了隐式类型转换，查询结果自然面目全非。如果只打印SQL不打印参数，这种问题光靠肉眼是定位不了的。

还有个小技巧：数据库连接池如果是Druid，它的StatFilter也能输出慢SQL和SQL执行统计，但那是连接池维度的，和MybatisPlus的日志是两个体系。我建议别在同一层同时开两种SQL日志，重复打印会让日志文件迅速膨胀，还会把关键信息淹没在冗余输出里。

3.4 生产环境SQL日志的正确打开方式

生产环境不是不能看SQL，而是不能把所有SQL都打出来。我采用的方案是：把Mapper级别设成INFO保持静默，但在数据库层开启慢查询日志。以MySQL为例：

SET GLOBAL slow_query_log = ON; SET GLOBAL long_query_time = 2;

这样超过2秒的SQL会记录到MySQL的慢查询日志文件，业务侧日志不受影响。配合链路追踪记录耗时，就能做到“全量SQL不出业务日志，异常慢SQL一个不落”。这个思路比在生产环境打印所有SQL更优雅，也更符合运维安全原则。

4. 日志与分页插件的关联排查：分页失效和500条上限

4.1 从日志里一眼判断分页有没有生效

分页插件是否正常，体现到日志上非常直白：分页生效的SQL末尾带着LIMIT ?,?；分页没生效，SQL就是全量查询，没有LIMIT。所以判断分页有没有被成功拦截，先看日志里有没有LIMIT，这比翻代码还快。

我第一次遇到“分页失效”时，折腾了很久因为业务逻辑没错，后来在日志里看到一条没有LIMIT的全量查询SQL，才确定MybatisPlus的拦截器根本没执行。配置分页拦截器的标准写法是在配置类里注册一个MybatisPlusInterceptorBean，并添加PaginationInnerInterceptor：

@Configuration public class MybatisPlusConfig { @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); PaginationInnerInterceptor pagination = new PaginationInnerInterceptor(DbType.MYSQL); // 关键：显式设置单页上限，避免不同版本默认行为带来的差异 pagination.setMaxLimit(-1L); interceptor.addInnerInterceptor(pagination); return interceptor; } }

拦截器一定要注册成Bean，交给Spring管理。有人把new PaginationInnerInterceptor()写在MybatisPlusInterceptor的实例化里，但忘了加@Bean或者没有被扫描到，分页自然失效。除了日志里没有LIMIT，这类问题常见表现就是接口返回了全量数据，或者Page.getTotal()始终等于当前页条数。

4.2 单页500条上限是怎么来的，怎么解除

“接触mybatisplus单页500条限制”这个问题在热词里反复出现，实际是被分页插件内置的maxLimit保护机制拦住了。部分版本的PaginationInnerInterceptor默认设置了一个单页最大条数上限（网上大量讨论集中在500这个数值），当你的Page的size超过这个值，分页插件会选择截断或抛异常，从业务侧看就是“明明请求了2000条，只返回了500条”。

这个机制本意是防止有人滥用全表分页拖垮数据库，但在某些合理场景下确实会误伤。解决方式在上面代码里已经写清楚了：调用pagination.setMaxLimit(-1L)表示不做限制，或者按业务需要设置一个更大的值，比如1000L。

这里多说一句：解除限制不等于鼓励单页查全表。我在实际项目中见过太多人为了图省事把size调到几千，结果数据库在高峰期CPU直接拉满。正确做法是分页参数强制校验，size超过200就提示用户缩小查询范围。限制可以在代码里解除，但数据库压垮了，邮件通知和告警可不会帮你自动善后。

4.3 拦截器顺序对日志输出的影响

MybatisPlusInterceptor支持添加多个InnerInterceptor，执行顺序遵循添加顺序。分页拦截器和其他拦截器（如乐观锁插件、租户插件）混用时，顺序不同会导致SQL改写结果完全不同，这在日志里也能看出来——明明加了乐观锁字段，SQL里却没有版本条件，八成是拦截器顺序问题。

我的建议是：分页插件要尽量保持在Interceptor列表的最内层执行，也就是其他拦截器改写完成后，最后由分页插件做LIMIT拼装。通常写法是最后添加PaginationInnerInterceptor。如果日志里SQL出现奇怪的“LIMIT嵌套”或者条件错乱，优先检查拦截器顺序。

5. 常见问题排查实录：日志没出来先别怀疑人生

5.1 日志问题速查表

把这几年我在日志上踩过的坑整理成一张速查表，按图索骥能省不少时间。

5.2 一个真实的线上日志排查案例

有次我排查一个线上问题，现象是业务逻辑都正常，但日志文件里只有框架自带的启动日志，项目里的业务日志和SQL日志一条都找不到。看application.yml里没写logging.config，代码里log.info也应该有输出，第一反应是日志级别被调高了。

结果查了半天，发现是操作同学在启动脚本里加了一个覆盖参数--logging.level.root=WARN，业务日志级别是INFO，全被压掉了。从XML配置角度怎么找都找不到问题，因为配置本身没有错，是运行时参数优先级更高。

这类问题给我的教训是：排查日志问题，不要只盯着logback-spring.xml，要从“配置优先级”的维度排查，顺序是：命令行参数 > application.yml > logback-spring.xml。哪里的配置最“外”最优先，就先从哪看起。

还有一次更隐蔽，日志文件不生成，排查了半天发现是部署目录只读，应用启动时创建不了logs文件夹。SpringBoot对日志目录创建失败是“静默降级”的，不会阻止应用启动，只在异常堆栈里留一条信息。如果你发现应用正常运行但日志文件就是没有，先检查目录权限，这个检查成本五分钟，比瞎改配置省心得多。

5.3 日志级别调优，别把性能优化成事故

日志对性能的影响远超大多数人想象。DEBUG级别的日志在每次SQL执行时都要格式化字符串，在高频接口里这种开销会被放大。生产环境把日志级别定为INFO是基本底线。

如果确实需要临时排查生产问题，我会这样做：先观察一天极少量的客户端流量，把单个Mapper包级别临时调到DEBUG，确认问题后立即改回INFO。而不是把root级别整个降到DEBUG——那样整个应用的所有框架日志全炸出来，磁盘IO直接被打满，慢SQL还没找到，系统先被日志拖垮了。

我自己在项目里还会加上一个“日志级别热更新”的小工具，通过一个内部接口来调整某个包级别，比打命令重启应用灵活得多。这个看团队需求，不是必须项，但值得尝试。

最后再分享一点自己的习惯

我现在每搭一个新项目，第一件事就是把日志配置固定成和上一个大项目一样的模板，然后先跑一个简单的查询接口，确认Preparing和Parameters都能在控制台看到，再把Mapper包名的logger级别调到DEBUG看一遍文件输出，最后改回INFO。这一套流程走下来，日志配置基本不会再出问题。

日志配置里最容易忽略的其实是“一致性”——开发环境、测试环境、生产环境的日志格式和输出目标尽量保持一致，格式不同会导致线上排查时明明看到报错却对应不上本地代码行号。统一用logback-spring.xml管理、统一日志格式，比单点排查时临时写配置可靠得多。日志不是出问题了才想起来的东西，它是项目上线之前就应该长在骨子里的基础设施。