MyBatis-Plus updateById 空值不更新与更新无效的深度解析

1. 一个让无数人半夜爬起来改代码的“幽灵Bug”

如果你用 MyBatis-Plus 做过项目，大概率遇到过这种让人抓狂的场景：前端传过来一个对象，用户把某个字段清空了，你信心满满地调用updateById，结果数据库里那个字段纹丝不动，还是老值。你以为是前端没传，抓包一看，字段明明在，值就是null或者空字符串。再或者，你明明在实体类里改了字段值，updateById执行完返回true，可数据库里那列就是没变，仿佛这个方法在跟你玩“假装更新”的游戏。

这两个问题——空值不更新和更新字段无效——是 MyBatis-Plus 使用频率最高的updateById方法上最经典的两类坑。它们不是框架的 Bug，而是框架默认策略和开发者预期之间的错位。前者源于 MyBatis-Plus 对null值的默认忽略策略，后者则牵扯到字段填充、主键识别、SQL 生成逻辑、甚至实体类映射等一系列环节。很多新手被卡住之后，上网搜一圈，抄一段@TableField(updateStrategy = FieldStrategy.IGNORED)贴上去，问题看似解决了，但下次换个场景又翻车，因为根本没搞懂背后的机制。

这篇内容就是把这个方法彻底拆开讲清楚。我会从默认策略的设计动机讲起，把“为什么不更新空值”这件事的来龙去脉说明白，然后给出几种不同场景下的正确解法，再重点拆解“更新字段无效”这个更隐蔽的问题——它可能由七八种完全不同的原因导致，每一种的排查路径和修复方式都不一样。不管你是刚接触 MyBatis-Plus 的新手，还是用了两三年但一直靠“抄配置”过日子的老手，看完之后应该都能对updateById的行为有一个确定性的掌控，而不是靠猜。

2.updateById为什么默认“无视”你的 null 值

2.1 框架的默认策略：NOT_NULL 不是 Bug，是刻意设计

MyBatis-Plus 在生成UPDATE语句时，默认采用的字段更新策略是FieldStrategy.NOT_NULL。这个策略的含义很直白：只有字段值不为null时，才会把该字段拼接到SET子句中。也就是说，如果你传进去的对象里name字段是null，生成的 SQL 里压根不会出现name = ?这一段。

很多人第一次遇到时觉得这是框架在“吞”自己的数据，但从框架设计角度看，这个默认值是有充分理由的。在实际业务中，我们经常做“部分更新”——比如一个用户对象有二十个字段，前端只提交了其中三个修改过的字段，其余字段没传。如果框架把所有null字段都拼进SET子句，那数据库里另外十七个字段就会被全部清空。这种“误伤”在生产环境里是灾难性的。所以NOT_NULL策略本质上是一种保护机制，防止部分更新场景下意外覆盖未提交的字段。

理解了这个设计动机，你就不会再把“空值不更新”当成 Bug 来骂了。它是一个需要你根据业务场景主动选择的策略，而不是框架替你做的错误决定。

2.2 全局策略与局部策略的优先级关系

MyBatis-Plus 允许你在两个层级配置字段更新策略：全局配置和字段级注解。全局配置写在配置文件里：

mybatis-plus: global-config: db-config: update-strategy: not_null

字段级则通过@TableField注解覆盖：

@TableField(updateStrategy = FieldStrategy.IGNORED) private String nickname;

优先级规则很简单：字段级注解 > 全局配置 > 框架默认值。这里有个容易踩的细节——FieldStrategy枚举在不同版本里名字有变化。较早的版本用IGNORED表示“忽略判断，始终拼接”，后来改成了ALWAYS，同时NOT_NULL在某些版本里对应NOT_NULL，在另一些版本里叫DEFAULT。如果你从网上抄的配置编译不过，先检查一下你用的 MyBatis-Plus 版本，别急着怀疑自己写错了。

提示：升级 MyBatis-Plus 大版本时，务必检查FieldStrategy相关枚举的变更，这是版本升级中最容易引发“更新行为突变”的地方之一。

2.3 空字符串和 null 是两回事，别混为一谈

这里必须单独拎出来说一个高频误区。NOT_NULL策略只判断null，不判断空字符串。也就是说，如果前端传过来的是""（空字符串），字段值不为null，框架会正常把它拼进SET子句，数据库里该字段会被更新成空字符串。所以“空值不更新”这个说法其实不准确——准确的说法是“null值不更新”。

这个区别在实际业务里非常关键。比如用户清空了一个备注字段，前端可能传""也可能传null，取决于前端框架和序列化配置。如果你的业务要求“清空即置空”，那你要么统一前端传""，要么把策略改成IGNORED并接受null覆盖的风险。我见过不少项目在这两种值之间来回摇摆，导致同一个清空操作有时生效有时不生效，排查半天才发现是前端不同页面的传值方式不一致。

