企业官网建设流程全解析

Gradle与MyBatis集成这件事，看起来简单，实际一上手就会碰到一堆坑。依赖版本冲突、代码生成器配置繁琐、构建速度慢、Java版本与Gradle版本不匹配，这些问题我基本都踩过一遍。这篇内容不打算讲什么高深理论，就是把我在实际项目里验证过的一套配置方案、代码生成落地方式、以及排查问题的思路完整梳理出来，给正在折腾这件事的朋友一份可以直接参考的实践记录。

1. 整体设计思路：为什么这么配

1.1 先从构建工具说起

Gradle在Java后端项目里已经是很主流的选择了，尤其在Spring Boot生态里，用Gradle管理依赖、处理多模块构建、跑代码生成任务，都比Maven要灵活不少。但灵活的另一面是配置项多，稍不注意就容易出问题。我见过太多项目卡在Gradle版本和项目需求对不上，或者依赖解析慢到让人怀疑人生。

拿我手头这个项目举例，技术栈是Spring Boot 2.7 + MyBatis + MySQL，构建工具选了Gradle 7.6。为什么要选这个组合？Spring Boot 2.7对应Gradle 7.x比较稳妥，Gradle 8.x虽然也能用，但有些老插件不一定兼容，尤其是MyBatis Generator这类不怎么频繁更新的插件。版本不是越新越好，稳定才是第一位的。

1.2 核心需求拆解

这篇文章要解决的实质问题有三个：

• 第一，Gradle依赖怎么配，MyBatis相关组件之间不打架。
• 第二，MyBatis Generator代码生成怎么跑通，不依赖IDE插件，直接在命令行或构建过程中完成。
• 第三，集成过程中常见的问题有哪些，怎么快速定位和解决。

这三个问题分别对应依赖管理、代码生成、问题排查三条线，也是很多人在项目初期耗费大量时间的痛点。

2. 依赖配置的核心要点

2.1 最小依赖集合

MyBatis在Spring Boot项目里，最基础的依赖其实就两个组合。mybatis-spring-boot-starter是首选，它把MyBatis的核心库、Spring集成、自动配置都打包好了，不需要自己去拼装mybatis和mybatis-spring。数据库驱动根据实际使用的数据库选，MySQL就是com.mysql:mysql-connector-j。

我这里用的是Groovy DSL的Gradle配置，build.gradle关键部分如下：

dependencies { implementation 'org.mybatis.spring.boot:mybatis-spring-boot-starter:2.3.1' runtimeOnly 'com.mysql:mysql-connector-j:8.0.33' }

注意到几个细节：数据库驱动用runtimeOnly就够了，因为编译期不需要直接引用驱动类；MySQL 8以上版本的驱动坐标已经从mysql-connector-java改成了mysql-connector-j，这个细节容易踩坑，尤其在看老教程的时候。

2.2 分页插件和通用Mapper的取舍

很多人会把PageHelper和tk.mybatis的通用Mapper一起加上，我个人的建议是能少加就少加。PageHelper用起来方便，但它会拦截所有查询，偶尔会出现分页参数串了的情况。通用Mapper更不用说了，理念很好，但国内版本更新偏慢，和Spring Boot 2.7以上版本配合时偶尔会有兼容问题。

如果项目对分页和CRUD的简化确实有需求，优先考虑MyBatis-Plus，它的分页插件和条件构造器设计更贴近现代开发习惯。但这个要看团队的整体技术选型，如果项目就是纯MyBatis路线，只加一个starter就够了，其他都是加分项，不是必需品。

2.3 排除冲突依赖的姿势

实战中最常见的问题是javax和jakarta命名空间冲突，尤其在Spring Boot 2.x和3.x混用的团队里。假如你引入了一个第三方库，它内部传递依赖了Spring Boot 3的组件，项目就会炸。

这时候可以在Gradle里用全局排除策略：

configurations.all { exclude group: 'org.springframework.boot', module: 'spring-boot-starter-logging' }

但我提醒一下，排除依赖是双刃剑。能精准定位再排除，别一把梭。我见过有人为了修一个警告信息，把日志依赖全排了，结果项目启动后没有任何日志输出，排查问题全靠猜。

3. 代码生成器：MyBatis Generator的落地

3.1 为什么用XML配置

MyBatis Generator（MBG）从1.4.0开始支持纯Java代码配置，但实际项目里XML配置的使用量还是很大。原因很简单：XML配置里可以直接看到数据库连接、表名、生成策略这些核心信息，团队协作时容易过审，也方便临时改参数。Java配置虽然类型安全，但复杂参数的可读性并不好。

MBG的版本也有讲究。老项目的1.3.x系列用org.mybatis.generator这个groupId下的mybatis-generator-core，新项目直接用1.4.x。1.4.x在反注释、批量语句生成、Java8时间类型支持上都做了不少优化，体验比1.3.x好很多。

3.2 generatorConfig.xml配置详解

我项目里的配置文件是这样的：

