通用 Mapper 3.x 平滑升级到 4.x+：tk.mybatis:mapper 适配模块（mapper-all）深度解析

• 后端
• ORM
• 数据库

本篇技术指南围绕 Mapper 仓库中的all适配模块展开，详细讲解 MyBatis 通用 Mapper 如何通过一个聚合工程帮助用户从 3.x 平滑过渡到 4.x 及以后版本：它提供了基于 Maven 依赖传递的dependencies子模块与基于 maven-shade-plugin 打成大 jar 包的mapper子模块两种集成方案，并保证了 Maven 坐标tk.mybatis:mapper不变、升级时只改版本号。读完本文，你将掌握这两种方案的实现原理、pom 配置细节、版本覆盖机制，以及从 3.x 升级到 4.x/6.x 时需要注意的注解与 JDK 约束。

一、为什么需要"通用 Mapper3 适配"模块

MyBatis 通用 Mapper 在 4.x 之后将原本单一大 jar 的结构拆分为mapper-core、mapper-base、mapper-extra、mapper-spring、mapper-weekend、mapper-generator等多个独立模块（见根 pom.xml 中<modules>声明）。拆分带来的直接后果是：老用户从 3.x 升级时，需要逐个引入多个新坐标、处理版本对齐问题，迁移成本明显上升。

all适配模块正是为了解决这一过渡难题而生。它在 all/README.md 中明确了两条核心承诺：

1. 提供两个子模块，分别用依赖传递和大 jar 包两种方式把拆分后的模块重新聚合，让用户只需引入一个坐标；
2. jar 的 Maven 坐标仍然保持tk.mybatis:mapper，从 3.x 升级到 4.x 时只需要修改版本号，其余代码与配置无需大动。

也就是说，all模块的本质是一个"兼容层 + 聚合层"，它不实现新的通用方法，而是把 4.x 拆分出来的能力按 3.x 时代的习惯重新打包交付。

二、适配模块的整体架构：mapper-all 聚合工程

all目录下是一个典型的 Maven 聚合工程，其聚合关系记录在 all/pom.xml：

<modules> <module>mapper</module> <module>dependencies</module> </modules>

作为聚合 POM，它还承担了另一项重要职责——通过dependencyManagement统一管理六个子模块的版本（均取${project.version}），保证mapper与dependencies两个子模块引用同一批依赖版本：

• tk.mybatis:mapper-core
• tk.mybatis:mapper-base
• tk.mybatis:mapper-extra
• tk.mybatis:mapper-spring
• tk.mybatis:mapper-weekend
• tk.mybatis:mapper-generator

两个子模块的定位与差异如下表所示：

三、方式一：基于 Maven 依赖传递的 dependencies 子模块

3.1 依赖传递的原理

all/dependencies/pom.xml 定义了坐标为tk.mybatis:mapper-all-dependencies的 jar 工程（其description为 "Mybatis 通用 Mapper Jar 集成"），内部直接声明了六个模块依赖：

<dependencies> <dependency> <groupId>tk.mybatis</groupId> <artifactId>mapper-core</artifactId> </dependency> <dependency> <groupId>tk.mybatis</groupId> <artifactId>mapper-base</artifactId> </dependency> <!-- mapper-extra / mapper-spring / mapper-weekend / mapper-generator 同理 --> </dependencies>

注意这些依赖都没有显式写<version>，版本由父级mapper-all的dependencyManagement统一注入。这正是"只引一个坐标、自动带上一整套"的原理：Maven 的依赖传递机制会把该模块的六个直接依赖递归带入使用方项目。

3.2 使用方法

根据 all/dependencies/README.md，使用方只需要添加一个依赖：

<dependency> <groupId>tk.mybatis</groupId> <artifactId>mapper-all-dependencies</artifactId> <version>版本号</version> </dependency>

引入后会自动引入 mapper-core、mapper-extra、mapper-generator、mapper-spring、mapper-weekend 等其他依赖，无需手动逐个添加。

3.3 覆盖子模块版本

该模块还提供了一套"按属性覆盖版本"的机制。默认情况下无需任何设置，但如果你出于特殊需要想单独调整某个子模块的版本（例如集成自研的分支快照），可以在使用方的 pom 中声明对应的 Maven 属性：

<properties> <mapper-core.version>4.0.0-SNAPSHOT</mapper-core.version> <mapper-extra.version>1.0.0-SNAPSHOT</mapper-extra.version> <mapper-spring.version>1.0.0-SNAPSHOT</mapper-spring.version> <mapper-weekend.version>1.1.3-SNAPSHOT</mapper-weekend.version> <mapper-generator.version>1.0.0-SNAPSHOT</mapper-generator.version> </properties>

上面具体版本号只是示例，默认不需要自己设置。可以推断，这一机制依赖于 Maven 依赖版本属性（${mapper-core.version}等）的解析规则：当某条依赖的版本来自属性时，覆盖属性即可改变最终解析到的版本。

四、方式二：基于 maven-shade-plugin 的大 jar 包 mapper 子模块

4.1 打包原理

all/mapper/pom.xml 定义的mapper模块同样坐标稳定在tk.mybatis:mapper，但聚合手段完全不同——它在package阶段通过maven-shade-plugin（版本 3.6.0）把六个子模块的 class 全部合并进一个大 jar：

<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-shade-plugin</artifactId> <version>3.6.0</version> <executions> <execution> <phase>package</phase> <goals> <goal>shade</goal> </goals> <configuration> <createDependencyReducedPom>false</createDependencyReducedPom> <createSourcesJar>true</createSourcesJar> <artifactSet> <includes> <include>tk.mybatis:mapper-core</include> <include>tk.mybatis:mapper-base</include> <include>tk.mybatis:mapper-extra</include> <include>tk.mybatis:mapper-spring</include> <include>tk.mybatis:mapper-weekend</include> <include>tk.mybatis:mapper-generator</include> </includes> </artifactSet> </configuration> </execution> </executions> </plugin> </plugins> </build>