3. 让 null 值也能更新进去的四种做法及适用边界

3.1 字段级注解：精准打击，推荐首选

最推荐的方式是在需要允许null更新的字段上单独加注解：

@TableField(updateStrategy = FieldStrategy.IGNORED) private String email;

这样只有email这一个字段会忽略null判断，其他字段仍然保持NOT_NULL的保护。这种做法的好处是影响范围可控，你清楚地知道哪些字段允许被置空，哪些不允许。在一个几十个字段的实体里，通常真正需要“允许置空”的字段就那么几个，比如备注、描述、可选的关联 ID 等，用字段级注解精确控制是最稳妥的。

需要注意的是，加了IGNORED之后，这个字段在所有updateById调用中都会无视null判断。如果你的业务里存在“部分更新”和“全量更新”混用同一个实体的场景，就要小心了——部分更新时如果这个字段没传值（为null），它会被意外清空。这种情况下，字段级注解就不够用了，得考虑下面要说的UpdateWrapper方案。

3.2 全局策略调整：省事但风险高

把全局策略改成IGNORED：

mybatis-plus: global-config: db-config: update-strategy: ignored

一行配置解决所有字段的空值更新问题，看起来很美。但我个人在实际项目中很少这么干，原因很简单：它把保护机制整个拆掉了。一旦全局生效，任何一次updateById调用中，实体里所有为null的字段都会被写进数据库。如果你的代码里存在“查出来改两个字段再存回去”的写法，而查出来的对象某些字段本来就是null，那没问题；但如果是“new 一个对象只 set 了主键和要改的字段”，那其余字段全会被清空。这种事故一旦发生，恢复数据非常麻烦。

全局策略适合那种实体字段全部必填、不存在部分更新场景的项目。如果你的业务确实是这样，那全局改掉也无妨。但只要项目里存在部分更新的用法，就别碰全局配置。

3.3UpdateWrapper显式 set：最灵活但最啰嗦

当你需要精确控制某一次更新中哪些字段被置空时，UpdateWrapper是最可靠的手段：

UpdateWrapper<User> wrapper = new UpdateWrapper<>(); wrapper.eq("id", user.getId()) .set("email", null) .set("nickname", user.getNickname()); userMapper.update(null, wrapper);

这种写法完全绕开了实体字段策略的判断逻辑，你set什么就更新什么，set成null就写null。缺点是字段多了之后代码很长，而且字段名是硬编码的字符串，重构时容易漏改。我通常只在“需要把某几个字段显式置空”这种特定场景下用它，日常更新还是走实体方式。

3.4 自定义 SQL：终极兜底方案

如果上面几种方式都不适用，比如更新逻辑涉及复杂的条件判断或多表关联，那就直接在 Mapper 里写自定义 SQL：

@Update("UPDATE user SET email = #{email}, nickname = #{nickname} WHERE id = #{id}") int updateUserFields(@Param("id") Long id, @Param("email") String email, @Param("nickname") String nickname);

自定义 SQL 的好处是完全透明，你写什么就是什么，没有任何框架策略在中间做判断。代价是失去了 MyBatis-Plus 自动生成 SQL 的便利性，字段增减时要手动维护 SQL。适合更新逻辑稳定、字段不多的场景。

把这四种方式放在一起对比一下：

4. 更新字段无效：一个症状背后的七种病因

“空值不更新”至少还有明确的策略解释，而“更新字段无效”才是真正让人抓狂的问题——方法返回成功，SQL 也执行了，但数据就是没变。这个症状背后可能藏着完全不同的原因，我按排查优先级从高到低逐个拆解。

4.1 主键没值或主键值不对：最常见的低级错误

updateById的核心逻辑是根据主键生成WHERE id = ?条件。如果实体对象的主键字段是null，MyBatis-Plus 会直接抛出异常或者生成一条WHERE id = null的 SQL，更新零行。更隐蔽的情况是主键值不对——比如前端传了个字符串"123"，后端字段是Long，类型转换后可能变成别的值，或者前端传了0，而数据库里根本没有id = 0的记录。

排查方法很直接：在调用updateById之前把主键值打印出来，和数据库里的实际主键比对。另外检查实体类主键字段是否标注了@TableId，且type配置正确。如果主键是自增的，type = IdType.AUTO；如果是手动赋值或雪花算法，对应配置不同。主键识别错了，WHERE条件就是错的，更新自然无效。

4.2 实体类字段与数据库列名映射错位

MyBatis-Plus 默认开启驼峰转下划线映射，userName对应user_name。但如果你的数据库列名不符合这个规则，比如列名是username（没有下划线），而实体字段是userName，默认映射就会找不到对应列，生成的 SQL 里可能压根不包含这个字段，或者映射到错误的列上。

