1. 项目概述告别重复劳动拥抱高效开发如果你是一名Java后端开发者尤其是使用Spring Boot和MyBatis这套经典组合的那么“CRUD”这个词对你来说一定不陌生。每天对着数据库表一遍又一遍地写着几乎雷同的实体类Entity、数据访问层接口Mapper、服务层接口Service及其实现类这种重复、枯燥且容易出错的体力活占据了大量宝贵的开发时间。更头疼的是一旦表结构有变动这些代码又得手动同步修改维护成本直线上升。“MyBatis-Plus代码自动生成器”就是为了终结这种局面而生的利器。它不是一个独立的新框架而是MyBatis-Plus简称MP这个强大的MyBatis增强工具包中的一个核心功能模块。简单来说你只需要告诉它你的数据库连接信息和表名它就能像一位不知疲倦的“代码工人”自动为你生成包括Entity、Mapper、Service、Controller在内的全套基础代码甚至能生成配套的XML映射文件。这不仅仅是简单的复制粘贴生成的代码结构清晰遵循最佳实践并且原生集成了MP的各种便捷功能如通用CRUD方法、分页插件、逻辑删除等开箱即用。对于个人开发者或小团队它能让你快速搭建项目骨架将精力集中在核心业务逻辑上。对于中大型团队它能统一代码规范减少因手写导致的风格差异和低级错误提升整体代码质量和开发效率。无论你是想快速验证一个想法还是维护一个庞大的企业级应用这个自动生成器都能成为你开发工具箱里不可或缺的一环。接下来我们就深入拆解它的工作原理、核心配置以及如何在实际项目中玩转它避开那些我踩过的“坑”。2. 核心原理与架构设计解析2.1 生成器的核心工作流MyBatis-Plus的代码生成器AutoGenerator本质上是一个基于元数据Metadata的模板渲染引擎。它的工作流程可以清晰地分为四个阶段理解这个流程有助于我们后续进行深度定制。第一阶段数据源连接与元数据提取这是所有工作的起点。生成器通过你配置的DataSourceConfig连接到指定的数据库。连接成功后它会执行一系列JDBC元数据查询获取目标数据库、目标表的结构信息。这些信息包括但不限于表名、表注释、所有字段的列名、数据类型及其对应的Java类型、是否为主键、是否可为空、默认值以及字段注释。这一步的准确性直接决定了生成代码的质量因此一个稳定、权限足够的数据库连接至关重要。第二阶段策略配置与信息加工获取到原始的元数据后生成器并不会直接使用。它会根据你预先设定的各种“策略”StrategyConfig对这些信息进行加工和转换。这是生成器智能化的核心体现。例如命名策略将下划线分隔的表名如user_order转换为大驼峰命名的Java类名UserOrder。字段类型转换将数据库的varchar映射为Stringdatetime映射为LocalDateTimetinyint(1)映射为Boolean。逻辑处理根据字段名如deleted、is_deleted或自定义规则自动为实体类添加TableLogic注解实现逻辑删除。过滤与包含决定哪些表需要生成哪些字段需要被忽略如不希望在实体类中出现create_time和update_time字段而是通过MP的自动填充功能处理。第三阶段模板渲染与文件生成经过加工后的“数据模型”包含了表信息、字段信息、各种配置参数被传递到FreeMarker模板引擎。MyBatis-Plus内置了一套默认的模板文件.ftl后缀分别对应Entity、Mapper、Service、Controller等。模板引擎将数据模型填充到这些模板中生成最终的Java源代码或XML文件内容。你可以完全自定义这些模板以生成符合你团队独特编码规范的代码。第四阶段文件输出最后生成器根据PackageConfig和GlobalConfig的配置将渲染好的内容写入到项目源码目录的指定包路径下。它会自动创建所需的目录结构确保生成的代码立即可以被项目识别和编译。2.2 与MyBatis-Plus生态的深度集成生成的代码不是孤立的它与MyBatis-Plus的其他特性无缝集成这也是其价值倍增的关键。通用CRUD接口生成的Mapper接口会自动继承MP的BaseMapperT。这意味着你的Mapper立刻拥有了数十个通用的单表操作方法如selectByIdinsertupdateByIdselectListselectPage等无需编写任何SQL。ActiveRecord模式支持如果你启用了此模式生成的Entity类会继承ModelT类允许你通过实体对象本身直接进行CRUD操作如user.insert() 提供了另一种简洁的数据操作方式。注解驱动生成器会根据策略自动为实体类添加MP的核心注解。TableName 指定实体对应的数据库表名。TableId 标识主键字段并可指定主键类型如自增、UUID。TableField 处理字段映射如属性名与列名不一致、自动填充策略等。Version/TableLogic 根据配置自动添加乐观锁或逻辑删除注解。插件就绪生成的代码结构天然适配MP的分页插件PaginationInterceptor/MybatisPlusInterceptor、性能分析插件等。你只需要在项目配置中声明这些插件生成代码中的分页查询等方法即可直接使用。注意生成器只负责生成“骨架”代码。对于复杂的联表查询、动态SQL、特定的业务逻辑仍然需要你在生成的Mapper XML文件或Service层中手动补充。它的目标是解放95%的重复性基础编码工作。3. 从零开始详细配置与实战演练理论讲完我们来点实际的。下面我将通过一个完整的示例展示如何配置并运行代码生成器。假设我们有一个shop_db数据库里面有一张t_user表。3.1 环境准备与依赖引入首先确保你的Spring Boot项目中已经引入了MyBatis-Plus的依赖。代码生成器是mybatis-plus-boot-starter的一部分但为了更清晰我们通常也会显式引入生成器模块。dependencies !-- Spring Boot Web (根据项目需要) -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- MyBatis-Plus 启动器 -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.1/version !-- 请使用最新稳定版 -- /dependency !-- 代码生成器模块 -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-generator/artifactId version3.5.3.1/version /dependency !-- 模板引擎依赖默认使用Freemarker -- dependency groupIdorg.freemarker/groupId artifactIdfreemarker/artifactId version2.3.31/version /dependency !-- 数据库驱动 -- dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency !-- 若使用其他数据库如PostgreSQL则替换为对应驱动 -- /dependencies3.2 编写代码生成器主程序我们不建议将生成器代码放在主应用逻辑中。通常的做法是创建一个独立的、可执行的类例如CodeGenerator在需要时运行它。下面是一个高度可配置的示例import com.baomidou.mybatisplus.generator.AutoGenerator; import com.baomidou.mybatisplus.generator.config.*; import com.baomidou.mybatisplus.generator.config.rules.NamingStrategy; import com.baomidou.mybatisplus.generator.engine.FreemarkerTemplateEngine; public class CodeGenerator { public static void main(String[] args) { // 1. 创建代码生成器对象 AutoGenerator generator new AutoGenerator(); // 2. 全局配置 GlobalConfig globalConfig new GlobalConfig(); // 获取当前项目路径 String projectPath System.getProperty(user.dir); // 设置输出目录 globalConfig.setOutputDir(projectPath /src/main/java); // 设置作者会出现在类注释中 globalConfig.setAuthor(YourName); // 生成后是否打开输出目录Windows下有用 globalConfig.setOpen(false); // 是否覆盖已有文件谨慎使用 globalConfig.setFileOverride(true); // 设置主键类型ASSIGN_ID:雪花算法 ASSIGN_UUID:UUID, AUTO:自增 globalConfig.setIdType(IdType.ASSIGN_ID); // 实体属性 Swagger2/3 注解按需开启 // globalConfig.setSwagger2(true); generator.setGlobalConfig(globalConfig); // 3. 数据源配置 DataSourceConfig dataSourceConfig new DataSourceConfig(); dataSourceConfig.setUrl(jdbc:mysql://localhost:3306/shop_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai); dataSourceConfig.setDriverName(com.mysql.cj.jdbc.Driver); dataSourceConfig.setUsername(root); dataSourceConfig.setPassword(yourpassword); generator.setDataSource(dataSourceConfig); // 4. 包配置 PackageConfig packageConfig new PackageConfig(); // 设置父包名下面的模块包都会在这个下面 packageConfig.setParent(com.example.shop); // 设置实体类包名 packageConfig.setEntity(entity); // 设置Mapper接口包名 packageConfig.setMapper(mapper); // 设置Service接口包名 packageConfig.setService(service); // 设置Service实现类包名 packageConfig.setServiceImpl(service.impl); // 设置Controller包名 packageConfig.setController(controller); // 设置XML映射文件路径推荐放在resources下 packageConfig.setXml(mapper.xml); generator.setPackageInfo(packageConfig); // 5. 策略配置最核心、最灵活的部分 StrategyConfig strategy new StrategyConfig(); // 数据库表映射到实体的命名策略下划线转驼峰 strategy.setNaming(NamingStrategy.underline_to_camel); // 数据库表字段映射到实体属性的命名策略同上 strategy.setColumnNaming(NamingStrategy.underline_to_camel); // 实体类使用Lombok强烈推荐 strategy.setEntityLombokModel(true); // 生成 RestController 控制器 strategy.setRestControllerStyle(true); // 设置需要生成的表名支持多个用逗号分隔 strategy.setInclude(t_user, t_order, t_product); // 设置表前缀生成实体时会自动去掉。例如 t_user - User strategy.setTablePrefix(t_); // 逻辑删除字段名数据库中 strategy.setLogicDeleteFieldName(deleted); // 乐观锁字段名数据库中 // strategy.setVersionFieldName(version); // 自动填充配置需配合MetaObjectHandler使用 // TableFill createTime new TableFill(create_time, FieldFill.INSERT); // TableFill updateTime new TableFill(update_time, FieldFill.INSERT_UPDATE); // strategy.setTableFillList(Arrays.asList(createTime, updateTime)); // 控制器映射路径风格下划线转连字符如 /userOrder - /user-order strategy.setControllerMappingHyphenStyle(true); generator.setStrategy(strategy); // 6. 模板引擎配置使用默认的Freemarker generator.setTemplateEngine(new FreemarkerTemplateEngine()); // 7. 执行生成 generator.execute(); } }运行这个main方法如果控制台没有报错并提示“生成成功”那么打开你的项目src/main/java/com/example/shop目录你会看到一整套层次分明的代码已经生成好了。3.3 核心配置项深度解读上面的示例中包含了最常用的配置但生成器的能力远不止于此。下面我拆解几个关键配置分享我的心得1. 全局配置 (GlobalConfig)setFileOverride(true/false) 这是最容易踩坑的地方。建议在第一次生成或确定要覆盖时设为true生成后立即改为false。否则下次运行可能会意外覆盖你手动编写的业务代码造成不可逆的损失。我个人的习惯是将这个配置项提取到程序参数或环境变量中动态控制。setIdType() 主键策略的选择至关重要。AUTO依赖于数据库自增在分布式环境下可能成为瓶颈。ASSIGN_ID默认雪花算法和ASSIGN_UUID更适合分布式系统。需要根据你的业务场景和数据库设计提前决定。2. 策略配置 (StrategyConfig)setInclude()和setExclude() 这是控制生成范围的主要手段。对于大型数据库建议使用setInclude明确指定本次需要生成的表避免一次性生成所有表导致混乱。setEntityLombokModel(true)强烈建议开启。Lombok会自动为实体类生成Getter、Setter、toString()、equals()、hashCode()方法以及无参/全参构造函数让实体类代码极其简洁。但需要确保项目已引入Lombok依赖并且IDE安装了Lombok插件。setLogicDeleteFieldName() 如果你遵循MP的逻辑删除约定使用一个标志位字段如deleted在此配置后生成的实体类对应字段会自动添加TableLogic注解Service层生成的删除方法会自动变为逻辑删除。自定义模板 这是高级玩法。如果你对默认生成的Controller代码风格不满意比如你想统一返回固定的Result包装类可以复制mybatis-plus-generator源码中的模板文件在jar包的templates目录下到项目的resources/templates目录然后进行修改。最后在代码中通过TemplateConfig指定你的自定义模板路径即可。4. 进阶应用与场景化定制掌握了基础生成后我们来看看如何应对更复杂的实际场景。4.1 处理数据库字段级加密/解密这是最近一个比较热的需求对应热词“数据库字段级加密”。假设t_user表的phone和email字段需要加密存储。MyBatis-Plus生成器本身不直接处理加解密但我们可以通过结合MP的TypeHandler和自定义注解来优雅地实现并且让生成器为我们打好基础。第一步创建自定义类型处理器// 1. 定义一个加密/解密的工具类示例使用AES Component public class CryptoUtil { private static final String SECRET_KEY your-secret-key-16/24/32bytes; public String encrypt(String data) { // 实现AES加密逻辑返回Base64编码字符串 // ... return encryptedBase64Str; } public String decrypt(String encryptedBase64Str) { // 实现AES解密逻辑 // ... return originalData; } } // 2. 自定义TypeHandler public class EncryptTypeHandler extends BaseTypeHandlerString { Autowired // 注意TypeHandler是MyBatis实例化的常规注入可能不行可通过其他方式获取Bean private static CryptoUtil cryptoUtil; // 设置ApplicationContext以便获取Bean public static void setCryptoUtil(CryptoUtil util) { cryptoUtil util; } Override public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) throws SQLException { // 写入数据库时加密 ps.setString(i, cryptoUtil.encrypt(parameter)); } Override public String getNullableResult(ResultSet rs, String columnName) throws SQLException { // 从数据库读取时解密 String dbData rs.getString(columnName); return dbData ! null ? cryptoUtil.decrypt(dbData) : null; } Override public String getNullableResult(ResultSet rs, int columnIndex) throws SQLException { String dbData rs.getString(columnIndex); return dbData ! null ? cryptoUtil.decrypt(dbData) : null; } Override public String getNullableResult(CallableStatement cs, int columnIndex) throws SQLException { String dbData cs.getString(columnIndex); return dbData ! null ? cryptoUtil.decrypt(dbData) : null; } }第二步创建自定义注解可选但更清晰Documented Retention(RetentionPolicy.RUNTIME) Target(ElementType.FIELD) public interface EncryptedField { }第三步如何与生成器结合生成器无法自动识别哪些字段需要加密。你有两种策略生成后手动修改 先让生成器生成标准代码。然后手动在User实体的phone和email字段上添加TableField(typeHandler EncryptTypeHandler.class)注解。这是最直接的方式。自定义模板 更高级的做法是修改实体类生成模板entity.java.ftl。在模板中判断字段名如果字段名在预定义的加密字段列表中则在生成的TableField注解中自动加入typeHandler配置。这需要你对FreeMarker模板语法比较熟悉。第四步在Spring中注册TypeHandler在你的MyBatis配置类或主应用类中确保EncryptTypeHandler被正确注册并且CryptoUtil能被其访问到可以通过PostConstruct静态注入。实操心得字段加密虽然增强了安全性但会导致该字段失去索引功能且模糊查询LIKE将无法实现。务必在业务设计初期就权衡好安全和功能的边界。通常只对极其敏感的信息如身份证号、银行卡号进行加密而手机号、邮箱可能更适合脱敏显示而非全字段加密。4.2 实现动态数据源与租户隔离“动态取消租户隔离”这个热词指向了多租户SaaS场景。MyBatis-Plus提供了强大的多租户插件TenantLineInnerInterceptor。生成器在此场景下的价值在于能快速为所有相关业务表生成代码基础。核心思路你的每张业务表都应该有一个租户ID字段例如tenant_id。在生成实体类时可以通过策略配置自动为每张表添加这个公共字段并为实体类生成对应的属性。配置MP的多租户插件自动在SQL中注入tenant_id ?条件。“动态取消隔离”通常指在特定场景如超级管理员查看所有数据下需要临时忽略租户条件。这可以通过MP插件提供的TenantLineHandler接口中的ignoreTable方法判断或者使用InterceptorIgnore注解在Mapper方法上标记。生成器在这里的作用是保证数据结构的一致性通过配置StrategyConfig的setSuperEntityColumns(“tenant_id”)方法可以让所有生成的实体类都从一个包含tenantId字段的基类继承避免手动为每个实体添加的麻烦。4.3 生成代码后的标准开发流程代码生成不是终点而是标准化开发的起点。一个良好的流程是设计数据库表。运行生成器生成基础CRUD代码。将生成的文件纳入版本控制如Git。这是关键很多人只把生成的代码当成临时产物其实它们和手写代码一样重要。在生成的Service或Controller基础上添加具体的业务逻辑。例如在UserServiceImpl中编写复杂的用户注册、登录逻辑。如果需要修改表结构增加字段、修改类型先修改数据库。将生成器的setFileOverride(true)并只include需要更新的表重新生成。谨慎处理合并冲突生成器会覆盖整个实体类。如果你在实体类上添加了自定义注解或方法它们会被覆盖。有几种策略将自定义内容移到独立的类或父类中。使用setFileOverride(false)然后手动将新字段合并到现有实体类中比较麻烦。最好的实践是尽量不在生成的实体类中添加业务逻辑。业务方法应放在Service或专门的领域模型中。实体类尽量保持为纯粹的数据载体贫血模型这样重新生成时的风险最低。5. 常见问题排查与性能调优即使工具强大在实际使用中还是会遇到各种问题。下面是我总结的一些典型“坑”及其解决方案。5.1 生成过程报错与排查问题现象可能原因解决方案java.sql.SQLException: Access denied数据库连接URL、用户名或密码错误用户权限不足。1. 检查连接字符串的IP、端口、数据库名。2. 使用数据库客户端工具测试账号密码。3. 确保该账号有查询information_schema库的权限。Unknown database ‘xxx’数据库不存在。确认数据库名是否正确或先在MySQL中创建该数据库。生成的文件为空或内容不全表名大小写问题表不存在策略过滤掉了所有表。1. 检查setInclude中的表名是否与数据库中的完全一致注意大小写敏感设置。2. 检查setTablePrefix是否错误地过滤了表名。Lombok注解生成但IDE报错IDE未安装Lombok插件项目未启用注解处理。1. 在IntelliJ IDEA或Eclipse中安装对应Lombok插件并重启IDE。2. 对于某些IDE可能需要在设置中启用“注解处理”Annotation Processing。生成的字段类型不对数据库驱动版本旧无法正确识别新类型如datetime映射为Date而非LocalDateTime。1. 升级数据库驱动到最新稳定版。2. 在数据源配置URL中指定时区参数。3. 使用IDbType进行自定义类型转换高级。运行生成器后项目编译报错生成的代码引用了不存在的类或注解依赖冲突。1. 检查是否引入了必要的依赖如Lombok、Swagger。2. 检查MP版本与生成器版本是否一致。3. 清理项目并重新构建mvn clean compile。5.2 生成代码的性能与最佳实践不要频繁运行生成器 尤其是在团队协作中频繁覆盖文件会导致代码历史混乱和合并冲突。确立一个规范只在表结构发生变更时由专人负责运行生成器并提交这次生成的代码变更。其他开发者通过拉取更新来同步基础代码。模块化与分包 对于大型项目所有实体、Mapper都放在同一个包下会变得臃肿。可以利用PackageConfig为不同的业务模块设置不同的父包。或者更常见的做法是使用多模块Maven/Gradle项目为每个微服务或业务模块单独配置一个生成器只生成其需要的表对应的代码。自定义模板以统一规范 这是将生成器价值最大化的手段。花点时间定制一套属于你们团队的模板可以确保生成的Controller统一返回格式、生成的Service包含标准日志注解、生成的实体类带有特定的注解校验等。一次投入长期受益。将生成器脚本化 把上面的CodeGenerator类进一步封装读取外部配置文件如generator.properties或application.yml中的自定义配置这样可以在不修改代码的情况下切换数据库、调整包名、选择要生成的表。甚至可以集成到Maven/Gradle构建生命周期中实现更自动化的代码生成。处理好“逻辑删除”与唯一索引的冲突 这是一个经典的业务坑。如果你的表对某个字段如用户名username建立了唯一索引又启用了逻辑删除。当用户A删除逻辑删除了自己的账号后用户B试图注册相同的用户名会因为唯一索引冲突而失败。解决方案通常有两种一是在业务逻辑上将“已删除”记录的用户名修改为一个唯一但无意义的值如deleted_ 原用户名 id二是在数据库层面建立包含deleted字段的复合唯一索引但这种方式在已删除记录很多时可能影响性能。生成器帮你加上了TableLogic但业务上的并发问题需要你自己在设计时考虑周全。最后我想分享一点个人体会MyBatis-Plus代码生成器最好的使用方式是把它当作一位“严格的初始化助手”。它负责打下坚实、规范的基础而你将宝贵的创造力投入到复杂的业务逻辑、算法优化和系统架构中。不要试图用它生成一切也不要因为它生成后还需要手动调整而感到失望。恰恰是这种“80%自动20%手动”的模式在效率和灵活性之间取得了最佳平衡。当你熟悉它之后尝试去定制它的模板让它生成的代码更贴合你的“手气”你会发现它真的能成为提升开发幸福感的利器。