MyBatis-Plus联合主键处理：从原理到实战解决方案

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) { QueryWrapper<UserRole> wrapper = new QueryWrapper<>(); wrapper.eq("user_id", userId) .eq("role_id", roleId); return userRoleMapper.selectOne(wrapper); // 或者使用LambdaWrapper，避免字段名硬编码 // LambdaQueryWrapper<UserRole> lambdaWrapper = new LambdaQueryWrapper<>(); // lambdaWrapper.eq(UserRole::getUserId, userId).eq(UserRole::getRoleId, roleId); } public boolean deleteByCompositeKey(Long userId, Long roleId) { QueryWrapper<UserRole> 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); UpdateWrapper<UserRole> 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) { LambdaQueryWrapper<UserRole> 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需要更新的字段 UpdateWrapper<UserRole> 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

这是最复杂的一步。你需要：

1. 创建一个自定义的BaseMapper接口，继承MP的BaseMapper，并声明针对联合主键的方法，例如：

   public interface CompositeKeyBaseMapper<T> extends BaseMapper<T> { // 根据联合主键查询 T selectByCompositeKey(@Param("et") T entity); // 根据联合主键更新（选择性更新） int updateByCompositeKey(@Param("et") T entity); // 根据联合主键删除 int deleteByCompositeKey(@Param("et") T entity); }

2. 实现这个接口的默认方法。这需要你编写一个CompositeKeySqlInjector，在MP启动时，将这些自定义方法的SQL模板注入到Mapper中。SQL模板需要能根据实体类上的@CompositeKey注解动态生成WHERE key1=? AND key2=?的条件。
3. 让你的业务Mapper继承这个自定义的CompositeKeyBaseMapper。

这个过程涉及对MP内部接口AbstractMethod、SqlMethod、TableInfo的扩展和反射操作，代码量较大且容易出错。它要求开发者对MP的源码有较深的理解。一个更轻量、更常见的折中方案是：不为所有联合主键表做全局注入，而是为某个特定的实体Mapper编写自定义的XML映射文件或@Select、@Update注解。

例如，在UserRoleMapper.xml中：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd"> <mapper namespace="com.example.mapper.UserRoleMapper"> <!-- 通用查询映射结果 --> <resultMap id="BaseResultMap" type="com.example.entity.UserRole"> <result column="user_id" property="userId" /> <result column="role_id" property="roleId" /> <result column="assign_time" property="assignTime" /> </resultMap> <!-- 根据联合主键查询 --> <select id="selectByCompositeKey" resultMap="BaseResultMap"> SELECT * FROM sys_user_role WHERE user_id = #{userId} AND role_id = #{roleId} </select> <!-- 根据联合主键更新（动态更新非空字段） --> <update id="updateByCompositeKey"> UPDATE sys_user_role <set> <if test="assignTime != null"> assign_time = #{assignTime}, </if> </set> WHERE user_id = #{userId} AND role_id = #{roleId} </update> </mapper>

然后在UserRoleMapper接口中声明这些方法：

public interface UserRoleMapper extends BaseMapper<UserRole> { UserRole selectByCompositeKey(@Param("userId") Long userId, @Param("roleId") Long roleId); int updateByCompositeKey(UserRole userRole); }

这种方式比全局注入器简单，针对性更强，但每个联合主键表都需要单独编写XML和接口方法，也有一定的重复工作。

5. 解决方案三：审视设计，能否避免联合主键？

在寻找技术解决方案的同时，我们也应该回过头来审视一下数据库设计：这张表真的必须使用联合主键吗？

联合主键会带来一些额外的复杂度：

1. 索引开销：InnoDB中，主键就是聚簇索引。联合主键会导致索引长度增加，可能影响插入性能和存储空间。
2. 外键引用：如果其他表需要外键关联到这张表，外键也必须引用所有的主键列，这会让关联关系变得复杂。
3. ORM适配：正如我们遇到的，大多数ORM框架对联合主键的支持都不如单主键那么友好和高效。

一个常见的、更优的替代方案是：使用一个独立的、无业务意义的自增ID（或分布式ID）作为代理主键（Surrogate Key），同时将原本计划作为联合主键的多个字段设置为唯一约束（UNIQUE KEY）。

改造后的UserRole表设计如下：

• idBIGINT PRIMARY KEY AUTO_INCREMENT (或使用雪花算法ID)
• user_idBIGINT NOT NULL
• role_idBIGINT NOT NULL
• assign_timeDATETIME
• UNIQUE 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的便捷API（selectById,updateById,saveOrUpdate）都可以直接使用，因为主键又变回了单一的id字段。而业务上要求的“一个用户不能重复分配同一个角色”的规则，由数据库层的唯一索引uk_user_role来保证，与主键解耦。

这个方案的优点是彻底解决了ORM层面的适配问题，让代码变得简洁，并且通常更符合大多数ORM框架的最佳实践。缺点是需要修改现有表结构，如果已有大量数据或外部系统依赖原主键结构，迁移成本会很高。此外，多了一个字段，在查询时如果WHERE条件用的是user_id和role_id，需要额外注意索引的使用，确保uk_user_role索引能被有效利用。

6. 实战中的决策与经验总结

面对MyBatis-Plus的联合主键问题，没有银弹。选择哪种方案，取决于你的项目阶段、团队技术栈和具体的业务上下文。

对于新项目或允许改动的老项目，我强烈推荐方案三（使用代理主键）。一劳永逸地避免后续所有因联合主键带来的开发效率问题和潜在隐患，从长远看，收益远大于初期改表的成本。这也是为什么在现代Web应用开发中，使用无业务意义的代理主键几乎成为一种默认的规范。

对于无法修改表结构的遗留系统，方案一（手动Wrapper）是最安全、最推荐的做法。它不引入任何黑魔法，代码意图清晰，任何接手项目的开发者都能一眼看懂。你可以通过抽取工具方法或基类Service来减少Wrapper构建的重复代码。例如，创建一个BaseService<Entity, 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的设计边界，根据实际情况选择最合适的应对策略，是我们从“会用”到“用好”这样一个强大工具的关键一步。