<!DOCTYPE generatorConfiguration PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN" "http://mybatis.org/dtd/mybatis-generator-config_1_0.dtd"> <generatorConfiguration> <properties resource="generator.properties"/> <context id="mysqlContext" targetRuntime="MyBatis3Simple" defaultModelType="flat"> <property name="javaFileEncoding" value="UTF-8"/> <property name="useMapperCommentGenerator" value="true"/> <jdbcConnection driverClass="${jdbc.driver}" connectionURL="${jdbc.url}" userId="${jdbc.username}" password="${jdbc.password}"/> <javaModelGenerator targetPackage="com.example.model" targetProject="src/main/java"/> <sqlMapGenerator targetPackage="mapper" targetProject="src/main/resources"/> <javaClientGenerator targetPackage="com.example.mapper" targetProject="src/main/java" type="XMLMAPPER"/> <table tableName="user" domainObjectName="User"> <property name="useActualColumnNames" value="false"/> <generatedKey column="id" sqlStatement="JDBC"/> </table> </context> </generatorConfiguration>

几个配置点我展开说一下。

targetRuntime="MyBatis3Simple"这是我最常用的设置。它生成的Mapper极其精简，基础的单表CRUD都有，但不会生成一大堆用不上的ByExample方法。如果你真的需要动态查询，再改成MyBatis3，否则Simple足够用了。

defaultModelType="flat"意思是每个表只生成一个实体类，不做主键类和BLOB类拆分。现在基本没人会去拆分这些了，纯属增加管理成本。

generatedKey加上之后，生成器会在insert语句里自动添加useGeneratedKeys="true"，插入数据后实体的主键会回填，这个对后续业务处理很重要。

3.3 通过Gradle Task跑代码生成

不依赖IDE插件的话，最优雅的方式是写一个Gradle Task来触发MBG。这里我踩过一个坑：MBG的运行时依赖要单独加在buildscript或者其他自定义配置里，不能直接加到主dependencies块，否则会把生成器代码打进业务包里。

我推荐的方式是单独声明一个自定义配置：

configurations { mybatisGenerator } dependencies { mybatisGenerator 'org.mybatis.generator:mybatis-generator-core:1.4.2' mybatisGenerator 'com.mysql:mysql-connector-j:8.0.33' } task mbgGenerate { doLast { def configFile = file('src/main/resources/generatorConfig.xml') def ant = antBuilder() ant.taskdef( name: 'mbg', classname: 'org.mybatis.generator.ant.GeneratorAntTask', classpath: configurations.mybatisGenerator.asPath ) ant.mbg(configfile: configFile.path, overwrite: true) } }

然后在命令行执行：

gradle mbgGenerate

整个过程就通了。overwrite=true这个参数要注意，生成器会直接覆盖已有的同名文件。如果团队里有人在实体类上手动加了字段，跑一次生成就全没了。我在项目里的做法是overwrite=false，生成失败的再人工确认，安全第一。

3.4 代码生成后的手动调整清单

生成完之后，我建议按这个顺序检查：

• 实体类是否有@TableName注解（如果用MyBatis-Plus的话）
• Mapper接口是否加了@Mapper注解或者在启动类上加了@MapperScan
• XML文件里的resultMap是否符合实际字段映射
• 主键回填有没有生效

尤其是@MapperScan，很多项目跑起来提示Invalid bound statement (not found)，一查就是Mapper接口没被Spring扫描到。这和MBG无关，但和整个集成链路密切相关。

4. 实际集成中的关键环节

4.1 配置文件里的必备项

代码生成完，要确保application.yml里MyBatis的配置正确。我通常这样配：

mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.model configuration: map-underscore-to-camel-case: true

mapper-locations指定XML映射文件的位置，type-aliases-package让实体类可以用简单名字代替全限定名，map-underscore-to-camel-case更是必备，数据库的user_name字段就能自动映射到Java的userName属性，不用手动写一大堆resultMap了。

4.2 日志打印：排查SQL的唯一手段

MyBatis开发过程中SQL日志的打印极其重要。在application.yml里加上：

logging: level: com.example.mapper: debug

注意这里的com.example.mapper要改成你Mapper接口所在的包路径。配置成debug级别后，MyBatis会把执行的SQL、参数值、返回行数都打印出来，配合mybatis-log-plugin之类的IDEA插件看动态SQL很方便。

有些项目图省事，直接把root日志级别调成debug，结果日志量大到IDEA控制台直接卡死，这个真不推荐。

4.3 缓存机制：先用好再说

MyBatis有一级缓存和二级缓存，这个话题面试被问烂了，但实际项目里很多人根本不关心，默认配置直接用。一级缓存是SqlSession级别的，默认开启，在同一个SqlSession里重复查询同一条数据，会直接命中缓存。

二级缓存是Mapper级别的，默认关闭。我在项目中一般不开二级缓存，原因很简单：多表关联查询的缓存失效不好控制，一旦脏数据被缓存了，排查起来特别痛苦。如果某个查询真是热点，我会用Redis做业务级缓存，可控性更强。