这段配置中有几个关键点：

• artifactSet.includes精确圈定了要合并进大 jar 的六个tk.mybatis模块，避免把无关依赖（如 MyBatis、JPA API）一并打入，导致与其他 jar 冲突；
• createDependencyReducedPom=false保留完整 POM，不做依赖裁剪，保证产物坐标与依赖声明信息完整；
• createSourcesJar=true同时生成 sources jar，方便 IDE 中查看源码；
• 六个模块依赖全部声明为<optional>true</optional>，因此引入该依赖时不会引入传递依赖——class 已经被 shade 进 jar 内部了。

唯一保留的"必须依赖"是jakarta.persistence-api（JPA 注解 API），它不参与 shade 合并，仍然作为外部依赖存在，这一点可以从 all/mapper/pom.xml 中的依赖注释（"必须依赖"）得到印证。

4.2 使用方法

根据 all/mapper/README.md，使用方引入方式与 3.x 时代完全一致：

<dependency> <groupId>tk.mybatis</groupId> <artifactId>mapper</artifactId> <version>版本号</version> </dependency>

4.3 两种方式的取舍

• 选dependencies：依赖交还给 Maven 管理，各模块版本可独立覆盖，调试时能看到清晰的依赖树，适合追求可控性的项目；
• 选mapper大 jar：坐标与 3.x 完全对齐、零配置升级，适合希望"改个版本号就完事"的存量项目；代价是依赖粒度被合并，无法单独替换某个子模块版本。

五、GAV 不变：从 3.x 升级只改版本号

这是整个适配模块存在的最核心价值。all/README.md 原话强调："本项目下面的 jar 的 Maven 为tk.mybatis:mapper，也就是从 mapper 3.x 升级到 4.x 的时候可以只改版本号。"

从 all/mapper/pom.xml 可以看到，mapper模块的groupId继承自tk.mybatis、artifactId为mapper，与 3.x 时代的坐标逐字一致。这意味着存量项目升级时的迁移动作被压缩到最小：

1. 把依赖坐标tk.mybatis:mapper的<version>从3.x改为新版本号；
2. 原有业务 Mapper 接口、通用方法调用、配置项保持不变；
3. 剩余需要处理的工作主要集中在环境层面的注解与 JDK 约束（见下文第七节）。

六、适配模块背后集成的六大能力

all模块聚合的六个子模块各自承担不同职责，这些能力在仓库中均有对应的实现与文档，下面逐一列出，便于读者了解"一个坐标背后到底带回来了什么"：

需要特别指出的是，通用 Mapper 聚焦单表 CRUD，不支持通用的多表联合查询（根 README.md 明确说明"支持单表操作，不支持通用的多表联合查询"），多表场景仍需要手写 SQL 或引入其他方案。

七、升级到 4.x/6.x 的注意事项（当前仓库视角）

虽然all适配模块把"换坐标"这一步简化成了改版本号，但 4.x 之后的技术栈演进仍然带来了几处需要提前确认的约束，这些以当前仓库（master，revision=6.0.0，见根 pom.xml）的实际内容为准：

7.1 JDK 与 JPA 注解命名空间变化

• 当前仓库基于JDK 17 + Jakarta JPA 注解 + Spring Boot 4构建（根 README.md），jakarta.persistence-api版本为 3.2.0；
• 因此实体上的@javax.persistence.Id等注解需要同步替换为jakarta.persistence.Id（即 JPA 2.x 的javax命名空间 → JPA 3.x 的jakarta命名空间）；
• 从源码注释看，主键字段必须通过 JPA 的@Id注解显式声明，否则无法确认实体类哪个属性是主键（见 base/src/main/java/tk/mybatis/mapper/common/base/select/SelectByPrimaryKeyMapper.java）。

7.2 分支与版本对应关系

仓库按分支提供不同技术栈的适配（根 README.md 的版本匹配说明）：

升级前请先确认自己项目的 Spring Boot / JDK 环境，再选择对应版本线。

7.3 配置方式保持兼容

配置层面与 3.x 基本兼容。以 Spring 集成为例，仍可使用tk.mybatis.spring.mapper.MapperScannerConfigurer（注意是 tk 包名，不是官方 mybatis-spring 的org.xxx类）或@MapperScan注解；通用 Mapper 3.6.0 之后会自动注册带@RegisterMapper注解的基类接口，不再强制要求配置mappers属性，只需给基类加@RegisterMapper注解即可（见 spring/README.md 与 base/src/main/java/tk/mybatis/mapper/common/Mapper.java 中的@RegisterMapper注解）。

八、延伸阅读

如果你希望进一步了解适配模块背后的各个子模块，可以直接在仓库中按下面顺序阅读：

• all/README.md（适配模块说明，本文主体）
• all/dependencies/pom.xml 与 all/mapper/pom.xml（两种聚合方式的实现）
• base/src/main/java/tk/mybatis/mapper/common/Mapper.java 与 base/src/main/java/tk/mybatis/mapper/common/MySqlMapper.java（基础通用方法与 MySql 特有方法的组合示例，也是自定义扩展时的参考模板）
• spring/README.md（Spring 集成的完整配置示例）
• extra/README.md 与 weekend/README.md（扩展方法与 Lambda 条件构造）
• README.md（项目总览、版本匹配与快速入门指引）

• 后端
• ORM
• 数据库