name: mybatis-plus-dev description: >- MyBatis-Plus（baomidou）Java ORM 增強框架開發助手。 在 Java / Spring Boot 專案中開發任何資料庫增刪改查（CRUD）、分頁查詢、條件查詢、 Mapper / DAO / Service 層、實體類與表對映、邏輯刪除、批次插入、樂觀鎖、自動填充、 事務管理、SQL / XML Mapper 相關功能時使用本技能——無論使用者是否提到 MyBatis-Plus （CRUD / pagination / ORM / DAO / database query / entity mapping / transaction）。 專案依賴已含 mybatis-plus（mybatis-plus-boot-starter 及 mybatis-plus-spring-boot*-starter 系列，覆蓋 SpringBoot 2/3/4）或程式碼出現 BaseMapper / IService / ServiceImpl / LambdaQueryWrapper / LambdaUpdateWrapper / @TableId / @TableField / @TableLogic / saveBatch / selectPage 時必須使用本技能；純 MyBatis、無 ORM 或 ORM 未知專案，先主動詢問使用者是否引入 MyBatis-Plus 再開發。 不適用於：已使用 JPA / Hibernate 的專案（不建議遷移）、資料庫表結構設計/DDL、純 SQL 效能調優 （連線池/索引/慢查詢屬 DBA 層）。 agent_created: true version: 2.3.1 slug: mybatis-plus-dev displayName: MyBatis-Plus 開發助手

MyBatis-Plus 開發助手

面向日常 Java 開發的 MyBatis-Plus 編碼助手。推薦 3.5.17（3.5.x 最新線，2026），3.5.x 全線適用，3.4.x 大部分相容（差異處已註明）。 採用完全本地自包含策略：所有知識沉澱於本地 references/，執行時不依賴任何外部文件站點。

版本與依賴（先判 SpringBoot 版本）

• 切勿同時引入 mybatis / mybatis-spring-boot-starter / mybatis-spring，會與 MP 版本衝突。
• 分頁必引 mybatis-plus-jsqlparser（自 v3.5.9 起 PaginationInnerInterceptor 已從核心拆分，單獨成依賴；否則分頁靜默失效）。JDK8 專案用 mybatis-plus-jsqlparser-4.9。

第 0 步：依賴探測與啟用分支（收到資料庫訪問類任務先做這一步）

任務涉及增刪改查、分頁、條件查詢、Mapper/DAO/Service 層、實體對映、事務等編碼——即使使用者沒提 MyBatis-Plus——先檢索專案依賴（在 pom.xml / build.gradle 中搜 mybatis-plus、mybatis、spring-boot-starter-data-jpa、hibernate）：

何時使用本技能

檢查點：判定為「不適用」→ 告知使用者當前問題不在 MyBatis-Plus 範圍，建議退出本技能。判定為「部分適用」→ 告知僅 10-xml.md + 11-transaction.md 可參考，其餘不適用，讓使用者確認是否繼續。

主動行為觸發（見到這些程式碼模式時主動提醒）

• selectPage / page → 確認引了 mybatis-plus-jsqlparser + 註冊 PaginationInnerInterceptor（否則分頁靜默失效）
• @Transactional 無 rollbackFor → 顯式指定 rollbackFor = Exception.class
• saveBatch 當高效能批次 → 預設非 BATCH executor，量大需配 BatchExecutor（見 04-crud.md）
• 其餘觸發（null 不更新 / apply 注入 / Wrapper 複用 / XML 列舉 typeHandler / join 改寫 XML / 字串欄位名 / SQL 函式硬堆 Wrapper）→ 見上方「核心強約束」#3/#4/#7/#8/#9/#11 與下方「使用流程」自檢清單

核心強約束（Agent 必須遵守）

1. 繼承範式：XxxMapper extends BaseMapper<T>；Service 介面 extends IService<T>；實現類 extends ServiceImpl<XxxMapper, T>。
2. 優先用父類方法：單表 CRUD 直接用 BaseMapper / IService 提供的方法（selectList / selectById / save / updateById / page …），不要手擼冗餘 CRUD 或重複 XML。
3. Wrapper 能力邊界——超界轉 XML：Wrapper 適合單表 + 標準比較/排序/聚合條件（eq/like/in/between/orderBy…）。以下場景必須改寫 XML，不要用 Wrapper 硬堆：
4. 聯表（JOIN，含子查詢關聯）
5. 視窗函式（ROW_NUMBER()/RANK()/SUM() OVER(...) 等）
6. 聚合函式 + GROUP BY/HAVING（SUM(cnt)/COUNT(DISTINCT …)）
7. 資料庫專有函式 / 複雜表示式（DATE_FORMAT()/JSON_EXTRACT()/CASE WHEN，跨庫不可移植）
8. 自定義列別名 / 投影計算列（amount*2 AS double_amount）

