后端ORM数据库【免费下载链接】MapperMybatis Common Mapper - Easy to use项目地址https://gitcode.com/gh_mirrors/ma/Mapper点击查看免费下载本篇技术指南围绕 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 中明确了两条核心承诺提供两个子模块分别用依赖传递和大 jar 包两种方式把拆分后的模块重新聚合让用户只需引入一个坐标jar 的 Maven 坐标仍然保持tk.mybatis:mapper从 3.x 升级到 4.x 时只需要修改版本号其余代码与配置无需大动。也就是说all模块的本质是一个兼容层 聚合层它不实现新的通用方法而是把 4.x 拆分出来的能力按 3.x 时代的习惯重新打包交付。二、适配模块的整体架构mapper-all 聚合工程all目录下是一个典型的 Maven 聚合工程其聚合关系记录在 all/pom.xmlmodules modulemapper/module moduledependencies/module /modules作为聚合 POM它还承担了另一项重要职责——通过dependencyManagement统一管理六个子模块的版本均取${project.version}保证mapper与dependencies两个子模块引用同一批依赖版本tk.mybatis:mapper-coretk.mybatis:mapper-basetk.mybatis:mapper-extratk.mybatis:mapper-springtk.mybatis:mapper-weekendtk.mybatis:mapper-generator两个子模块的定位与差异如下表所示维度dependencies 子模块mapper-all-dependenciesmapper 子模块mapper聚合方式声明直接依赖借助 Maven 依赖传递机制maven-shade-plugin 将各模块 class 打入同一个 jarMaven 坐标tk.mybatis:mapper-all-dependenciestk.mybatis:mapper与 3.x 保持一致传递依赖引入后自动传递全部六个模块依赖不会引入传递依赖optionaltrue/optional典型使用场景希望依赖由 Maven 管理、可单独覆盖版本希望一个 jar 走天下、坐标与 3.x 完全一致打包产物常规 jar依赖仍在外部大 jar依赖 class 已合并进包内三、方式一基于 Maven 依赖传递的 dependencies 子模块3.1 依赖传递的原理all/dependencies/pom.xml 定义了坐标为tk.mybatis:mapper-all-dependencies的 jar 工程其description为 Mybatis 通用 Mapper Jar 集成内部直接声明了六个模块依赖dependencies dependency groupIdtk.mybatis/groupId artifactIdmapper-core/artifactId /dependency dependency groupIdtk.mybatis/groupId artifactIdmapper-base/artifactId /dependency !-- mapper-extra / mapper-spring / mapper-weekend / mapper-generator 同理 -- /dependencies注意这些依赖都没有显式写version版本由父级mapper-all的dependencyManagement统一注入。这正是只引一个坐标、自动带上一整套的原理Maven 的依赖传递机制会把该模块的六个直接依赖递归带入使用方项目。3.2 使用方法根据 all/dependencies/README.md使用方只需要添加一个依赖dependency groupIdtk.mybatis/groupId artifactIdmapper-all-dependencies/artifactId version版本号/version /dependency引入后会自动引入 mapper-core、mapper-extra、mapper-generator、mapper-spring、mapper-weekend 等其他依赖无需手动逐个添加。3.3 覆盖子模块版本该模块还提供了一套按属性覆盖版本的机制。默认情况下无需任何设置但如果你出于特殊需要想单独调整某个子模块的版本例如集成自研的分支快照可以在使用方的 pom 中声明对应的 Maven 属性properties mapper-core.version4.0.0-SNAPSHOT/mapper-core.version mapper-extra.version1.0.0-SNAPSHOT/mapper-extra.version mapper-spring.version1.0.0-SNAPSHOT/mapper-spring.version mapper-weekend.version1.1.3-SNAPSHOT/mapper-weekend.version mapper-generator.version1.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 全部合并进一个大 jarbuild plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-shade-plugin/artifactId version3.6.0/version executions execution phasepackage/phase goals goalshade/goal /goals configuration createDependencyReducedPomfalse/createDependencyReducedPom createSourcesJartrue/createSourcesJar artifactSet includes includetk.mybatis:mapper-core/include includetk.mybatis:mapper-base/include includetk.mybatis:mapper-extra/include includetk.mybatis:mapper-spring/include includetk.mybatis:mapper-weekend/include includetk.mybatis:mapper-generator/include /includes /artifactSet /configuration /execution /executions /plugin /plugins /build这段配置中有几个关键点artifactSet.includes精确圈定了要合并进大 jar 的六个tk.mybatis模块避免把无关依赖如 MyBatis、JPA API一并打入导致与其他 jar 冲突createDependencyReducedPomfalse保留完整 POM不做依赖裁剪保证产物坐标与依赖声明信息完整createSourcesJartrue同时生成 sources jar方便 IDE 中查看源码六个模块依赖全部声明为optionaltrue/optional因此引入该依赖时不会引入传递依赖——class 已经被 shade 进 jar 内部了。唯一保留的必须依赖是jakarta.persistence-apiJPA 注解 API它不参与 shade 合并仍然作为外部依赖存在这一点可以从 all/mapper/pom.xml 中的依赖注释必须依赖得到印证。4.2 使用方法根据 all/mapper/README.md使用方引入方式与 3.x 时代完全一致dependency groupIdtk.mybatis/groupId artifactIdmapper/artifactId version版本号/version /dependency4.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 时代的坐标逐字一致。这意味着存量项目升级时的迁移动作被压缩到最小把依赖坐标tk.mybatis:mapper的version从3.x改为新版本号原有业务 Mapper 接口、通用方法调用、配置项保持不变剩余需要处理的工作主要集中在环境层面的注解与 JDK 约束见下文第七节。六、适配模块背后集成的六大能力all模块聚合的六个子模块各自承担不同职责这些能力在仓库中均有对应的实现与文档下面逐一列出便于读者了解一个坐标背后到底带回来了什么子模块职责仓库证据mapper-core核心注解KeySql、LogicDelete、NameStyle、Version、RegisterMapper等、实体解析与通用 SQL 生成引擎core/src/main/java/tk/mybatis/mapper/annotation、core/src/main/java/tk/mybatis/mapper/gensql/GenSql.javamapper-base基础通用方法selectByPrimaryKey、selectOne、select、selectAll、selectCount、existsWithPrimaryKey、insert、insertSelective、updateByPrimaryKey、updateByPrimaryKeySelective、delete、deleteByPrimaryKey等base/src/main/java/tk/mybatis/mapper/common/base/BaseMapper.java、base/src/main/java/tk/mybatis/mapper/common/Mapper.javamapper-extra扩展方法InsertListMapper批量插入、UpdateByPrimaryKeySelectiveForceMapper空字段强制更新、聚合查询、按属性查询/删除、id 列表操作等extra/README.md、extra/src/main/java/tk/mybatis/mapper/additionalmapper-spring与 Spring/Spring Boot 集成MapperScannerConfigurer、MapperScanmapperHelperRef/properties两种注解配置、tk.mybatis.mapper.session.Configurationspring/README.md、spring/src/main/java/tk/mybatis/springmapper-weekend基于 Lambda 的类型安全条件构造器Weekend可在Example.Criteria中直接传方法引用如andIsNull(User::getId)weekend/README.md、weekend/src/main/java/tk/mybatis/mapper/weekend/Weekend.javamapper-generatorMyBatis Generator 扩展MapperPlugin、TemplateFilePlugin、代码模板格式化等generator/src/main/java/tk/mybatis/mapper/generator需要特别指出的是通用 Mapper 聚焦单表 CRUD不支持通用的多表联合查询根 README.md 明确说明支持单表操作不支持通用的多表联合查询多表场景仍需要手写 SQL 或引入其他方案。七、升级到 4.x/6.x 的注意事项当前仓库视角虽然all适配模块把换坐标这一步简化成了改版本号但 4.x 之后的技术栈演进仍然带来了几处需要提前确认的约束这些以当前仓库masterrevision6.0.0见根 pom.xml的实际内容为准7.1 JDK 与 JPA 注解命名空间变化当前仓库基于JDK 17 Jakarta JPA 注解 Spring Boot 4构建根 README.mdjakarta.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 版本Mapper 版本masterSpring Boot 4.xJDK 176.0.05.xSpring Boot 3.xJDK 175.0.04.3.xSpring Boot 2.xJDK 84.3.x升级前请先确认自己项目的 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.mdSpring 集成的完整配置示例extra/README.md 与 weekend/README.md扩展方法与 Lambda 条件构造README.md项目总览、版本匹配与快速入门指引赞分享后端ORM数据库【免费下载链接】MapperMybatis Common Mapper - Easy to use项目地址https://gitcode.com/gh_mirrors/ma/Mapper点击查看免费下载相关推荐终极指南如何从 Fast-Check 3.x 平滑升级到 4.x终极指南如何从 Fast Check 3.x 平滑升级到 4.x Fast Check 是 JavaScript 生态中功能强大的基于属性的测试框架随着版本开发工具测试Django Channels版本升级指南从3.x到4.x的平滑迁移Django Channels版本升级指南从3.x到4.x的平滑迁移 Django Channels是Django官方推荐的异步Web框架它为Django带后端WebSocket异步编程CouchDB 升级实战指南从 1.x / 2.x 平滑升级到 3.xCouchDB 升级实战指南从 1.x / 2.x 平滑升级到 3.x 本篇技术指南以 CouchDB 官方升级文档 upgrading.rst https:数据库文档数据库后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
