MyBatis-Plus乐观锁配置：@Version与拦截器使用教程

MyBatis-Plus 的乐观锁并非仅靠 `@Version` 注解就能自动生效，而是一套需精确协同的机制：必须注册 `MybatisPlusInterceptor` 并显式添加 `OptimisticLockerInnerInterceptor`，配合数值型非空版本字段（如 `Integer`）、数据库列默认值为 0，且仅在 `updateById()` 或带主键条件的 `update(entity, wrapper)` 中触发——任何配置遗漏（如误用已废弃插件、拦截器顺序错误、字段类型不符或使用 LambdaUpdate 直接拼 WHERE）都会导致乐观锁静默失效；更关键的是，失败时抛出的是易被忽略的 `OptimisticLockException`，不返回冲突详情，也无内置重试逻辑，所有业务级容错、版本比对与用户提示都需开发者手动补全，真正考验的是对机制本质的理解与落地细节的把控。

MyBatis-Plus 的 @Version 注解本身不生效——必须配合同名字段 + 乐观锁拦截器，否则并发更新时完全不校验版本号。

为什么加了 @Version 字段却没触发乐观锁？

常见错误是只在实体类上加了 @Version 注解，但没注册 MybatisPlusInterceptor 并添加 OptimisticLockerInnerInterceptor。MyBatis-Plus 不会自动启用乐观锁逻辑，它纯靠拦截器在 SQL 构建阶段注入 WHERE version = #{version} 条件。

• 实体字段类型必须是 Integer、Long 或 AtomicInteger 等可递增数值类型（不能是 String 或 LocalDateTime）
• 数据库对应列建议设为 NOT NULL DEFAULT 0，避免 NULL 导致 WHERE 条件恒假
• Spring Boot 3.x + MyBatis-Plus 3.5.3+ 起，拦截器注册方式有变化，老配置会静默失效

MyBatis-Plus 3.5+ 正确配置乐观锁拦截器

新版拦截器必须通过 MybatisPlusInterceptor 添加，且顺序影响执行（乐观锁需在分页等拦截器之前）。Spring Boot 配置示例如下：

@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
    return interceptor;
}

• 不要用已废弃的 OptimisticLockerPlugin，它在 3.4.4 后被移除
• 如果项目还用了分页插件，OptimisticLockerInnerInterceptor 必须先于 PaginationInnerInterceptor 添加
• 若使用多数据源，每个 SqlSessionFactory 都要单独配置该拦截器

@Version 字段在 update 操作中如何被识别？

MyBatis-Plus 只对 updateById() 和 update(entity, wrapper) 中带主键条件的场景生效；其他如 lambdaUpdate().set() 直接拼 WHERE 的写法，不会自动注入版本检查。

• ✅ 正确：调用 userMapper.updateById(user)，且 user 中 version 字段值非 null
• ❌ 无效：用 lambdaUpdate().eq(User::getId, id).set(User::getName, "x") —— 此时无版本字段参与，乐观锁不触发
• ⚠️ 注意：updateById() 会把当前对象所有非 null 字段作为 SET 子句，但 WHERE 里只加主键和 version，不校验其他字段

并发更新失败后怎么拿到真实原因？

乐观锁失败时抛出 OptimisticLockException，不是常见的 SQLException，容易被全局异常处理器漏捕获。

• 该异常继承自 MybatisPlusException，需显式 catch 或在统一异常处理中匹配 instanceof OptimisticLockException
• 异常 message 通常是 updated 0 row，但不包含被覆盖的原始数据——业务层需自行查库比对最新 version
• 若想返回冲突详情（如“当前版本为 5，你提交的是 3”），得在 service 层先 selectById 再做判断，@Version 机制本身不提供差值信息

真正难的不是加注解或配拦截器，而是理解它只作用于特定 update 入口，且失败后没有内置重试或版本提示逻辑——这些都得自己补全。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~