用 apply()/last() 拼函式片段是反模式（注入風險 + 跨庫不可移植 + 語義不可讀），見 references/05-wrapper.md §1、references/10-xml.md。 4. null 不更新：updateById(entity) 中 entity 的 null 欄位預設不參與更新（根因：全域性 updateStrategy 預設 NOT_NULL，見 references/02-config.md §7）；要顯式置空用 UpdateWrapper.set(...) 或欄位級 @TableField(updateStrategy = FieldStrategy.ALWAYS)。 5. 邏輯刪除：推薦 0+毫秒時間戳方案（Long 欄位，logic-not-delete-value: 0，logic-delete-value: "UNIX_TIMESTAMP(now())*1000"）；用全域性 logic-delete-field 或欄位 @TableLogic；啟用後查詢自動過濾已刪除行。 6. 分頁外掛最後新增 + 顯式 DbType：MybatisPlusInterceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)) 必須放在外掛鏈最後；非 MySQL（PG/Oracle/SQLServer/達夢/金倉）必須顯式指定 DbType，否則分頁方言可能生成錯誤（total 錯或語法錯）。跨庫差異（主鍵策略/引用符/批次語法）見 references/12-dbtype.md。 7. SQL 注入防護：Wrapper.apply 用 {0} 佔位符（PreparedStatement 引數化）+ 前置 SqlInjectionUtils.check(...) 校驗，禁止字串拼接 SQL 片段。check 返回 boolean 並拋異常，不返回安全值。 8. Wrapper 不可複用：同一 Wrapper 例項多次使用會疊加條件；每次查詢 new 一個新的。 9. 列舉對映：列舉值欄位標 @EnumValue（或實現 IEnum），JSON 序列化標 @JsonValue；XML 自定義查詢中列舉欄位的每個位置（resultMap、條件 #{}、插入 #{}）都要宣告 typeHandler=MybatisEnumTypeHandler。 10. 高階外掛順序（多租戶/資料許可權/動態表名 → 分頁最後）：TenantLineInnerInterceptor / DataPermissionInterceptor / DynamicTableNameInnerInterceptor 必須在 PaginationInnerInterceptor 之前新增；否則 COUNT 語句不會被改寫，分頁總數不準或資料許可權漏過濾（見 references/07-plugin.md §5）。 11. 欄位引用必須用方法引用（Lambda）：構造條件/更新預設用 LambdaQueryWrapper / LambdaUpdateWrapper + 方法引用（User::getName），禁止字串欄位名（eq("name", ...)）。例外：動態列名 / 動態表名 / 方言函式等執行時才知道的列——用 QueryWrapper / UpdateWrapper 字串形式 + 註釋說明，且拼接外部輸入走 §7 {0} 佔位防注入。方法引用編譯期檢查，欄位改名編譯報錯；字串字面量無校驗，重構改名靜默產出錯誤 SQL（Unknown column）或查錯資料（見 references/05-wrapper.md §1）。

決策路由（全部本地，無線上 fetch）

組合場景閱讀順序：先讀機制類（01/02/03/04/05/06/07），再讀落地/糾偏類（08/09/10/11）。例：分頁+聯表→先 06 後 10；列舉+XML→先 03 後 10；邏輯刪除+多租戶→先 07 後 02；批次+事務→先 04 後 11；事務+多資料來源→先 11 後 02；事務回滾排查→先 11 後 08。

使用流程

1. 確認 MP 適用性：先執行「第 0 步：依賴探測與啟用分支」；依賴缺失時主動詢問是否引入 MyBatis-Plus。不適用 → 告知使用者並建議退出；部分適用 → 告知範圍並讓使用者確認；正常 → 繼續。
2. 定位 reference：查上方「決策路由」表，讀對應檔案。
3. 編碼遵循強約束：先看 11 條核心強約束，再讀 reference 給程式碼。
4. 遇異常先查排錯：references/09-troubleshoot.md + references/08-antipattern.md。
5. 輸出前自檢（9 項）：
6. [ ] starter 座標對應 SpringBoot 版本？（2.x / 3.x / 4.x）
7. [ ] 分頁場景引了 mybatis-plus-jsqlparser？
8. [ ] updateById 需置 null？→ 改用 LambdaUpdateWrapper.set()
9. [ ] XML 中列舉欄位每處 #{} 都聲明瞭 typeHandler=MybatisEnumTypeHandler？
10. [ ] Wrapper 每次 new 新例項？
11. [ ] Wrapper 條件用方法引用（User::getXxx）？字串欄位名僅限動態列名/動態表名例外
12. [ ] 視窗/聚合/GROUP BY/專有函式/計算列場景 → 改寫 XML，未用 apply/last 拼？
13. [ ] @Transactional 顯式寫了 rollbackFor = Exception.class？
14. [ ] 事務方法無自呼叫？

版本注意

• 依賴座標 com.baomidou:mybatis-plus-*，本地 references 基於 3.5.17 整理，3.5.x 全線適用。
• v3.5.9+ 外掛拆分為可選依賴（分頁需額外引 mybatis-plus-jsqlparser）。
• 若使用者環境為 3.4.x 舊版：PaginationInterceptor 在 3.4.0 起標記廢棄、3.5.x 已移除，應遷移到 MybatisPlusInterceptor（見 references/13-migration.md）；3.4.x 暫無 jsqlparser 拆分，勿按 3.5.9+ 引依賴。

  7w4.net收錄了海量優質技能外掛。

這個技能質量較好，能有效幫助開發者解決 MyBatis-Plus 使用中的各種問題。它的優點是知識覆蓋全面，包含大量實戰案例和防坑指南，強約束規則明確，決策路由表讓問題解答更精準。需要改進的是各部分內容詳略不均，有些場景指導比較詳細，有些則比較簡略，建議補充完善。總體來說，這是一個實用性強、能夠幫助開發者避免常見錯誤的開發助手。