做Java后端开发的朋友应该都对实体类、Mapper接口、XML映射文件这三件套不陌生。数据库表一多最磨人的往往不是业务逻辑本身而是照着表结构写各种getter/setter、拼CRUD语句、维护Example查询条件这类重复劳动。第一次写能忍第十次再写真的就是拿手指头敲给自己找罪受。MyBatis Generator下文统一叫MBG就是专门解决这个问题的连上数据库、读一遍表结构就能把单表的基础CRUD代码按配置批量生成出来。这篇文章不打算重复官方文档重点聊我实际项目里的用法、配置文件抠出来的细节、怎么接自定义注释和Lombok以及几个会让你当场想摔键盘的坑。1. 项目概述与核心痛点解析1.1 MyBatis Generator到底帮你省了什么MBG最开始是iBatis时代Abator生成器进化过来的在MyBatis社区里一直属于“官网低调但用的人很多”的工具。它的核心能力很简单读取数据库表结构然后按模板生成三类东西分别是Java实体类Model、操作数据库的Mapper接口、以及Mapper对应的XML映射文件。如果你打开example开关它还会生成一套Example查询条件类可以让你不写SQL就拼出带各种and、or、like、between的动态查询条件。我自己的第一个直观感受是它不是在帮你“少写代码”而是在帮你“消灭代码错误”。手写实体类时漏一个字段、类型写错一个地方编译期通常不报错跑到测试阶段才炸出来。而MBG拿着数据库真实元数据生成字段名、类型、注释都是从库里直接读出来的天然就和表结构对得上。再加上它的XML合并机制二次生成时只会追加新内容不会动你手工加进去的自定义SQL这就很舒服了。自动生成的代码结构大概是这样的实体类每个字段一个属性带getter/setter字段注释会原样带进来。Mapper接口单表的基础insert、update、delete、select方法以及配合Example用的动态查询方法。XML映射对应Mapper接口里每个方法的SQL包含ResultMap、动态where条件、批量操作的foreach片段。所以说只要你的项目是标准MyBatis或Spring Boot集成MyBatisMBG就能直接替换掉建表后最无聊的那段开发流程让你把时间花在真正需要思考的业务逻辑上。1.2 什么场景该用、什么场景不该用MBG虽然好用但也不是什么项目都适合无脑套。我个人的判断标准是只要你的数据库表是稳定结构、且需要大量单表CRUD用MBG就非常划算。比如后台管理系统、订单系统、CMS之类天天跟几十张业务表打交道每张表都要增删改查先生成一套基础代码再往里加业务方法流程跑得飞快。反过来如果你的项目是领域驱动设计驱动、对持久层代码有很强的定制需求或者你更愿意把SQL全收在手写XML里而不是依赖生成的动态SQL那MBG的用处就有限了。生成出来的Example类通常比较大有些人会觉得“不如直接写个自定义方法干净”。这种情况我建议别硬上工具是服务人的没必要为了用而用。另外大家常拿它和MyBatis-Plus自带的代码生成器对比。MyBatis-Plus的生成器也蛮好用生成完之后直接配套BaseMapper的通用CRUD方法生成体验更“现代”。但如果你项目里不想引MyBatis-Plus那套东西或者公司规范指定用原生MyBatisMBG依然是稳妥选择。它的优势在于稳、成熟、可定制性强无论换到哪个项目配置逻辑都是那几套不容易踩出花来。2. 环境准备与运行方式选型2.1 版本与依赖的坑点MBG的官方Maven坐标是org.mybatis.generator:mybatis-generator-core配套的Maven插件是mybatis-generator-maven-plugin。目前用的比较多的版本在1.3.x到1.4.x之间1.4.x对JDK 8和JDK 11的兼容性很好新项目建议直接用1.4.2或更新的稳定版老项目如果原本是1.3.7也不用急着升配置文件的写法基本兼容。这块有一个很多人容易忽略的坑MBG插件本身不依赖数据库驱动它需要你额外在插件里配置驱动依赖。比如连MySQL就要在Maven插件内部声明mysql-connector-java。如果你用的是MySQL 8及以上驱动类名必须从com.mysql.jdbc.Driver换成com.mysql.cj.jdbc.Driver不换的话连接串直接报ClassNotFoundException。我一般建议在插件配置里显式带上依赖而不是依赖项目的全局依赖传递这样生成环境和运行环境是隔离的也省得项目里升级驱动版本时把生成脚本带崩了。我常用的插件配置是这样的plugin groupIdorg.mybatis.generator/groupId artifactIdmybatis-generator-maven-plugin/artifactId version1.4.2/version configuration configurationFile${project.basedir}/src/main/resources/generatorConfig.xml/configurationFile overwritetrue/overwrite verbosetrue/verbose /configuration dependencies dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version /dependency /dependencies /pluginoverwrite这个参数值是true的话每次重新生成时Java文件整体覆盖如果设成falseMBG可能会按自己的合并策略处理已有文件实际用下来我基本都是overwritetrue。因为XML文件有专门的合并逻辑Java文件覆盖掉重来反而更可控前提是你的实体类里没有手工加过业务方法。2.2 三种运行方式实测对比MBG常见的有三种运行方式Maven插件方式、Java编程式调用、命令行方式。我大部分时候用的都是Maven插件方式最省事一条命令跑完。Java编程式适合把生成动作集成到自动化构建或者自研脚手架平台里命令行则适合在一些临时环境里快速生成不过还得手工准备classpath稍微繁琐一些。运行方式优点缺点适合场景Maven插件配置清晰、依赖隔离、一键执行需要项目里有Maven环境日常开发90%的场景够用Java编程式调用可以在代码里动态控制配置做二次封装需要自己写启动类和参数传递逻辑自研生成平台、自动化CI流程命令行轻量、不用写Java代码classpath和驱动依赖要自己管理临时或多环境手工生成命令行跑的时候需要拿到JDBC驱动和MBG核心jar包然后把-configfile指向配置文件例如java -jar mybatis-generator-core-1.4.2.jar -configfile ./generatorConfig.xml。但你要保证这个classpath里有MySQL驱动不然第一步连接数据库就挂了。Maven插件靠dependencies把驱动带进去这块体验确实最好。如果不是搞特殊自动化需求老老实实Maven插件就够了。想封装成公司内部脚手架的话再考虑Java编程式。3. 配置文件全拆解与生成实操3.1 generatorConfig.xml核心标签逐项拆解MBG的核心配置都放在一个generatorConfig.xml里文件结构不复杂但每个标签的作用要搞清楚不然照抄网上配置容易踩坑。整套文件最外层是generatorConfiguration内部主要分几块properties加载外置属性文件、context定义一组生成上下文、jdbcConnection连数据库、javaTypeResolver做JDBC类型到Java类型的映射然后是三个生成器分别控制实体类、XML、Mapper接口的输出位置。properties标签很实用可以把数据库地址、账号密码单独抽到generator.properties里生成脚本入库。我习惯把连接串和密码放外面generatorConfig.xml里用${jdbc.url}这种占位符引用这样换环境或者交给别人执行时不用翻配置文件找密码。context是整个生成任务的根。它有id、targetRuntime、defaultModelType这些属性。targetRuntime建议用MyBatis3它可以决定生成出来的Mapper风格是原生MyBatis3还是带Example的MyBatis3Simple。如果不想生成那一大堆Example类用MyBatis3Simple会更清爽只有最基础的CRUD。defaultModelType我推荐flat这样每张表只生成一个实体类不会有主键类和BLOB类拆出来的情况。如果你用默认的conditional遇到BLOB字段时可能会多拆出WithBLOBs子类类层次一下子就变复杂了。业务系统里这种拆分类特别烦人平铺反而是最直观的。javaTypeResolver用来自定义类型转换最常用的一个属性是forceBigDecimals。如果数据库里有DECIMAL类型的金额字段默认情况下JDBC映射可能会转成Double或Float这不适合金额计算设成true之后DECIMAL统一映射成BigDecimal精度就稳了。我之前踩过坑没设这个属性金额字段后面计算时出现了小数精度问题查了半天发现生成出来是Double简直想拍桌子。3.2 5分钟生成一张表的完整配置与执行过程下面给一份我实际项目里跑过的精简配置数据库是MySQL 8生成的是一张用户表。直接复制到项目对应位置改一下连接信息就能用。?xml version1.0 encodingUTF-8? !DOCTYPE generatorConfiguration PUBLIC -//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN http://mybatis.org/dtd/mybatis-generator-config_1_0.dtd generatorConfiguration properties resourcegenerator.properties/ context idmysqlContext targetRuntimeMyBatis3 defaultModelTypeflat jdbcConnection driverClasscom.mysql.cj.jdbc.Driver connectionURL${jdbc.url} userId${jdbc.username} password${jdbc.password} property namenullCatalogMeansCurrent valuetrue/ /jdbcConnection javaTypeResolver property nameforceBigDecimals valuetrue/ /javaTypeResolver javaModelGenerator targetPackagecom.example.demo.entity targetProjectsrc/main/java property nametrimStrings valuetrue/ /javaModelGenerator sqlMapGenerator targetPackagemapper targetProjectsrc/main/resources/ javaClientGenerator typeXMLMAPPER targetPackagecom.example.demo.mapper targetProjectsrc/main/java/ table tableNameuser domainObjectNameUser enableCountByExamplefalse enableUpdateByExamplefalse enableDeleteByExamplefalse enableSelectByExamplefalse selectByExampleQueryIdfalse/ /context /generatorConfiguration连接串里如果带了参数注意XML里要转义必须写成amp;比如jdbc:mysql://localhost:3306/demo?useSSLfalseamp;serverTimezoneAsia/Shanghai。不转义的话直接就是XML解析报错白折腾一趟。跑之前先确认generator.properties里有这仨配置jdbc.urljdbc:mysql://localhost:3306/demo_db?useSSLfalseserverTimezoneAsia/Shanghai jdbc.usernameroot jdbc.password123456然后在项目根目录执行mvn mybatis-generator:generate看到BUILD SUCCESS之后去src/main/java和src/main/resources各目录下面看一眼就会发现实体、Mapper接口和XML文件都已经生成好了。整个过程从改配置到执行熟练之后确实不到5分钟。3.3 生成结果怎么看目录、代码与增量机制生成完的代码目录通常会这样分布com.example.demo.entity.User字段、getter/setter注释直接搬表注释。com.example.demo.mapper.UserMapper接口方法声明。resources/mapper/UserMapper.xmlSQL实现和ResultMap。如果你是第一次跑直接把XML文件塞进MyBatis的Mapper扫描路径就行。我习惯在Spring Boot配置里指一下mapper-locationsmybatis: mapper-locations: classpath:mapper/*.xml然后启动项目做个单元测试或者写个接口确认基础CRUD没问题就说明流程通了。这里要讲清楚一个很多人误会的点MBG在二次生成时Java文件会被覆盖但XML文件不会全量覆盖它只会把缺失的节点追加进去。所以你手工改过XML里的SQL片段比如加了一段自定义select重新生成后这段内容依然保留。这是MBG最贴心的机制之一也是它能在一个项目里长期反复用的底气。当然前提是别去手工改XML里由MBG管理的那段ResultMap和基础SQL改了也会被它纠正回来。4. 进阶定制注释、Lombok与插件机制4.1 自定义注释生成器把默认注释换成自己的风格默认生成的Java文件注释会带一段“This class was generated by MyBatis Generator”英文注释以及每个字段继承表注释后的描述。说实话这个注释在代码规约比较严格的公司里可能会被要求改掉。没问题MBG留了口子自己写个类继承DefaultCommentGenerator覆盖对应方法就行。我写过的一个简易自定义注释生成器大致长这样package com.example.generator; import org.mybatis.generator.api.IntrospectedTable; import org.mybatis.generator.api.dom.java.*; import org.mybatis.generator.internal.DefaultCommentGenerator; public class MyCommentGenerator extends DefaultCommentGenerator { Override public void addModelClassComment(TopLevelClass topLevelClass, IntrospectedTable introspectedTable) { String tableName introspectedTable.getFullyQualifiedTable().getIntrospectedTableName(); topLevelClass.addJavaDocLine(/**); topLevelClass.addJavaDocLine( * 数据表对应的实体类 tableName); topLevelClass.addJavaDocLine( * 由MyBatis Generator生成禁止手工修改。); topLevelClass.addJavaDocLine( */); } Override public void addGeneralMethodComment(Method method, IntrospectedTable introspectedTable) { // 不生成方法级别注释保持代码清爽 } }然后在generatorConfig.xml里指定到它不要忘了把这个类的编译产物加到Maven插件依赖里否则会报找不到类commentGenerator typecom.example.generator.MyCommentGenerator/如果项目是多模块建议把这个自定义类放在一个独立的公共模块里并在插件依赖中引用对应模块。一般我会把这种生成期辅助类放到generator-tools模块和数据源驱动一起作为插件依赖避免和业务代码耦合。4.2 让生成的实体直接带上Lombok注解不少项目现在都全面使用Lombok实体类不再写一堆getter/setter。MBG默认是不生成Lombok注解的你要么手动在每个实体上补要么用插件机制在生成的类上自动加。后者是正路一次配置以后所有表生成都自动带注解。写插件也不复杂核心就是继承PluginAdapter在modelBaseRecordClassGenerated里给生成的类加上Data和Builder注解。我常用的示例代码如下package com.example.generator; import org.mybatis.generator.api.PluginAdapter; import org.mybatis.generator.api.IntrospectedTable; import org.mybatis.generator.api.dom.java.TopLevelClass; public class LombokPlugin extends PluginAdapter { Override public boolean modelBaseRecordClassGenerated(TopLevelClass topLevelClass, IntrospectedTable introspectedTable) { topLevelClass.addImportedType(lombok.Data); topLevelClass.addImportedType(lombok.Builder); topLevelClass.addAnnotation(Data); topLevelClass.addAnnotation(Builder); return true; } Override public boolean modelExampleClassGenerated(TopLevelClass topLevelClass, IntrospectedTable introspectedTable) { topLevelClass.addImportedType(lombok.Data); topLevelClass.addAnnotation(Data); return true; } }配置里这样挂载plugin typecom.example.generator.LombokPlugin/加了之后实体类就清爽很多字段也直接从表结构带过来了。不过有一点得注意如果同时生成Example类也要给Example类加上合适的Lombok注解不然它生成出来还是四处都是getter和setter整体风格就不统一了。4.3 插件机制还有什么常见玩法插件机制是MBG里最值得投入精力研究的部分。除了加注解你还可以用它做很多结构性的调整。比较常见的是让实体类自动实现Serializable、给Mapper接口方法加统一注释、调整Mapper接口的命名规则甚至可以在生成完成后做一遍代码规范检查。我还试过用插件完成“字段类型替换”比如数据库里有json类型默认映射可能处理得不对这时候可以在插件里拦截column类型解析或者通过javaTypeResolver自定义规则统一转成String。另一个常见的需求是“软删除字段过滤”比如每张表都有deleted字段希望生成的查询自动带上过滤条件。这种逻辑如果手工维护很累但通过插件在每个生成的selectByExample方法里追加条件效果就很统一。插件开发上手之后MBG就不再是一个单纯的“代码模板生成器”更像是一个“持久层代码规范化工具”。我个人建议团队用MBG时把通用规则固化到插件里这样无论谁来执行生成产出的代码风格都是一致的。5. 高频问题排查与避坑技巧5.1 MySQL 8驱动与连接串的三连坑第一个坑是驱动类名。MySQL 8开始官方驱动包把com.mysql.jdbc.Driver挪到了兼容层新项目直接用com.mysql.cj.jdbc.Driver最稳。第二个坑是时区。驱动会默认读系统时区连接MySQL时如果没写serverTimezone某些环境下会报The server time zone value is unrecognized所以连接串里最好显式指定serverTimezoneAsia/Shanghai。第三个坑是nullCatalogMeansCurrent属性。如果你在连接库里执行表扫描时发现MBG死活找不到表往往就是多个catalog导致的可以在jdbcConnection内部加property namenullCatalogMeansCurrent valuetrue/这个属性会让驱动在没有显式catalog时直接把当前连接这个库作为查询目标库。很多人连不上表、提示Table not found都和这个有关系。老版本MySQL驱动上特别明显顺手加上基本能解决。5.2 覆盖、追加与XML合并的真实规则有个项目经理问过我“MBG重新生成会不会把我手写的SQL删了”这个问题确实值得认真讲。MBG的行为是Java文件在overwritetrue时重新生成并覆盖旧文件XML文件采用的是增量合并策略只补充缺失的片段不会把你手工添加的SQL删掉。依赖这条规则你完全可以在XML里放自定义SQL然后放心大胆地反复生成。但是要注意一个细节如果某次执行生成阶段报错了部分文件可能已经写入磁盘导致下次生成时把当前文件当作“已生成”跳过。所以我遇到生成报错时处理方式是先检查生成日志如果不是配置问题就把相关目录里刚才生成的临时文件清理掉再重新跑。如果文件已经污染了就直接用git回退重新生成一次比手工改来改去省事得多。另外overwritefalse时Java文件的处理逻辑有些微妙不建议日常使用。如果你不想覆盖实体类里手工加的业务方法也不应该依赖生成器的保留策略更靠谱的做法是把业务方法放到Service里实体保持纯洁。5.3 多模块工程与路径问题的处理建议MBG的targetProject路径是相对执行目录而言的。在单模块项目里直接写src/main/java没问题但如果你的项目是多模块的典型结构是parent下面有api、service、dao等多个子模块跑插件的时候执行目录不同相对路径很容易飘到奇怪的地方去。我的建议是配置里不要写裸的相对路径尽量用${project.basedir}来拼绝对路径。比如javaModelGenerator targetPackagecom.example.dao.entity targetProject${project.basedir}/dao/src/main/java/同时保证configurationFile也用了${project.basedir}定位否则你放在父工程里跑的时候Maven可能找不到配置文件。这个坑属于典型的“本地能跑换个人就跑不了”问题路径一旦定了就固化到配置里别依赖当前工作目录的运气。另外多模块下生成文件和工程结构要对齐。如果模块是dao只放Mapper和实体那生成器就要分别指定targetProject到dao模块的源码目录而不是全部塞到web模块里。我把所有生成的代码都收敛到数据访问层这样后续代码审查、权限控制都清晰。6. 最后的一点实践建议用MBG这四五年我最大的感受是这东西前期花点时间把配置和自定义插件打磨好后面每建一张表都能省下至少一两个小时的机械劳动。而且它最大的价值不只是“快”而是让所有生成的代码风格一致、结构统一团队协作时不会出现十个人写的实体类十条风格的乱象。如果你准备在项目里正式引入MBG我建议按这个顺序来先建一个独立模块放自定义插件和注释生成器把公司的代码规范固化进去再准备一份标准generatorConfig.xml模板文件里只留占位符型的环境差异项最后把执行文档写进README明确命令、输出目录、以及生成后必须人工检查的几类文件。每次生成完跑一遍测试确认基础CRUD正常再提交。这样整个流程就不依赖某个人手熟新同事照着文档也能顺利生成。一个很不起眼但好用的经验是生成前顺手看一下表设计里字段注释写得全不全。MBG会把字段注释原封不动搬到实体类上注释写得规范生成的Java文件可读性直接上一个台阶。反过来表字段没有注释生成的代码就干巴巴的。这种“生成代码顺着数据库元数据自动变好”的效果是手工写代码很难达到的。以后每建一张表先补好表注释再跑生成省的可不只是一点点。
做Java后端开发的朋友应该都对实体类、Mapper接口、XML映射文件这三件套不陌生。数据库表一多最磨人的往往不是业务逻辑本身而是照着表结构写各种getter/setter、拼CRUD语句、维护Example查询条件这类重复劳动。第一次写能忍第十次再写真的就是拿手指头敲给自己找罪受。MyBatis Generator下文统一叫MBG就是专门解决这个问题的连上数据库、读一遍表结构就能把单表的基础CRUD代码按配置批量生成出来。这篇文章不打算重复官方文档重点聊我实际项目里的用法、配置文件抠出来的细节、怎么接自定义注释和Lombok以及几个会让你当场想摔键盘的坑。1. 项目概述与核心痛点解析1.1 MyBatis Generator到底帮你省了什么MBG最开始是iBatis时代Abator生成器进化过来的在MyBatis社区里一直属于“官网低调但用的人很多”的工具。它的核心能力很简单读取数据库表结构然后按模板生成三类东西分别是Java实体类Model、操作数据库的Mapper接口、以及Mapper对应的XML映射文件。如果你打开example开关它还会生成一套Example查询条件类可以让你不写SQL就拼出带各种and、or、like、between的动态查询条件。我自己的第一个直观感受是它不是在帮你“少写代码”而是在帮你“消灭代码错误”。手写实体类时漏一个字段、类型写错一个地方编译期通常不报错跑到测试阶段才炸出来。而MBG拿着数据库真实元数据生成字段名、类型、注释都是从库里直接读出来的天然就和表结构对得上。再加上它的XML合并机制二次生成时只会追加新内容不会动你手工加进去的自定义SQL这就很舒服了。自动生成的代码结构大概是这样的实体类每个字段一个属性带getter/setter字段注释会原样带进来。Mapper接口单表的基础insert、update、delete、select方法以及配合Example用的动态查询方法。XML映射对应Mapper接口里每个方法的SQL包含ResultMap、动态where条件、批量操作的foreach片段。所以说只要你的项目是标准MyBatis或Spring Boot集成MyBatisMBG就能直接替换掉建表后最无聊的那段开发流程让你把时间花在真正需要思考的业务逻辑上。1.2 什么场景该用、什么场景不该用MBG虽然好用但也不是什么项目都适合无脑套。我个人的判断标准是只要你的数据库表是稳定结构、且需要大量单表CRUD用MBG就非常划算。比如后台管理系统、订单系统、CMS之类天天跟几十张业务表打交道每张表都要增删改查先生成一套基础代码再往里加业务方法流程跑得飞快。反过来如果你的项目是领域驱动设计驱动、对持久层代码有很强的定制需求或者你更愿意把SQL全收在手写XML里而不是依赖生成的动态SQL那MBG的用处就有限了。生成出来的Example类通常比较大有些人会觉得“不如直接写个自定义方法干净”。这种情况我建议别硬上工具是服务人的没必要为了用而用。另外大家常拿它和MyBatis-Plus自带的代码生成器对比。MyBatis-Plus的生成器也蛮好用生成完之后直接配套BaseMapper的通用CRUD方法生成体验更“现代”。但如果你项目里不想引MyBatis-Plus那套东西或者公司规范指定用原生MyBatisMBG依然是稳妥选择。它的优势在于稳、成熟、可定制性强无论换到哪个项目配置逻辑都是那几套不容易踩出花来。2. 环境准备与运行方式选型2.1 版本与依赖的坑点MBG的官方Maven坐标是org.mybatis.generator:mybatis-generator-core配套的Maven插件是mybatis-generator-maven-plugin。目前用的比较多的版本在1.3.x到1.4.x之间1.4.x对JDK 8和JDK 11的兼容性很好新项目建议直接用1.4.2或更新的稳定版老项目如果原本是1.3.7也不用急着升配置文件的写法基本兼容。这块有一个很多人容易忽略的坑MBG插件本身不依赖数据库驱动它需要你额外在插件里配置驱动依赖。比如连MySQL就要在Maven插件内部声明mysql-connector-java。如果你用的是MySQL 8及以上驱动类名必须从com.mysql.jdbc.Driver换成com.mysql.cj.jdbc.Driver不换的话连接串直接报ClassNotFoundException。我一般建议在插件配置里显式带上依赖而不是依赖项目的全局依赖传递这样生成环境和运行环境是隔离的也省得项目里升级驱动版本时把生成脚本带崩了。我常用的插件配置是这样的plugin groupIdorg.mybatis.generator/groupId artifactIdmybatis-generator-maven-plugin/artifactId version1.4.2/version configuration configurationFile${project.basedir}/src/main/resources/generatorConfig.xml/configurationFile overwritetrue/overwrite verbosetrue/verbose /configuration dependencies dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version /dependency /dependencies /pluginoverwrite这个参数值是true的话每次重新生成时Java文件整体覆盖如果设成falseMBG可能会按自己的合并策略处理已有文件实际用下来我基本都是overwritetrue。因为XML文件有专门的合并逻辑Java文件覆盖掉重来反而更可控前提是你的实体类里没有手工加过业务方法。2.2 三种运行方式实测对比MBG常见的有三种运行方式Maven插件方式、Java编程式调用、命令行方式。我大部分时候用的都是Maven插件方式最省事一条命令跑完。Java编程式适合把生成动作集成到自动化构建或者自研脚手架平台里命令行则适合在一些临时环境里快速生成不过还得手工准备classpath稍微繁琐一些。运行方式优点缺点适合场景Maven插件配置清晰、依赖隔离、一键执行需要项目里有Maven环境日常开发90%的场景够用Java编程式调用可以在代码里动态控制配置做二次封装需要自己写启动类和参数传递逻辑自研生成平台、自动化CI流程命令行轻量、不用写Java代码classpath和驱动依赖要自己管理临时或多环境手工生成命令行跑的时候需要拿到JDBC驱动和MBG核心jar包然后把-configfile指向配置文件例如java -jar mybatis-generator-core-1.4.2.jar -configfile ./generatorConfig.xml。但你要保证这个classpath里有MySQL驱动不然第一步连接数据库就挂了。Maven插件靠dependencies把驱动带进去这块体验确实最好。如果不是搞特殊自动化需求老老实实Maven插件就够了。想封装成公司内部脚手架的话再考虑Java编程式。3. 配置文件全拆解与生成实操3.1 generatorConfig.xml核心标签逐项拆解MBG的核心配置都放在一个generatorConfig.xml里文件结构不复杂但每个标签的作用要搞清楚不然照抄网上配置容易踩坑。整套文件最外层是generatorConfiguration内部主要分几块properties加载外置属性文件、context定义一组生成上下文、jdbcConnection连数据库、javaTypeResolver做JDBC类型到Java类型的映射然后是三个生成器分别控制实体类、XML、Mapper接口的输出位置。properties标签很实用可以把数据库地址、账号密码单独抽到generator.properties里生成脚本入库。我习惯把连接串和密码放外面generatorConfig.xml里用${jdbc.url}这种占位符引用这样换环境或者交给别人执行时不用翻配置文件找密码。context是整个生成任务的根。它有id、targetRuntime、defaultModelType这些属性。targetRuntime建议用MyBatis3它可以决定生成出来的Mapper风格是原生MyBatis3还是带Example的MyBatis3Simple。如果不想生成那一大堆Example类用MyBatis3Simple会更清爽只有最基础的CRUD。defaultModelType我推荐flat这样每张表只生成一个实体类不会有主键类和BLOB类拆出来的情况。如果你用默认的conditional遇到BLOB字段时可能会多拆出WithBLOBs子类类层次一下子就变复杂了。业务系统里这种拆分类特别烦人平铺反而是最直观的。javaTypeResolver用来自定义类型转换最常用的一个属性是forceBigDecimals。如果数据库里有DECIMAL类型的金额字段默认情况下JDBC映射可能会转成Double或Float这不适合金额计算设成true之后DECIMAL统一映射成BigDecimal精度就稳了。我之前踩过坑没设这个属性金额字段后面计算时出现了小数精度问题查了半天发现生成出来是Double简直想拍桌子。3.2 5分钟生成一张表的完整配置与执行过程下面给一份我实际项目里跑过的精简配置数据库是MySQL 8生成的是一张用户表。直接复制到项目对应位置改一下连接信息就能用。?xml version1.0 encodingUTF-8? !DOCTYPE generatorConfiguration PUBLIC -//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN http://mybatis.org/dtd/mybatis-generator-config_1_0.dtd generatorConfiguration properties resourcegenerator.properties/ context idmysqlContext targetRuntimeMyBatis3 defaultModelTypeflat jdbcConnection driverClasscom.mysql.cj.jdbc.Driver connectionURL${jdbc.url} userId${jdbc.username} password${jdbc.password} property namenullCatalogMeansCurrent valuetrue/ /jdbcConnection javaTypeResolver property nameforceBigDecimals valuetrue/ /javaTypeResolver javaModelGenerator targetPackagecom.example.demo.entity targetProjectsrc/main/java property nametrimStrings valuetrue/ /javaModelGenerator sqlMapGenerator targetPackagemapper targetProjectsrc/main/resources/ javaClientGenerator typeXMLMAPPER targetPackagecom.example.demo.mapper targetProjectsrc/main/java/ table tableNameuser domainObjectNameUser enableCountByExamplefalse enableUpdateByExamplefalse enableDeleteByExamplefalse enableSelectByExamplefalse selectByExampleQueryIdfalse/ /context /generatorConfiguration连接串里如果带了参数注意XML里要转义必须写成amp;比如jdbc:mysql://localhost:3306/demo?useSSLfalseamp;serverTimezoneAsia/Shanghai。不转义的话直接就是XML解析报错白折腾一趟。跑之前先确认generator.properties里有这仨配置jdbc.urljdbc:mysql://localhost:3306/demo_db?useSSLfalseserverTimezoneAsia/Shanghai jdbc.usernameroot jdbc.password123456然后在项目根目录执行mvn mybatis-generator:generate看到BUILD SUCCESS之后去src/main/java和src/main/resources各目录下面看一眼就会发现实体、Mapper接口和XML文件都已经生成好了。整个过程从改配置到执行熟练之后确实不到5分钟。3.3 生成结果怎么看目录、代码与增量机制生成完的代码目录通常会这样分布com.example.demo.entity.User字段、getter/setter注释直接搬表注释。com.example.demo.mapper.UserMapper接口方法声明。resources/mapper/UserMapper.xmlSQL实现和ResultMap。如果你是第一次跑直接把XML文件塞进MyBatis的Mapper扫描路径就行。我习惯在Spring Boot配置里指一下mapper-locationsmybatis: mapper-locations: classpath:mapper/*.xml然后启动项目做个单元测试或者写个接口确认基础CRUD没问题就说明流程通了。这里要讲清楚一个很多人误会的点MBG在二次生成时Java文件会被覆盖但XML文件不会全量覆盖它只会把缺失的节点追加进去。所以你手工改过XML里的SQL片段比如加了一段自定义select重新生成后这段内容依然保留。这是MBG最贴心的机制之一也是它能在一个项目里长期反复用的底气。当然前提是别去手工改XML里由MBG管理的那段ResultMap和基础SQL改了也会被它纠正回来。4. 进阶定制注释、Lombok与插件机制4.1 自定义注释生成器把默认注释换成自己的风格默认生成的Java文件注释会带一段“This class was generated by MyBatis Generator”英文注释以及每个字段继承表注释后的描述。说实话这个注释在代码规约比较严格的公司里可能会被要求改掉。没问题MBG留了口子自己写个类继承DefaultCommentGenerator覆盖对应方法就行。我写过的一个简易自定义注释生成器大致长这样package com.example.generator; import org.mybatis.generator.api.IntrospectedTable; import org.mybatis.generator.api.dom.java.*; import org.mybatis.generator.internal.DefaultCommentGenerator; public class MyCommentGenerator extends DefaultCommentGenerator { Override public void addModelClassComment(TopLevelClass topLevelClass, IntrospectedTable introspectedTable) { String tableName introspectedTable.getFullyQualifiedTable().getIntrospectedTableName(); topLevelClass.addJavaDocLine(/**); topLevelClass.addJavaDocLine( * 数据表对应的实体类 tableName); topLevelClass.addJavaDocLine( * 由MyBatis Generator生成禁止手工修改。); topLevelClass.addJavaDocLine( */); } Override public void addGeneralMethodComment(Method method, IntrospectedTable introspectedTable) { // 不生成方法级别注释保持代码清爽 } }然后在generatorConfig.xml里指定到它不要忘了把这个类的编译产物加到Maven插件依赖里否则会报找不到类commentGenerator typecom.example.generator.MyCommentGenerator/如果项目是多模块建议把这个自定义类放在一个独立的公共模块里并在插件依赖中引用对应模块。一般我会把这种生成期辅助类放到generator-tools模块和数据源驱动一起作为插件依赖避免和业务代码耦合。4.2 让生成的实体直接带上Lombok注解不少项目现在都全面使用Lombok实体类不再写一堆getter/setter。MBG默认是不生成Lombok注解的你要么手动在每个实体上补要么用插件机制在生成的类上自动加。后者是正路一次配置以后所有表生成都自动带注解。写插件也不复杂核心就是继承PluginAdapter在modelBaseRecordClassGenerated里给生成的类加上Data和Builder注解。我常用的示例代码如下package com.example.generator; import org.mybatis.generator.api.PluginAdapter; import org.mybatis.generator.api.IntrospectedTable; import org.mybatis.generator.api.dom.java.TopLevelClass; public class LombokPlugin extends PluginAdapter { Override public boolean modelBaseRecordClassGenerated(TopLevelClass topLevelClass, IntrospectedTable introspectedTable) { topLevelClass.addImportedType(lombok.Data); topLevelClass.addImportedType(lombok.Builder); topLevelClass.addAnnotation(Data); topLevelClass.addAnnotation(Builder); return true; } Override public boolean modelExampleClassGenerated(TopLevelClass topLevelClass, IntrospectedTable introspectedTable) { topLevelClass.addImportedType(lombok.Data); topLevelClass.addAnnotation(Data); return true; } }配置里这样挂载plugin typecom.example.generator.LombokPlugin/加了之后实体类就清爽很多字段也直接从表结构带过来了。不过有一点得注意如果同时生成Example类也要给Example类加上合适的Lombok注解不然它生成出来还是四处都是getter和setter整体风格就不统一了。4.3 插件机制还有什么常见玩法插件机制是MBG里最值得投入精力研究的部分。除了加注解你还可以用它做很多结构性的调整。比较常见的是让实体类自动实现Serializable、给Mapper接口方法加统一注释、调整Mapper接口的命名规则甚至可以在生成完成后做一遍代码规范检查。我还试过用插件完成“字段类型替换”比如数据库里有json类型默认映射可能处理得不对这时候可以在插件里拦截column类型解析或者通过javaTypeResolver自定义规则统一转成String。另一个常见的需求是“软删除字段过滤”比如每张表都有deleted字段希望生成的查询自动带上过滤条件。这种逻辑如果手工维护很累但通过插件在每个生成的selectByExample方法里追加条件效果就很统一。插件开发上手之后MBG就不再是一个单纯的“代码模板生成器”更像是一个“持久层代码规范化工具”。我个人建议团队用MBG时把通用规则固化到插件里这样无论谁来执行生成产出的代码风格都是一致的。5. 高频问题排查与避坑技巧5.1 MySQL 8驱动与连接串的三连坑第一个坑是驱动类名。MySQL 8开始官方驱动包把com.mysql.jdbc.Driver挪到了兼容层新项目直接用com.mysql.cj.jdbc.Driver最稳。第二个坑是时区。驱动会默认读系统时区连接MySQL时如果没写serverTimezone某些环境下会报The server time zone value is unrecognized所以连接串里最好显式指定serverTimezoneAsia/Shanghai。第三个坑是nullCatalogMeansCurrent属性。如果你在连接库里执行表扫描时发现MBG死活找不到表往往就是多个catalog导致的可以在jdbcConnection内部加property namenullCatalogMeansCurrent valuetrue/这个属性会让驱动在没有显式catalog时直接把当前连接这个库作为查询目标库。很多人连不上表、提示Table not found都和这个有关系。老版本MySQL驱动上特别明显顺手加上基本能解决。5.2 覆盖、追加与XML合并的真实规则有个项目经理问过我“MBG重新生成会不会把我手写的SQL删了”这个问题确实值得认真讲。MBG的行为是Java文件在overwritetrue时重新生成并覆盖旧文件XML文件采用的是增量合并策略只补充缺失的片段不会把你手工添加的SQL删掉。依赖这条规则你完全可以在XML里放自定义SQL然后放心大胆地反复生成。但是要注意一个细节如果某次执行生成阶段报错了部分文件可能已经写入磁盘导致下次生成时把当前文件当作“已生成”跳过。所以我遇到生成报错时处理方式是先检查生成日志如果不是配置问题就把相关目录里刚才生成的临时文件清理掉再重新跑。如果文件已经污染了就直接用git回退重新生成一次比手工改来改去省事得多。另外overwritefalse时Java文件的处理逻辑有些微妙不建议日常使用。如果你不想覆盖实体类里手工加的业务方法也不应该依赖生成器的保留策略更靠谱的做法是把业务方法放到Service里实体保持纯洁。5.3 多模块工程与路径问题的处理建议MBG的targetProject路径是相对执行目录而言的。在单模块项目里直接写src/main/java没问题但如果你的项目是多模块的典型结构是parent下面有api、service、dao等多个子模块跑插件的时候执行目录不同相对路径很容易飘到奇怪的地方去。我的建议是配置里不要写裸的相对路径尽量用${project.basedir}来拼绝对路径。比如javaModelGenerator targetPackagecom.example.dao.entity targetProject${project.basedir}/dao/src/main/java/同时保证configurationFile也用了${project.basedir}定位否则你放在父工程里跑的时候Maven可能找不到配置文件。这个坑属于典型的“本地能跑换个人就跑不了”问题路径一旦定了就固化到配置里别依赖当前工作目录的运气。另外多模块下生成文件和工程结构要对齐。如果模块是dao只放Mapper和实体那生成器就要分别指定targetProject到dao模块的源码目录而不是全部塞到web模块里。我把所有生成的代码都收敛到数据访问层这样后续代码审查、权限控制都清晰。6. 最后的一点实践建议用MBG这四五年我最大的感受是这东西前期花点时间把配置和自定义插件打磨好后面每建一张表都能省下至少一两个小时的机械劳动。而且它最大的价值不只是“快”而是让所有生成的代码风格一致、结构统一团队协作时不会出现十个人写的实体类十条风格的乱象。如果你准备在项目里正式引入MBG我建议按这个顺序来先建一个独立模块放自定义插件和注释生成器把公司的代码规范固化进去再准备一份标准generatorConfig.xml模板文件里只留占位符型的环境差异项最后把执行文档写进README明确命令、输出目录、以及生成后必须人工检查的几类文件。每次生成完跑一遍测试确认基础CRUD正常再提交。这样整个流程就不依赖某个人手熟新同事照着文档也能顺利生成。一个很不起眼但好用的经验是生成前顺手看一下表设计里字段注释写得全不全。MBG会把字段注释原封不动搬到实体类上注释写得规范生成的Java文件可读性直接上一个台阶。反过来表字段没有注释生成的代码就干巴巴的。这种“生成代码顺着数据库元数据自动变好”的效果是手工写代码很难达到的。以后每建一张表先补好表注释再跑生成省的可不只是一点点。