这种情况的典型表现是：某些字段能更新，某些不能，而且不能更新的字段有规律——通常是命名不符合驼峰转下划线规则的。解决办法是在字段上加@TableField("username")显式指定列名，或者在全局配置里调整映射策略。我建议对命名不规范的列一律加显式注解，别依赖默认映射去猜。

4.3 字段策略把非 null 值也“过滤”掉了

这个坑比较反直觉。前面说了NOT_NULL策略只过滤null，但如果你把策略配成了NOT_EMPTY，那空字符串也会被过滤。更极端的情况是配成了某些版本里的NEVER或错误的枚举值，导致字段压根不进SET子句。还有一种情况是字段上同时存在多个策略相关注解，互相覆盖，最终生效的策略和你以为的不一样。

排查时可以把 MyBatis-Plus 的 SQL 日志打开，直接看生成的 SQL 里到底有没有你要更新的字段：

mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

日志里能看到完整的Preparing和Parameters，字段在不在SET子句里一目了然。这是排查所有“更新无效”问题的第一步，先确认 SQL 长什么样，再往下查。

4.4 自动填充处理器覆盖了你的值

很多项目用MetaObjectHandler做自动填充，比如updateTime、updateBy等字段在更新时自动赋值。如果填充逻辑写得有问题，比如在updateFill里把某个业务字段也重新赋值了，那你手动 set 的值就会被覆盖掉。这种问题特别隐蔽，因为你的代码逻辑看起来完全正确，值是在框架层被改掉的。

排查方法是临时注释掉MetaObjectHandler的注册，再执行一次更新，看字段是否恢复正常。如果恢复了，就去检查填充方法里strictUpdateFill或setFieldValByName的调用范围，确认没有误伤业务字段。

4.5 数据库层面：触发器、默认值、字段类型不匹配

SQL 确实执行了，字段也确实在SET子句里，但数据库里的值还是没变——这时候问题可能出在数据库层。常见的情况包括：表上有BEFORE UPDATE触发器，把字段值又改回去了；字段类型和传入值类型不匹配，比如DECIMAL字段传了超出精度范围的值被截断或忽略；字段有ON UPDATE默认值设置，覆盖了显式传入的值。

这类问题排查起来需要直接连数据库看表结构和触发器定义。我遇到过一次，某个字段怎么都更新不了，最后发现是同事加了个触发器做数据同步，把该字段强制回写了。这种问题在应用层怎么查都查不出来，必须下沉到数据库层。

4.6 事务未提交或回滚

更新方法返回true，但换个连接查数据库发现没变——很可能是事务没提交。比如方法上标了@Transactional但抛了异常被吞掉，或者手动管理事务时忘了commit。还有一种情况是更新操作在事务里执行了，但后续逻辑抛异常导致整个事务回滚，你看到方法返回成功，实际上数据已经回滚了。

排查时先确认事务边界，看更新操作所在的方法事务传播行为是否符合预期。可以在更新后立即在同一个事务里查一次，再在事务外查一次，对比结果。

4.7 乐观锁插件导致更新被静默跳过

如果项目里用了 MyBatis-Plus 的乐观锁插件，实体上有@Version字段，那updateById生成的 SQL 会带上WHERE version = ?条件。如果传入的版本号和数据库里的不一致，更新影响行数为零，方法返回false或影响行数为 0，但不会抛异常。很多人看到方法没报错就以为成功了，实际上更新被乐观锁挡掉了。

这种情况的排查方法是看updateById的返回值——它返回的是影响行数，返回 0 就说明没更新到任何记录。养成检查返回值的习惯，能提前发现很多这类静默失败。

把这七种原因整理成排查清单：

5. 把 SQL 日志变成你的听诊器

上面反复提到“看 SQL 日志”，这里单独展开讲一下怎么用好这个工具，因为它是排查所有更新问题的第一手段，没有之一。

5.1 打开日志的正确姿势

在配置文件里加上：

mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

执行一次更新后，控制台会输出类似这样的内容：

==> Preparing: UPDATE user SET nickname=?, email=? WHERE id=? ==> Parameters: 张三(String), null, 1001(Long) <== Updates: 1

从这三行里你能读出大量信息：SET子句里有哪些字段（判断字段是否被策略过滤）、参数值是什么（判断是否被填充覆盖）、WHERE条件是什么（判断主键是否正确）、影响行数是多少（判断是否真的更新到了记录）。基本上前四种病因都能从这三行日志里定位出来。

5.2 从日志反推问题类型的判断逻辑

拿到日志后按这个顺序看：先看WHERE条件，主键对不对；再看SET子句，你要更新的字段在不在里面；再看Parameters，值是不是你预期的值；最后看Updates，影响行数是不是大于零。这四步走完，问题基本就锁定在某个环节了。

