1. 联合主键的“坑”与MyBatis-Plus的“默认”逻辑最近在重构一个老项目的数据库层遇到了一个典型的“历史遗留”问题一张业务表使用了联合主键。当我信心满满地引入MyBatis-Plus以下简称MP准备大干一场时却发现updateById、deleteById这些我平时用得最顺手的API要么报错要么行为诡异。这让我意识到MP虽然极大地简化了单主键场景下的CRUD但在联合主键面前它的“默认”逻辑就有点不够用了。如果你也正被TableId只能标注一个字段、LambdaUpdateWrapper的eq方法对多个主键字段束手无策等问题困扰那么这篇踩坑与解决方案的总结或许能帮你少走弯路。联合主键在业务设计中并不少见尤其是在需要唯一标识一条记录但单个字段又无法满足唯一性约束的场景下比如“用户-角色”关联表、“订单-商品”明细表等。MP的核心设计哲学是“约定优于配置”其内置的通用Mapper如BaseMapper和Service层封装默认认准了一个名为id的字段或者通过TableId注解指定的单个字段作为主键。当实体类中存在多个主键字段时MP的默认机制就失效了因为它无法确定用哪个字段、或者如何组合这些字段来唯一锁定一条记录。这直接导致所有基于id的操作包括selectById、updateById、deleteById以及saveOrUpdate等便捷方法都无法直接使用。网络上搜索“mybatis-plus updatebatchbyid没数据修改也返回成功”这类问题其根源很可能就是主键映射不明确导致MP生成的WHERE条件无法正确匹配到数据。2. 问题根因MP的ORM映射与SQL生成机制剖析要解决问题首先得理解MP是如何工作的。MP在启动时会解析你的实体类构建一个TableInfo对象这个对象包含了表名、字段映射关系以及最关键的主键信息。对于单主键TableInfo中会明确记录主键的字段名keyColumn和属性名keyProperty。当执行updateById(entity)时MP会做两件事1. 从entity对象中取出主键属性值2. 将其作为WHERE条件WHERE id ?拼接到更新语句中。当你的实体类拥有多个主键字段时问题就来了。MP的TableInfo逻辑默认只支持一个主键。即使你在多个字段上加了TableId实际上这么做会出问题或者在数据库中将多个字段设为主键MP的元数据解析器在构建TableInfo时通常只会识别第一个被扫描到的TableId字段或者干脆无法正确构建多主键信息。这就导致了TableInfo中的主键信息是残缺或不正确的。以updateById为例其内部调用链最终会走到SqlMethod.UPDATE_BY_ID对应的SQL模板。这个模板是固定的UPDATE table_name SET ... WHERE key_column ?。这里的key_column是单数。MP无法自动将这个模板扩展为WHERE column1 ? AND column2 ?。因此当它试图用单个主键值去生成SQL时要么抛出异常如果主键配置混乱要么生成错误的SQL如只用了其中一个字段做条件这就是为什么会出现“没数据修改也返回成功”的诡异现象——因为WHERE条件可能只匹配了部分字段意外地匹配到了多条记录或者根本一条都没匹配到但MP的默认逻辑可能返回受影响行数为0在某些封装下被解读为“成功”。另一个常见的问题是使用QueryWrapper或UpdateWrapper的eq方法进行精确查询或更新。对于联合主键查询我们需要在Wrapper中连续调用eq来拼接多个条件。这本身没问题但很多开发者会尝试用Lambda表达式直接引用实体类的属性却发现当多个属性都是“主键”时缺乏一种标准、简洁的方式来构建这个多条件组合。他们可能会错误地认为MP应该提供一个像eqId()这样的多参数方法但MP并没有因为它的核心设计并未将联合主键作为一等公民支持。3. 解决方案一放弃“捷径”回归手动Wrapper构建这是最直接、最可控也最符合MP当前设计哲学的方案。既然MP的“ById”系列捷径走不通那我们就不走。对于任何需要操作联合主键记录的地方都明确地使用QueryWrapper或UpdateWrapper来构建完整的WHERE条件。3.1 精确查询与删除操作假设我们有一个UserRole实体联合主键是userId和roleId。// 实体类注意这里没有使用 TableId Data TableName(sys_user_role) public class UserRole { private Long userId; // 联合主键字段1 private Long roleId; // 联合主键字段2 private LocalDateTime assignTime; }要查询或删除一条特定的用户-角色关联记录可以这样做Service public class UserRoleService { Autowired private UserRoleMapper userRoleMapper; public UserRole getByCompositeKey(Long userId, Long roleId) { QueryWrapperUserRole wrapper new QueryWrapper(); wrapper.eq(user_id, userId) .eq(role_id, roleId); return userRoleMapper.selectOne(wrapper); // 或者使用LambdaWrapper避免字段名硬编码 // LambdaQueryWrapperUserRole lambdaWrapper new LambdaQueryWrapper(); // lambdaWrapper.eq(UserRole::getUserId, userId).eq(UserRole::getRoleId, roleId); } public boolean deleteByCompositeKey(Long userId, Long roleId) { QueryWrapperUserRole wrapper new QueryWrapper(); wrapper.eq(user_id, userId) .eq(role_id, roleId); int rows userRoleMapper.delete(wrapper); return rows 0; } }3.2 更新操作更新操作需要特别注意你不能用updateById而应该用update(entity, wrapper)方法。public boolean updateUserRoleTime(Long userId, Long roleId, LocalDateTime newTime) { UserRole updateEntity new UserRole(); updateEntity.setAssignTime(newTime); UpdateWrapperUserRole wrapper new UpdateWrapper(); wrapper.eq(user_id, userId) .eq(role_id, roleId); int rows userRoleMapper.update(updateEntity, wrapper); return rows 0; }注意这里传入的updateEntity只包含了要更新的字段assignTime主键字段userId和roleId是放在Wrapper里作为条件的。千万不要把主键字段也set到updateEntity中否则在极少数配置下MP可能会将其误认为需要更新的列。3.3 插入与“保存或更新”插入操作insert不受影响直接传入完整实体对象即可。麻烦的是saveOrUpdate这个便捷方法。它内部会先判断实体主键是否存在对于联合主键MP无法做出正确判断。因此我们需要手动实现这个逻辑public boolean saveOrUpdateUserRole(UserRole userRole) { LambdaQueryWrapperUserRole wrapper new LambdaQueryWrapper(); wrapper.eq(UserRole::getUserId, userRole.getUserId()) .eq(UserRole::getRoleId, userRole.getRoleId()); Long count userRoleMapper.selectCount(wrapper); if (count 0) { // 存在则更新 UserRole updateEntity new UserRole(); updateEntity.setAssignTime(userRole.getAssignTime()); // 只set需要更新的字段 UpdateWrapperUserRole updateWrapper new UpdateWrapper(); updateWrapper.eq(user_id, userRole.getUserId()) .eq(role_id, userRole.getRoleId()); return userRoleMapper.update(updateEntity, updateWrapper) 0; } else { // 不存在则新增 return userRoleMapper.insert(userRole) 0; } }这个方案的优点是简单明了无需任何额外配置或依赖完全在MP现有能力范围内。缺点就是代码稍显繁琐特别是在需要频繁操作联合主键表的地方会有很多重复构建Wrapper的代码。为了改善这一点可以在Service层或一个专门的Helper类中封装一个构建联合主键Wrapper的通用方法。4. 解决方案二自定义全局SQL注入器与通用Mapper如果你追求更高的开发效率希望在整个项目中对联合主键表也能使用类似selectById的语义那么可以考虑深度定制MP。这需要你理解MP的SQL注入机制并编写一些扩展代码。核心思路是自定义一个SqlInjector为你的联合主键实体Mapper注入处理多主键的SQL方法。4.1 定义联合主键注解首先我们可以创建一个注解来标记联合主键字段。Documented Retention(RetentionPolicy.RUNTIME) Target({ElementType.FIELD}) public interface CompositeKey { // 可以设置顺序用于决定主键字段在SQL中的顺序 int order() default 0; }4.2 改造实体类在实体类中使用这个注解并移除MP原生的TableId。Data TableName(sys_user_role) public class UserRole { CompositeKey(order 1) private Long userId; CompositeKey(order 2) private Long roleId; private LocalDateTime assignTime; }4.3 自定义SQL注入器与Mapper这是最复杂的一步。你需要创建一个自定义的BaseMapper接口继承MP的BaseMapper并声明针对联合主键的方法例如public interface CompositeKeyBaseMapperT extends BaseMapperT { // 根据联合主键查询 T selectByCompositeKey(Param(et) T entity); // 根据联合主键更新选择性更新 int updateByCompositeKey(Param(et) T entity); // 根据联合主键删除 int deleteByCompositeKey(Param(et) T entity); }实现这个接口的默认方法。这需要你编写一个CompositeKeySqlInjector在MP启动时将这些自定义方法的SQL模板注入到Mapper中。SQL模板需要能根据实体类上的CompositeKey注解动态生成WHERE key1? AND key2?的条件。让你的业务Mapper继承这个自定义的CompositeKeyBaseMapper。这个过程涉及对MP内部接口AbstractMethod、SqlMethod、TableInfo的扩展和反射操作代码量较大且容易出错。它要求开发者对MP的源码有较深的理解。一个更轻量、更常见的折中方案是不为所有联合主键表做全局注入而是为某个特定的实体Mapper编写自定义的XML映射文件或Select、Update注解。例如在UserRoleMapper.xml中?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.example.mapper.UserRoleMapper !-- 通用查询映射结果 -- resultMap idBaseResultMap typecom.example.entity.UserRole result columnuser_id propertyuserId / result columnrole_id propertyroleId / result columnassign_time propertyassignTime / /resultMap !-- 根据联合主键查询 -- select idselectByCompositeKey resultMapBaseResultMap SELECT * FROM sys_user_role WHERE user_id #{userId} AND role_id #{roleId} /select !-- 根据联合主键更新动态更新非空字段 -- update idupdateByCompositeKey UPDATE sys_user_role set if testassignTime ! null assign_time #{assignTime}, /if /set WHERE user_id #{userId} AND role_id #{roleId} /update /mapper然后在UserRoleMapper接口中声明这些方法public interface UserRoleMapper extends BaseMapperUserRole { UserRole selectByCompositeKey(Param(userId) Long userId, Param(roleId) Long roleId); int updateByCompositeKey(UserRole userRole); }这种方式比全局注入器简单针对性更强但每个联合主键表都需要单独编写XML和接口方法也有一定的重复工作。5. 解决方案三审视设计能否避免联合主键在寻找技术解决方案的同时我们也应该回过头来审视一下数据库设计这张表真的必须使用联合主键吗联合主键会带来一些额外的复杂度索引开销InnoDB中主键就是聚簇索引。联合主键会导致索引长度增加可能影响插入性能和存储空间。外键引用如果其他表需要外键关联到这张表外键也必须引用所有的主键列这会让关联关系变得复杂。ORM适配正如我们遇到的大多数ORM框架对联合主键的支持都不如单主键那么友好和高效。一个常见的、更优的替代方案是使用一个独立的、无业务意义的自增ID或分布式ID作为代理主键Surrogate Key同时将原本计划作为联合主键的多个字段设置为唯一约束UNIQUE KEY。改造后的UserRole表设计如下idBIGINT PRIMARY KEY AUTO_INCREMENT (或使用雪花算法ID)user_idBIGINT NOT NULLrole_idBIGINT NOT NULLassign_timeDATETIMEUNIQUE KEYuk_user_role(user_id,role_id) -- 业务唯一性约束实体类也随之改变Data TableName(sys_user_role) public class UserRole { TableId(type IdType.AUTO) // 或者 IdType.ASSIGN_ID private Long id; // 代理主键 private Long userId; private Long roleId; private LocalDateTime assignTime; }这样改造后所有MP的便捷APIselectById,updateById,saveOrUpdate都可以直接使用因为主键又变回了单一的id字段。而业务上要求的“一个用户不能重复分配同一个角色”的规则由数据库层的唯一索引uk_user_role来保证与主键解耦。这个方案的优点是彻底解决了ORM层面的适配问题让代码变得简洁并且通常更符合大多数ORM框架的最佳实践。缺点是需要修改现有表结构如果已有大量数据或外部系统依赖原主键结构迁移成本会很高。此外多了一个字段在查询时如果WHERE条件用的是user_id和role_id需要额外注意索引的使用确保uk_user_role索引能被有效利用。6. 实战中的决策与经验总结面对MyBatis-Plus的联合主键问题没有银弹。选择哪种方案取决于你的项目阶段、团队技术栈和具体的业务上下文。对于新项目或允许改动的老项目我强烈推荐方案三使用代理主键。一劳永逸地避免后续所有因联合主键带来的开发效率问题和潜在隐患从长远看收益远大于初期改表的成本。这也是为什么在现代Web应用开发中使用无业务意义的代理主键几乎成为一种默认的规范。对于无法修改表结构的遗留系统方案一手动Wrapper是最安全、最推荐的做法。它不引入任何黑魔法代码意图清晰任何接手项目的开发者都能一眼看懂。你可以通过抽取工具方法或基类Service来减少Wrapper构建的重复代码。例如创建一个BaseServiceEntity, Key其中Key是一个包含所有主键字段的类然后提供getWrapperByKey(Key key)这样的抽象方法。方案二自定义注入器适用于框架深度定制团队或极其追求Mapper层简洁性的场景。它技术难度最高维护成本也高一旦MP版本升级你的自定义注入器可能需要调整。如果决定采用务必编写详尽的文档和单元测试。最后分享一个我实际遇到的坑在采用方案一手动Wrapper进行批量更新时我最初使用了UpdateWrapper的setSql方法进行字段自增类似于wrapper.setSql(“count count 1”)。但在一个高并发场景下出现了数据错乱。排查后发现是因为多个线程同时构建了相似的Wrapper但MP的Wrapper在某些情况下存在线程共享的风险特别是复用Wrapper对象时。最佳实践是在Service方法内部每次需要Wrapper时都new一个新的对象绝不将其作为类成员变量或跨方法参数复用。对于简单的等值条件使用LambdaQueryWrapper和LambdaUpdateWrapper不仅能避免字段名硬编码其链式调用也天然是线程安全的。联合主键问题就像一面镜子照出了ORM框架的便捷性与数据库设计复杂性之间的权衡。理解MP的设计边界根据实际情况选择最合适的应对策略是我们从“会用”到“用好”这样一个强大工具的关键一步。