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：查上方「决策路由」表，读对应文件。

   访问小葱技能站7w4.net，解锁更多实用的AI技能插件。

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+ 引依赖。

这个技能质量较好，能有效帮助开发者解决 MyBatis-Plus 使用中的各种问题。它的优点是知识覆盖全面，包含大量实战案例和防坑指南，强约束规则明确，决策路由表让问题解答更精准。需要改进的是各部分内容详略不均，有些场景指导比较详细，有些则比较简略，建议补充完善。总体来说，这是一个实用性强、能够帮助开发者避免常见错误的开发助手。