如果SET子句里没有目标字段，问题在字段策略或映射；如果字段在但值不对，问题在自动填充或类型转换；如果 SQL 完全正确但Updates为 0，问题在主键、乐观锁或数据库层；如果Updates为 1 但数据没变，问题在事务或触发器。这套判断逻辑我用了很多年，几乎覆盖了所有更新无效的场景。

提示：生产环境不要长期开着StdOutImpl日志，输出量大且包含参数值，有性能和隐私风险。排查问题时临时开启，定位完就关掉。

6. 几个容易忽略的边角场景与实操心得

6.1 批量更新时updateById的循环调用陷阱

有些人图省事，在一个循环里对列表逐条调用updateById。数据量小的时候没问题，数据量一大就是灾难——每条记录一次数据库往返，几千条就是几千次网络开销，性能极差。更麻烦的是如果在事务里循环调用，事务持有时间过长，容易引发行锁竞争。

批量更新的正确做法是用updateBatchById（需要配合IService使用），或者自己拼批量 SQL。如果非要用循环，至少确认循环内的对象主键都正确，并且考虑分批提交控制事务大小。我见过一个项目在循环里更新五千条记录，接口超时三十秒，改成批量后降到两百毫秒。

6.2updateById返回 true 不等于更新成功

updateById的返回值是布尔类型，但它反映的是“方法是否正常执行”，而不是“是否真的更新了数据”。在乐观锁拦截、主键不存在等情况下，方法可能返回true但影响行数为 0。真正可靠的是看影响行数——用baseMapper.updateById(entity)时它返回的是int影响行数，返回 0 就说明没更新到任何记录。

养成检查影响行数的习惯，尤其是在涉及状态流转、库存扣减这类对更新结果敏感的业务里。返回 0 时该抛异常抛异常，该重试重试，别默默忽略。

6.3 实体继承和@TableField(exist = false)的干扰

如果实体类有继承关系，父类字段的映射有时会出问题。另外，标注了@TableField(exist = false)的字段不会参与 SQL 生成，如果你不小心给某个需要更新的字段加了这个注解，它就会被永久排除在更新之外。这种问题在重构时特别容易发生——有人为了临时屏蔽某个字段加了注解，后来忘了删，导致该字段再也更新不了。

排查时检查实体类所有字段的注解，特别是继承来的字段和标了exist = false的字段。我建议对exist = false的使用加注释说明原因，避免后人误删或误加。

6.4 版本升级引发的策略默认值变化

MyBatis-Plus 在不同版本间调整过FieldStrategy的默认值和枚举命名。从 3.1.x 升到 3.4.x 再到 3.5.x，updateStrategy的默认行为和可选值都有变化。升级后如果发现原本正常的更新逻辑突然不更新某些字段了，第一件事就是查版本变更日志里关于FieldStrategy的说明。

我的经验是：升级前把项目里所有@TableField注解和全局策略配置梳理一遍，升级后在测试环境跑一轮覆盖“空值更新”“部分更新”“全量更新”三种场景的用例，确认行为没有意外变化再上生产。

6.5 一个实用的调试小工具：更新前自检

我在项目里封装了一个简单的自检方法，在关键更新操作前调用，能提前拦住大部分低级错误：

public static void checkBeforeUpdate(Object entity) { if (entity == null) { throw new IllegalArgumentException("更新实体不能为空"); } // 反射获取主键值，检查是否为空 // 打印实体所有非空字段，便于比对预期 }

这个工具本身不复杂，价值在于把“更新前检查主键”这个动作固化成习惯。很多更新无效的问题，如果在调用前花两秒钟确认主键有值、字段有值，根本不会发生。

7. 写在最后的一点个人体会

updateById这个方法看起来简单，但它的行为受字段策略、全局配置、注解、自动填充、乐观锁、事务、数据库层等多重因素影响，任何一个环节出问题都会表现为“更新无效”这一个症状。我刚开始用 MyBatis-Plus 的时候，遇到更新问题就上网搜，搜到什么配置就抄什么，结果经常是这个问题解决了，那个问题又冒出来。后来逼着自己把 SQL 日志打开，一条一条看生成的语句，才慢慢建立起“从日志反推病因”的判断能力。

现在我的习惯是：任何更新相关的异常，第一步永远是看 SQL 日志，确认WHERE、SET、Parameters、Updates四个要素，再决定往哪个方向查。这个习惯帮我省掉了大量盲目试错的时间。另外，对于“允许置空”的字段，我一律用字段级注解显式声明，不用全局策略，这样每个字段的行为都是可预期、可追溯的。项目里的实体类字段策略配置，我建议也当成一种“契约”来维护——谁加的注解、为什么加，都留个注释，后面接手的人能少踩很多坑。