1. 项目概述为什么我们需要自定义 BaseMapper在 Java 后端开发尤其是基于 Spring Boot 和 MyBatis 的生态里MyBatis-Plus简称 MP几乎成了标配。它那套开箱即用的 CRUD 接口特别是那个万能的BaseMapperT让开发者从大量重复的增删改查 SQL 编写中解放出来效率提升肉眼可见。但用久了尤其是项目进入深水区后你会发现标准BaseMapper提供的十几个通用方法开始有点“不够用”了。比如你想批量插入时忽略重复记录想根据某个复杂条件逻辑删除或者想实现一个带乐观锁版本号的通用更新方法标准接口里并没有。这时候很多人的第一反应是在 Service 层写或者在每个 Mapper 里单独定义。但这样会导致代码重复且破坏了 MP 带来的统一性和优雅感。自定义BaseMapper就是为了解决这个痛点。它不是要你抛弃 MP而是在其强大基础上进行“魔改”和“增强”让你能定义一套符合自己项目业务特性的、可复用的通用数据操作接口。这就像给你的工具箱里增加了几把特制的、顺手的扳手干起活来更得劲。今天我就结合自己踩过的坑和实战经验带你从零到一玩转 MyBatis-Plus 的自定义BaseMapper让你不仅能解决“updateById 能否将字段更新为 null”这类具体问题更能掌握一套应对未来各种定制化需求的底层方法。2. 核心思路与架构设计自定义BaseMapper的核心思路是“继承与扩展”。我们不是要重新发明轮子而是基于 MP 提供的轮子给它加个涡轮增压或者换个更耐磨的轮胎。整个设计遵循“面向接口编程”和“泛型”的思想确保扩展性的同时保持类型安全。2.1 设计目标与原则首先我们要明确自定义的目标。通常包括以下几点补充通用方法添加项目内高频使用但标准BaseMapper缺失的方法如批量插入支持重复忽略、逻辑删除增强、根据条件更新指定字段等。统一行为定制对现有方法的行为进行微调。例如让updateById在特定情况下支持更新字段为null或者为所有插入操作自动填充某些审计字段如创建人、创建时间。多租户等高级特性集成将一些通用业务逻辑如基于数据行的多租户隔离下沉到 Mapper 层通过自定义方法或注解统一处理避免业务代码污染。设计时需要遵循几个原则向下兼容自定义的 Mapper 必须完全兼容原有的BaseMapper所有方法不能影响现有功能。高内聚将与实体相关的、最基础的数据操作聚合在自定义 Mapper 中。避免过度设计只添加真正通用、高频的方法。过于业务特异性的操作应该放在 Service 层或更具体的 Mapper 中。2.2 技术方案选型接口继承 vs 默认方法实现自定义BaseMapper主要有两种方式接口继承创建一个新的接口例如MyBaseMapperT让它继承自com.baomidou.mybatisplus.core.mapper.BaseMapperT然后在这个新接口中声明你需要添加的自定义方法。这是最主流、最清晰的方式。在BaseMapper中使用 Java 8 的默认方法理论上你可以尝试修改 MP 的源码不推荐或者在某个地方定义一个包含默认方法的接口。但这会破坏 MP 本身的纯洁性且对 MP 的升级不友好实践中几乎不用。毫无疑问我们选择接口继承方案。它的好处是结构清晰职责分明并且完全遵循了开闭原则对扩展开放对修改关闭。我们所有的定制化都发生在我们自己的接口和实现里与 MP 官方代码完全解耦。3. 基础搭建创建自定义 BaseMapper 接口让我们开始动手。首先在你的项目里通常是在一个类似com.xxx.framework.mapper的包下创建你的自定义基础 Mapper 接口。package com.yourproject.framework.mapper; import com.baomidou.mybatisplus.core.conditions.Wrapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.baomidou.mybatisplus.core.toolkit.Constants; import org.apache.ibatis.annotations.Param; import java.util.Collection; /** * 自定义通用 Mapper 接口 * param T 实体类型 */ public interface MyBaseMapperT extends BaseMapperT { /** * 批量插入支持重复键忽略 * 注意此方法需要数据库支持 INSERT IGNORE 或 ON DUPLICATE KEY UPDATE 语法如 MySQL。 * 需要在对应的 XML 文件中实现具体的 SQL。 * param entityList 实体对象集合 * return 影响行数 */ Integer insertBatchSomeColumn(Param(list) CollectionT entityList); /** * 根据 ID 更新所有字段包含 null 字段 * 此方法会使用实体对象中所有的字段值进行更新包括值为 null 的字段。 * 与默认的 updateById 行为忽略 null 字段不同。 * param entity 实体对象 * return 影响行数 */ int alwaysUpdateById(Param(Constants.ENTITY) T entity); /** * 根据条件更新指定的某个字段例如设置 status 1 * param wrapper 更新条件 * param column 要更新的字段名数据库列名 * param value 要更新的值 * return 影响行数 */ int updateColumnByWrapper(Param(Constants.WRAPPER) WrapperT wrapper, Param(column) String column, Param(value) Object value); }代码解析与注意事项extends BaseMapperT这是核心确保了所有标准 CRUD 方法的继承。Param注解这是 MyBatis 的注解用于给 XML 中的 SQL 参数命名。Constants.ENTITY和Constants.WRAPPER是 MP 提供的常量分别代表实体对象和条件包装器使用它们能更好地与 MP 内部机制配合。方法命名尽量做到见名知意。insertBatchSomeColumn这个名字其实来源于 MP 内置的InsertBatchSomeColumn注入器我们这里“借用”其意。alwaysUpdateById明确表示总是更新包含null。重要提示这里只是声明了接口方法具体的 SQL 实现需要我们在对应的 MyBatis XML 映射文件中编写。MP 的默认实现是通过动态代理和内置的SqlMethod枚举来注入标准方法的 SQL对于自定义方法我们需要自己提供 SQL。4. 实现自定义 SQLXML 映射文件编写接口声明好了下一步就是为这些自定义方法提供 SQL 实现。我们需要为每个使用MyBaseMapper的实体创建或修改其对应的 Mapper XML 文件。假设我们有一个User实体其对应的 Mapper 接口是UserMapper它继承了MyBaseMapperUser。public interface UserMapper extends MyBaseMapperUser { // 这里可以再定义 User 特有的查询方法 }那么在UserMapper.xml文件中我们除了原有的 SQL还需要添加自定义方法的实现。?xml version1.0 encodingUTF-8? !DOCTYPE mapper PUBLIC -//mybatis.org//DTD Mapper 3.0//EN http://mybatis.org/dtd/mybatis-3-mapper.dtd mapper namespacecom.yourproject.module.system.mapper.UserMapper !-- 其他原有的 resultMap 和 SQL 定义 -- !-- 1. 批量插入使用 MySQL 的 IGNORE 语法避免重复 -- insert idinsertBatchSomeColumn INSERT IGNORE INTO user (id, name, email, age, tenant_id) VALUES foreach collectionlist itemitem separator, (#{item.id}, #{item.name}, #{item.email}, #{item.age}, #{item.tenantId}) /foreach /insert !-- 2. 总是根据ID更新包含null字段 -- update idalwaysUpdateById UPDATE user set name #{entity.name}, email #{entity.email}, age #{entity.age}, tenant_id #{entity.tenantId}, -- 注意所有字段都必须显式列出即使可能为null updated_time #{entity.updatedTime} /set WHERE id #{entity.id} /update !-- 3. 根据条件更新指定列 -- update idupdateColumnByWrapper UPDATE user set ${column} #{value} /set ${ew.customSqlSegment} /update /mapper关键点与避坑指南INSERT IGNORE这是 MySQL 的语法如果插入的数据导致唯一键冲突则会忽略该条插入而不是报错。其他数据库如 PostgreSQL 可以使用ON CONFLICT DO NOTHING。务必根据你的数据库类型调整 SQL。alwaysUpdateById的陷阱这个方法需要你手动列出所有需要更新的字段。这与 MP 默认的updateById动态生成 SET 子句的逻辑不同。如果你漏掉了某个字段那么即使实体对象里该字段有值也不会被更新。建议可以通过代码生成器或者利用 MP 的TableInfo辅助类在运行时动态生成这个字段列表但这会复杂很多。对于简单场景手动维护是可接受的。updateColumnByWrapper的安全警告这里直接使用了${column}和${ew.customSqlSegment}。${}是文本替换存在 SQL 注入风险column参数绝对不能来自用户前端直接输入。应该在后端用白名单或枚举严格控制。${ew.customSqlSegment}是 MP 条件包装器生成的 SQL 片段由于Wrapper本身已经做了参数化处理相对安全但也要确保Wrapper的构建是可靠的。多租户字段处理注意在 SQL 中包含了tenant_id字段。在实际的多租户场景中你通常需要通过 MP 的插件如TenantLineInnerInterceptor自动在 WHERE 条件中追加租户过滤。在我们的自定义 SQL 中也需要手动确保UPDATE 和 DELETE 操作不会跨租户。例如在alwaysUpdateById的 WHERE 条件中最好加上AND tenant_id #{entity.tenantId}。这是一个极易出错的地方。5. 高级应用解决“updateById 不能更新 null”与多租户集成现在我们来直面热搜词里的具体问题并看看如何与高级特性结合。5.1 让 updateById 支持更新字段为 nullMP 默认的updateById方法使用的是“非空更新”策略。即只有当实体对象的字段值不为null时才会被加入到 SET 语句中。这通常是我们期望的行为可以避免意外地用null覆盖数据库中的现有值。但有些场景下我们确实需要将某个字段显式地设置为null。比如清空用户的备注信息或将一个可选的关联ID置空。解决方案就是我们上面实现的alwaysUpdateById方法。当你需要更新包含 null 的字段时就调用这个方法而不是默认的updateById。更进一步你可以创建一个全局的MetaObjectHandler但那是针对字段自动填充如TableField(fill FieldFill.INSERT)。对于更新策略MP 提供了FieldStrategy注解属性public class User { TableField(updateStrategy FieldStrategy.IGNORED) // 忽略判断始终更新此字段到数据库 private String remark; // 备注信息 }将字段的updateStrategy设置为FieldStrategy.IGNORED那么在使用默认的updateById时这个字段无论是否为null都会参与更新。这比自定义一个完整的方法更轻量但它是字段粒度的控制。如何选择如果只是个别字段需要更新null用TableField(updateStrategy FieldStrategy.IGNORED)。如果需要整个实体的所有字段都参与更新全量更新或者这个行为是某个业务模块的通用需求那么使用自定义的alwaysUpdateById方法更合适。5.2 基于注解的多租户数据隔离实现多租户SaaS 系统常见要求数据在存储层面隔离。MP 提供了优雅的插件机制来实现。我们的自定义BaseMapper需要与这个机制协同工作。第一步配置多租户插件在 MyBatis-Plus 的配置类中Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 添加多租户插件 TenantLineInnerInterceptor tenantInterceptor new TenantLineInnerInterceptor(); tenantInterceptor.setTenantLineHandler(new TenantLineHandler() { Override public Expression getTenantId() { // 从当前请求的上下文中获取租户ID例如从ThreadLocal或SecurityContext中 String tenantId TenantContext.getCurrentTenantId(); if (tenantId null) { throw new RuntimeException(无法获取当前租户信息); } return new StringValue(tenantId); } Override public String getTenantIdColumn() { // 返回数据库中表示租户ID的列名 return tenant_id; } Override public boolean ignoreTable(String tableName) { // 忽略不需要租户隔离的表如全局配置表 return sys_config.equalsIgnoreCase(tableName); } }); interceptor.addInnerInterceptor(tenantInterceptor); // 可以继续添加其他插件如分页插件、乐观锁插件 interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }第二步实体类标记租户字段在你的实体类中需要有一个字段对应数据库的租户ID列并使用TableField注解标记它不是一个普通的业务字段。public class User { TableId(type IdType.ASSIGN_ID) private Long id; private String name; // ... 其他业务字段 TableField(exist false) // 重点这里设置为 exist false表示它不是数据库表的一个普通字段 private String tenantId; // 这个字段的值由多租户插件自动处理不参与普通CRUD的字段映射 }注意这里的关键是TableField(exist false)。租户ID不应该由业务代码手动设置或更新它完全由插件在运行时动态注入到SQL条件中。因此实体类中这个字段仅作为一个“标记”或用于查询不应映射到数据库表的具体列因为列名已通过插件配置getTenantIdColumn()指定。第三步在自定义 SQL 中处理租户条件关键多租户插件只能自动处理由 MP自动生成的 SQL即通过BaseMapper标准方法调用的。对于我们在 XML 中手写的自定义 SQL插件是不会自动追加租户条件的这是一个巨大的坑。你必须手动在自定义 SQL 的 WHERE 条件中添加租户过滤。修改之前的alwaysUpdateByIdSQLupdate idalwaysUpdateById UPDATE user set name #{entity.name}, email #{entity.email}, age #{entity.age}, updated_time #{entity.updatedTime} /set WHERE id #{entity.id} AND tenant_id #{entity.tenantId} !-- 手动添加租户隔离条件 -- /update同理在updateColumnByWrapper中虽然${ew.customSqlSegment}可能包含了条件但为了安全你最好也确保调用方在构建Wrapper时包含了租户条件或者在 SQL 中硬性添加update idupdateColumnByWrapper UPDATE user set ${column} #{value} /set where ${ew.customSqlSegment} !-- 为了绝对安全可以强制添加但需要能获取当前租户ID -- !-- AND tenant_id #{tenantId} -- /where /update最佳实践建议对于所有自定义的、涉及数据修改UPDATE, DELETE和范围查询SELECT ... WHERE的 SQL必须显式考虑多租户条件。可以将当前租户ID作为参数传入或者在 SQL 中通过子查询等方式关联。这需要你在设计自定义方法接口时就将租户上下文考虑进去。6. 实战自定义 BaseMapper 的完整使用流程让我们通过一个完整的 Service 层示例看看如何运用这些自定义方法。Service public class UserServiceImpl extends ServiceImplUserMapper, User implements UserService { Override Transactional(rollbackFor Exception.class) public boolean batchCreateUsers(ListUser userList) { if (CollectionUtils.isEmpty(userList)) { return true; } // 使用自定义的批量插入方法避免重复 // 假设 userList 中的用户邮箱是唯一键 int rows baseMapper.insertBatchSomeColumn(userList); log.info(批量插入了 {} 条用户记录忽略重复项。, rows); return rows 0; } Override public boolean clearUserRemark(Long userId) { User user new User(); user.setId(userId); user.setRemark(null); // 明确要设置为null // 使用默认的 updateById 无法将 remark 更新为 null除非字段注解为 IGNORED // 因此使用我们自定义的全量更新方法 int rows baseMapper.alwaysUpdateById(user); // 注意此方法需要实体对象包含正确的 tenant_id否则多租户SQL会失败 // 更安全的做法是先查询出这个用户实体再设置remark为null然后更新。 // User dbUser getById(userId); // dbUser.setRemark(null); // int rows baseMapper.alwaysUpdateById(dbUser); return rows 0; } Override public boolean deactivateUsersByCondition(LocalDateTime beforeTime) { // 构建条件注册时间早于 beforeTime 的用户 LambdaQueryWrapperUser wrapper Wrappers.UserlambdaQuery() .lt(User::getCreateTime, beforeTime); // 使用自定义的按条件更新字段方法将 status 字段更新为 0 (禁用) // 注意column参数必须严格控制这里用硬编码或枚举 int rows baseMapper.updateColumnByWrapper(wrapper, status, 0); // 在多租户环境下必须在wrapper里加上租户条件否则会操作所有租户的数据 // wrapper.eq(User::getTenantId, TenantContext.getCurrentTenantId()); return rows 0; } }使用心得与陷阱事务管理批量操作务必放在Transactional事务中保证数据一致性。数据安全像updateColumnByWrapper这样的方法非常强大但也非常危险。必须在业务层严格校验传入的column参数最好使用预定义的枚举。永远不要将前端传来的字符串直接作为列名使用。多租户上下文在 Service 方法中只要涉及到数据库操作就必须时刻清楚当前的租户上下文。在构建Wrapper或准备实体对象时要确保租户ID被正确设置或包含。对于查询操作MP 的插件会自动追加条件但对于我们手写 SQL 的自定义方法这个责任就落到了我们开发者肩上。性能考量alwaysUpdateById是全字段更新可能会产生不必要的网络传输和数据库日志开销。如果只是更新少量字段使用默认的updateById配合TableField(updateStrategy FieldStrategy.IGNORED)注解是更优选择。7. 常见问题排查与进阶技巧在实际使用中你可能会遇到以下问题问题1自定义方法调用后报错 “Invalid bound statement (not found): ...”原因这是最常见的问题意味着 MyBatis 找不到该 Mapper 接口方法对应的 SQL 语句。排查检查 Mapper XML 文件中的namespace是否与 Mapper 接口的全限定名完全一致。检查 XML 中 SQL 语句的id是否与方法名完全一致。检查你的项目构建工具Maven/Gradle是否将 XML 文件正确复制到了target/classes或输出目录。确保application.yml中mybatis-plus.mapper-locations配置的路径能扫描到你的 XML 文件。问题2多租户插件对自定义 SQL 不生效导致数据泄露或误操作。原因如前所述插件只拦截 MP 自动生成的 SQL。解决方案方案A推荐在所有自定义的 DML SQL 中手动添加AND tenant_id #{tenantId}条件。需要将当前租户ID作为方法参数传入或通过ThreadLocal在 SQL 解析时获取。方案B放弃在复杂自定义 SQL 中直接操作多租户表。改为通过调用 MP 的标准方法如update(wrapper)或组合多个标准操作来实现业务逻辑从而享受插件的自动过滤。虽然可能效率稍低但安全性大大提升。问题3自定义的批量插入方法在数据库不支持 INSERT IGNORE 或 ON CONFLICT 时怎么办解决方案实现“批量插入-更新”逻辑。可以先根据唯一键查询出已存在的记录然后将列表分为“需插入”和“需更新”两部分分别处理。或者使用 MP 自带的saveOrUpdateBatch方法Service 层但它本质上是循环判断并非真正的批量 SQL。进阶技巧使用 MP 的SqlInjector进行全局方法注入如果你有一个自定义方法其 SQL 逻辑是通用的、可以动态生成的例如一个根据主键批量查询的方法selectBatchIds其实 MP 已经提供了你可以通过实现SqlInjector接口将这个方法像 MP 内置方法一样注入到所有的MyBaseMapper中而无需在每个实体的 XML 里写重复的 SQL。但这涉及更底层的 MP 扩展机制复杂度较高。对于大多数业务场景在 XML 中编写明确的自定义 SQL 更加直观和可控。当你真的有大量 Mapper 需要某个完全相同的自定义方法时再考虑使用SqlInjector进行优化。自定义BaseMapper是 MyBatis-Plus 进阶使用的标志。它要求你不仅会使用框架还要理解其运行原理并能与之协同工作。这个过程肯定会遇到坑但每解决一个你对数据访问层的掌控力就增强一分。记住任何强大的工具都是双刃剑自定义带来的灵活性也伴随着额外的复杂性和维护成本。在设计每一个自定义方法前都问问自己这个功能是否真的通用是否可以通过其他更简单的方式如 Service 组合、字段注解实现想清楚了再动手你的代码库会因此更加健壮和优雅。