1. 項(xiàng)目背景與核心訴求在基于Spring Boot和MyBatis-Plus的后端開(kāi)發(fā)中SQL日志的打印控制是一個(gè)高頻且看似簡(jiǎn)單實(shí)則暗藏玄機(jī)的需求。無(wú)論是日常開(kāi)發(fā)調(diào)試還是線(xiàn)上問(wèn)題排查我們都需要清晰地看到MyBatis-Plus最終執(zhí)行的SQL語(yǔ)句及其參數(shù)。然而很多開(kāi)發(fā)者尤其是剛接觸這套技術(shù)棧的朋友常常會(huì)困惑為什么我明明在application.yml里配置了logging.levelSQL日志就是不出現(xiàn)或者為什么在測(cè)試環(huán)境能正常打印的日志到了生產(chǎn)環(huán)境卻關(guān)不掉導(dǎo)致日志文件暴漲這背后涉及到Spring Boot的日志抽象、MyBatis-Plus自身的日志實(shí)現(xiàn)機(jī)制以及不同配置方式的優(yōu)先級(jí)問(wèn)題。簡(jiǎn)單地在配置文件里寫(xiě)一行l(wèi)ogging.level.com.xxx.mapperdebug在某些情況下可能并不奏效。今天我們就來(lái)徹底拆解MyBatis-Plus開(kāi)啟與關(guān)閉SQL日志打印的幾種主流方式深入其原理并分享我在實(shí)際項(xiàng)目中踩過(guò)的坑和總結(jié)的最佳實(shí)踐。目標(biāo)是讓你在任何環(huán)境下都能精準(zhǔn)、可控地管理SQL日志的輸出。2. 理解MyBatis-Plus的日志實(shí)現(xiàn)機(jī)制要控制日志首先得知道日志從哪里來(lái)。MyBatis-Plus本身并不直接產(chǎn)生日志它依賴(lài)于底層的MyBatis框架。MyBatis通過(guò)其內(nèi)置的Log接口來(lái)記錄日志這個(gè)接口有多種實(shí)現(xiàn)例如SLF4J、Log4J、Log4J2、JDK Logging等。Spring Boot默認(rèn)使用的是SLF4J Logback的組合。MyBatis-Plus或者說(shuō)MyBatis在執(zhí)行SQL時(shí)其日志輸出主要來(lái)源于兩個(gè)地方MyBatis核心的Executor組件它在執(zhí)行Statement時(shí)會(huì)通過(guò)配置的Log實(shí)現(xiàn)類(lèi)來(lái)打印SQL語(yǔ)句、參數(shù)和結(jié)果。這個(gè)日志級(jí)別通常由logging.level配置文件中對(duì)應(yīng)Mapper接口的包路徑來(lái)控制。MyBatis-Plus的P6Spy或性能分析插件等第三方工具這些工具通過(guò)攔截JDBC操作以更詳細(xì)或更格式化的方式輸出SQL。它們的開(kāi)關(guān)通常由獨(dú)立的配置項(xiàng)控制。最常見(jiàn)的困惑點(diǎn)在于你以為你在控制MyBatis的日志但實(shí)際上你的配置可能并沒(méi)有被正確應(yīng)用。這是因?yàn)镸yBatis在初始化SqlSessionFactory時(shí)會(huì)從配置中讀取logImpl屬性來(lái)決定使用哪種具體的日志實(shí)現(xiàn)。如果這個(gè)配置與Spring Boot默認(rèn)的日志門(mén)面不匹配或者日志實(shí)現(xiàn)類(lèi)在類(lèi)路徑上的加載順序有問(wèn)題就會(huì)導(dǎo)致logging.level配置失效。注意一個(gè)常見(jiàn)的誤區(qū)是認(rèn)為配置了mybatis-plus.configuration.log-impl就萬(wàn)事大吉。這個(gè)配置主要用于指定MyBatis內(nèi)部使用的日志實(shí)現(xiàn)類(lèi)如org.apache.ibatis.logging.slf4j.Slf4jImpl但它并不直接控制日志級(jí)別。日志級(jí)別仍然由Spring Boot的logging.level體系管理。指定正確的log-impl是為了讓MyBatis的日志調(diào)用能夠正確地橋接到SLF4J從而使logging.level配置生效。3. 開(kāi)啟SQL日志打印的三種核心方式根據(jù)不同的場(chǎng)景和需求我們可以選擇以下三種方式來(lái)開(kāi)啟SQL日志。3.1 方式一通過(guò)Spring Boot標(biāo)準(zhǔn)配置推薦這是最符合Spring Boot生態(tài)、最推薦的方式。其原理是通過(guò)設(shè)置特定Mapper接口所在包的日志級(jí)別為DEBUG。操作步驟在application.yml或application.properties配置文件中添加如下配置。# application.yml 示例 logging: level: # 將你的Mapper接口所在的包路徑設(shè)置為DEBUG級(jí)別 com.yourcompany.yourproject.mapper: debug# application.properties 示例 logging.level.com.yourcompany.yourproject.mapperdebug原理與細(xì)節(jié)com.yourcompany.yourproject.mapper需要替換為你項(xiàng)目中Mapper接口的實(shí)際包名。設(shè)置為DEBUG級(jí)別是因?yàn)镸yBatis執(zhí)行SQL的日志信息通常是在DEBUG級(jí)別輸出的。這種方式生效的前提是MyBatis使用的日志實(shí)現(xiàn)已經(jīng)正確集成到SLF4J。在Spring Boot默認(rèn)環(huán)境下這一點(diǎn)通常是滿(mǎn)足的。實(shí)測(cè)心得范圍控制你可以精確控制到某個(gè)具體的Mapper包例如logging.level.com.xxx.user.mapper: debug而其他包的日志保持INFO級(jí)別避免日志泛濫。環(huán)境區(qū)分通常我們會(huì)在application-dev.yml中開(kāi)啟此配置在application-prod.yml中將其關(guān)閉或設(shè)置為WARN/ERROR。輸出內(nèi)容這種方式打印的SQL日志默認(rèn)格式可能包含執(zhí)行時(shí)間、SQL語(yǔ)句和參數(shù)但參數(shù)是?占位符形式具體的參數(shù)值會(huì)另起一行顯示有時(shí)可讀性不是最佳。3.2 方式二在MyBatis-Plus配置中指定日志實(shí)現(xiàn)當(dāng)方式一不生效時(shí)很可能是MyBatis沒(méi)有使用SLF4J實(shí)現(xiàn)。此時(shí)我們需要在MyBatis-Plus的配置中顯式指定。操作步驟在application.yml中配置MyBatis-Plus的configuration。mybatis-plus: configuration: # 關(guān)鍵配置指定MyBatis使用SLF4J進(jìn)行日志記錄 log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl同時(shí)依然需要配合方式一設(shè)置對(duì)應(yīng)Mapper包的logging.level為DEBUG。為什么需要這樣做MyBatis支持多種日志實(shí)現(xiàn)SLF4J, LOG4J, LOG4J2, JDK_LOGGING等。它有一個(gè)自動(dòng)發(fā)現(xiàn)機(jī)制會(huì)按順序在類(lèi)路徑中尋找這些日志框架。有時(shí)由于依賴(lài)沖突或類(lèi)加載順序它可能選擇了非SLF4J的實(shí)現(xiàn)比如commons-logging導(dǎo)致其日志輸出脫離了Spring Boot的logging.level管理體系。顯式指定log-impl就是告訴MyBatis“別自己找了就用這個(gè)”?？蛇x的值org.apache.ibatis.logging.slf4j.Slf4jImpl(使用SLF4J配合Spring Boot Logback)org.apache.ibatis.logging.stdout.StdOutImpl(直接打印到控制臺(tái)簡(jiǎn)單粗暴不推薦生產(chǎn)使用)org.apache.ibatis.logging.log4j2.Log4j2Impl(使用Log4j2)org.apache.ibatis.logging.log4j.Log4jImpl(使用Log4j)踩坑記錄我曾經(jīng)遇到一個(gè)項(xiàng)目引入了某個(gè)老版本的中間件JAR包它依賴(lài)了commons-logging。導(dǎo)致MyBatis自動(dòng)選擇了JakartaCommonsLoggingImpl使得logging.level配置完全失效。排查了很久最終通過(guò)顯式配置log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl解決了問(wèn)題。所以如果你的SQL日志出不來(lái)這是第一個(gè)要檢查的配置點(diǎn)。3.3 方式三使用MyBatis-Plus的性能分析插件適用于開(kāi)發(fā)環(huán)境MyBatis-Plus提供了一個(gè)PerformanceInterceptor新版中已標(biāo)記為Deprecated建議使用MybatisPlusInterceptor添加PerformanceInterceptor它不僅能打印SQL還能輸出SQL執(zhí)行時(shí)間對(duì)性能調(diào)優(yōu)很有幫助。操作步驟以新版本為例創(chuàng)建一個(gè)配置類(lèi)如MybatisPlusConfig。在其中配置MybatisPlusInterceptor并添加PerformanceInterceptor。import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor; import com.baomidou.mybatisplus.extension.plugins.inner.PerformanceInterceptor; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Profile; Configuration public class MybatisPlusConfig { /** * 使用 Profile 注解確保該插件只在dev或test環(huán)境下生效 */ Bean Profile({dev, test}) public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 添加性能分析插件會(huì)打印SQL及執(zhí)行時(shí)間 interceptor.addInnerInterceptor(new PerformanceInterceptor()); // 你可以繼續(xù)添加其他插件比如分頁(yè)插件 // interceptor.addInnerInterceptor(new PaginationInnerInterceptor()); return interceptor; } }特性與注意事項(xiàng)執(zhí)行時(shí)間該插件會(huì)打印每條SQL的執(zhí)行時(shí)間單位ms對(duì)于發(fā)現(xiàn)慢SQL非常直觀(guān)。格式化SQL它輸出的SQL是格式化的有換行和縮進(jìn)并且參數(shù)是直接替換到SQL語(yǔ)句中的可讀性極佳。環(huán)境隔離強(qiáng)烈建議使用Profile注解將其限制在開(kāi)發(fā)、測(cè)試環(huán)境。因?yàn)槭占@些信息本身也有性能開(kāi)銷(xiāo)且生產(chǎn)環(huán)境日志量巨大。過(guò)時(shí)警告直接使用PerformanceInterceptorBean的方式在新版中已過(guò)時(shí)應(yīng)將其作為InnerInterceptor添加到MybatisPlusInterceptor中。與方式一/二的關(guān)系此插件是獨(dú)立工作的。即使你不配置logging.level只要這個(gè)插件被加載它就會(huì)打印SQL。它和方式一/二的日志輸出是并存的你可能會(huì)看到兩條相似的SQL日志。4. 關(guān)閉SQL日志打印的策略關(guān)閉日志通常是為了生產(chǎn)環(huán)境的整潔和性能。關(guān)閉策略與開(kāi)啟方式一一對(duì)應(yīng)。4.1 關(guān)閉Spring Boot標(biāo)準(zhǔn)配置的輸出這是最直接的方式將對(duì)應(yīng)包的日志級(jí)別調(diào)整為INFO、WARN或ERROR。# application-prod.yml logging: level: com.yourcompany.yourproject.mapper: info # 或 warn/error4.2 移除或更改MyBatis日志實(shí)現(xiàn)如果你顯式配置了log-impl可以將其改為一個(gè)不輸出SQL的級(jí)別或者干脆不配置讓MyBatis自動(dòng)選擇但有一定風(fēng)險(xiǎn)。更穩(wěn)妥的做法是在生產(chǎn)環(huán)境配置文件中將log-impl指向一個(gè)NoLoggingImpl如果存在或者確保其級(jí)別為INFO以上。實(shí)際上只要logging.level設(shè)置為INFO無(wú)論log-impl是什么都不會(huì)輸出DEBUG級(jí)別的SQL日志。4.3 確保性能分析插件不在生產(chǎn)環(huán)境加載這是最關(guān)鍵的一環(huán)。如果性能分析插件被加載到生產(chǎn)環(huán)境它會(huì)無(wú)視logging.level的設(shè)置強(qiáng)行打印SQL。確保方法如下使用Profile注解如上文示例這是最優(yōu)雅的方式。通過(guò)配置條件注入使用ConditionalOnProperty等注解根據(jù)配置文件中的屬性決定是否創(chuàng)建該Bean。徹底注釋或刪除在打包生產(chǎn)環(huán)境時(shí)確保配置類(lèi)中相關(guān)插件的Bean定義被移除或禁用。我踩過(guò)的一個(gè)大坑在一次預(yù)發(fā)布環(huán)境部署后發(fā)現(xiàn)日志量異常磁盤(pán)很快告警。排查后發(fā)現(xiàn)是運(yùn)維同學(xué)錯(cuò)誤地將包含Profile(“dev”)的配置類(lèi)打入了通用包而預(yù)發(fā)布環(huán)境激活的Profile包含了dev導(dǎo)致性能分析插件被激活。教訓(xùn)是環(huán)境隔離的配置一定要雙重確認(rèn)不僅依賴(lài)注解打包腳本和部署流程也要有相應(yīng)檢查。5. 高級(jí)場(chǎng)景與疑難排查5.1 動(dòng)態(tài)控制日志開(kāi)關(guān)有時(shí)我們希望在運(yùn)行時(shí)動(dòng)態(tài)開(kāi)啟某個(gè)特定功能的SQL日志比如在排查某個(gè)復(fù)雜業(yè)務(wù)問(wèn)題時(shí)。這可以通過(guò)編程方式動(dòng)態(tài)修改Logback的日志級(jí)別來(lái)實(shí)現(xiàn)。import org.slf4j.LoggerFactory; import ch.qos.logback.classic.Level; import ch.qos.logback.classic.Logger; public class LogLevelUtil { public static void setMapperLogLevel(boolean enable) { Logger logger (Logger) LoggerFactory.getLogger(com.yourcompany.yourproject.mapper); logger.setLevel(enable ? Level.DEBUG : Level.INFO); // 如果需要立即生效可以調(diào)用 logger.setLevel()Logback會(huì)處理。 // 注意此修改是內(nèi)存中的應(yīng)用重啟或配置刷新后會(huì)失效。 } }你可以通過(guò)一個(gè)管理端的API來(lái)調(diào)用這個(gè)方法實(shí)現(xiàn)動(dòng)態(tài)開(kāi)關(guān)。但請(qǐng)注意這會(huì)影響整個(gè)Mapper包的日志級(jí)別。5.2 只打印慢SQL日志生產(chǎn)環(huán)境我們可能不想看所有SQL但非常關(guān)心執(zhí)行時(shí)間超過(guò)一定閾值的慢SQL。這可以通過(guò)自定義攔截器或使用Logback的EvaluatorFilter來(lái)實(shí)現(xiàn)。自定義攔截器思路繼承MybatisPlusInterceptor或?qū)崿F(xiàn)MyBatis的Interceptor接口在invoke方法中計(jì)算SQL執(zhí)行時(shí)間如果超過(guò)閾值如1000ms則通過(guò)StatementHandler獲取到SQL信息并用log.warn()記錄到日志中。這樣慢SQL就會(huì)以WARN級(jí)別輸出即使整體日志級(jí)別是INFO也能看到。5.3 日志不輸出的完整排查鏈路當(dāng)你按照上述配置后SQL日志依然沒(méi)有出現(xiàn)可以按照以下鏈路排查檢查配置位置確認(rèn)application.yml文件是否在正確的classpath下激活的Profile是否正確。檢查包路徑確認(rèn)logging.level配置的包路徑是否完全匹配你的Mapper接口所在包。一個(gè)字母之差都會(huì)導(dǎo)致失效。檢查日志級(jí)別確認(rèn)你的日志框架全局級(jí)別沒(méi)有覆蓋。例如在Logback的logback-spring.xml中是否有全局的root levelINFO這不會(huì)影響包級(jí)別設(shè)置但需確認(rèn)沒(méi)有其他過(guò)濾器攔截。檢查MyBatis日志實(shí)現(xiàn)在應(yīng)用啟動(dòng)時(shí)查看日志開(kāi)頭部分MyBatis通常會(huì)打印一行如“Logging initialized using class org.apache.ibatis.logging.slf4j.Slf4jImpl adapter”的信息。確認(rèn)它使用的是Slf4jImpl。檢查依賴(lài)沖突運(yùn)行mvn dependency:tree或gradle dependencies檢查是否存在多個(gè)日志框架的綁定如同時(shí)存在logback-classic和log4j-over-slf4j沖突或者存在commons-logging的舊版本。使用exclusions排除不必要的傳遞依賴(lài)。使用調(diào)試模式臨時(shí)將logging.level.root設(shè)置為DEBUG觀(guān)察MyBatis相關(guān)的日志初始化過(guò)程看是否有錯(cuò)誤或警告信息。驗(yàn)證SQL是否執(zhí)行最根本的通過(guò)數(shù)據(jù)庫(kù)監(jiān)控或業(yè)務(wù)結(jié)果確認(rèn)你的代碼確實(shí)執(zhí)行了數(shù)據(jù)庫(kù)操作。有可能你的方法根本沒(méi)被調(diào)用或者走了緩存。5.4 日志輸出格式美化默認(rèn)的SQL日志可讀性可能不佳。你可以配置Logback的pattern來(lái)美化輸出。在application.yml中l(wèi)ogging: pattern: console: “%d{yyyy-MM-dd HH:mm:ss} - %logger{36} - %msg%n” # 簡(jiǎn)化控制臺(tái)格式 level: com.yourcompany.mapper: debug或者使用更復(fù)雜的logback-spring.xml文件進(jìn)行詳細(xì)控制例如將SQL日志單獨(dú)輸出到另一個(gè)文件。6. 生產(chǎn)環(huán)境最佳實(shí)踐總結(jié)根據(jù)多年項(xiàng)目經(jīng)驗(yàn)我總結(jié)出以下關(guān)于MyBatis-Plus SQL日志的生產(chǎn)環(huán)境實(shí)踐準(zhǔn)則開(kāi)發(fā)/測(cè)試環(huán)境采用“方式一 方式三”組合。application-dev.yml中配置logging.level.xxx.mapper: debug。通過(guò)Profile(“dev”)啟用PerformanceInterceptor插件獲得帶執(zhí)行時(shí)間的格式化SQL。這樣既能通過(guò)標(biāo)準(zhǔn)日志查看所有SQL又能通過(guò)插件快速定位性能瓶頸。生產(chǎn)環(huán)境采用“方式一關(guān)閉”。application-prod.yml中配置logging.level.xxx.mapper: info或warn。絕對(duì)確保PerformanceInterceptor等插件未被加載通過(guò)Profile嚴(yán)格控制?？梢钥紤]配置log-impl但非必須。重點(diǎn)是關(guān)閉DEBUG級(jí)別輸出。依賴(lài)管理在pom.xml中明確聲明日志依賴(lài)避免傳遞依賴(lài)帶來(lái)的沖突。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-logging/artifactId !-- 默認(rèn)使用Logback -- /dependency如果遇到?jīng)_突果斷使用exclusions排除其他日志框架的綁定。日志歸檔與監(jiān)控生產(chǎn)環(huán)境的日志即使是INFO級(jí)別也應(yīng)配置合理的滾動(dòng)策略按天、按大小分割、歸檔和清理策略。對(duì)于ERROR級(jí)別的日志建議配置告警及時(shí)通知開(kāi)發(fā)人員?？刂芐QL日志的打印是后端開(kāi)發(fā)者的一項(xiàng)基本功。它不僅僅是加一行配置那么簡(jiǎn)單而是要求我們對(duì)Spring Boot的日志體系、MyBatis的內(nèi)部機(jī)制以及項(xiàng)目自身的環(huán)境管理有清晰的認(rèn)識(shí)。從“能用”到“用得穩(wěn)”、“用得好”中間差的就是對(duì)這些細(xì)節(jié)的理解和把控。希望這篇內(nèi)容能幫你徹底理清這里的門(mén)道在下次遇到SQL日志相關(guān)問(wèn)題時(shí)能夠快速定位優(yōu)雅解決。