<!-- 不推荐默认开启 --> <cache eviction="LRU" flushInterval="60000" size="512" readOnly="true"/>

这段配置我见过很多项目都在用，但说实话，单机环境下开了二级缓存效果不大，分布式环境下缓存一致性问题更突出。建议项目初期不开，等真的遇到性能瓶颈再考虑。

5. 常见问题与排查技巧实录

5.1 Gradle下载依赖慢，构建卡死

这是Gradle使用中反馈最多的问题。中央仓库在海外，依赖解析慢甚至超时。标准解法是换国内镜像源。GitHub上有不少Gradle镜像仓库的地址，配置在repositories块里即可。

repositories { maven { url 'https://maven.aliyun.com/repository/central' } maven { url 'https://maven.aliyun.com/repository/public' } maven { url 'https://mirrors.tencent.com/nexus/repository/maven-public/' } mavenCentral() }

阿里云和腾讯云的Maven镜像都有比较高的可用性，我实测下来阿里云的速度最快。注意要放在mavenCentral()前面，这样Gradle会优先匹配镜像仓库。

5.2 Java版本与Gradle版本不匹配

Gradle对Java版本是有要求的。比如Gradle 7.6最高支持Java 19，Gradle 8.8开始支持Java 21。如果本机是Java 21，但项目用的Gradle版本是7.x，构建时会直接提示：

Unsupported Java version 21.0.4

这种问题的核心是统一版本管理。项目里加上.sdkmanrc或者.java-version文件，把Java版本和Gradle版本都固定下来，团队协作就不会因为各人本地环境不同而出现奇奇怪怪的问题。

5.3 提示找不到Statement

这个报错信息一般是Invalid bound statement (not added to mapper registry)。排查顺序如下：

• Mapper接口是否存在且被Spring扫描到
• XML文件路径和mapper-locations是否匹配
• XML文件里的namespace是否和Mapper接口全限定名一致
• 方法ID和Mapper接口方法名是否一致

90%的情况都出在这四点上，尤其是XML文件在src/main/java目录下但没有配置build.gradle里的resources识别，Gradle默认不会把src/main/java下的XML打包到classpath里。

5.4 MyBatis批量操作报错

批量插入时，很多人会在URL上配置allowMultiQueries=true，然后拼多条insert语句。这个方案有SQL注入风险，也不利于SQL执行计划复用。更规范的做法是：

SqlSession sqlSession = sqlSessionFactory.openSession(ExecutorType.BATCH); try { UserMapper mapper = sqlSession.getMapper(UserMapper.class); for (User user : userList) { mapper.insert(user); } sqlSession.commit(); } finally { sqlSession.close(); }

或者直接用MyBatis-Plus的saveBatch方法。批处理模式下，MyBatis会复用PreparedStatement，性能提升很可观。

5.5 项目写好了第一次用Gradle构建却一直卡在下载

这一条单独拿出来说，因为真的太常见了。新项目或者重装系统的电脑上，第一次gradle build时，Gradle会先下载Gradle发行版本身，然后又下载一堆依赖。如果发行版下载速度不行，构建进度条就可能一直停留在下载状态。

解决办法两个方向。一个是用Gradle Wrapper并修改gradle-wrapper.properties里的distributionUrl为国内镜像地址；另一个是直接手动下载好离线包，放到对应目录。都有不少博主分享过操作步骤，核心就是别让发行版也走官方渠道，速度差异不是一点半点。

6. 实操心得与避坑经验

这套方案我在多个Spring Boot项目中验证过，稳定性和可维护性都过关。最后分享几点实在的体会：

依赖版本尽量统一管理。Spring Boot的BOM机制能帮我们锁定大部分依赖版本，但MyBatis Generator这类独立工具不在BOM管理范围内，要么单独建gradle.properties维护版本号，要么用Gradle的Version Catalog把依赖和版本集中起来管理。项目一多，集中管理的优势会非常明显。

生成代码只当脚手架。MyBatis Generator生成的实体类和Mapper只是基础，业务上复杂查询还是要手写XML或通过注解自定义SQL。不要迷信“一键生成全部搞定”，生成完之后根据业务场景改造是常态。

构建脚本一定要写注释。这种没什么技术含量但很重要。Gradle的Groovy DSL写起来简洁，但项目交接到下一任手里时，没有注释的build.gradle真的是灾难现场。特别是那些藏着特定版本锁定、排除项、自定义Task的配置，没注释就等于没有维护性。

每次跑完代码生成后立刻编译。这是我在一个项目后养成的习惯。生成器跑完，先执行gradle compileJava验证代码能过编译，再往下开发。如果等到写了很多业务代码才编译，一旦发现生成结果有问题，改起来就麻烦多了。

实际开发中，我推荐这套组合的最终形态是：Gradle统一管理依赖和构建任务，MyBatis Generator只负责生成基础CRUD代码，XML文件放在resources目录下规范管理，关键配置全部外显在配置文件中。这样既保留Gradle构建的灵活性，又不会因为MyBatis配得不够精细而在运行期踩坑。