1. 问题背景与核心机制拆解

updateById这个方法，用过 MyBatis-Plus 的人应该都不陌生。它属于BaseMapper接口里最常用的几个方法之一，日常写业务代码时，改个状态、更新个字段，顺手就是一个updateById。但很多人第一次真正被它“坑”到，往往是在某个需要把字段置空的场景里——比如用户清空了昵称、订单的备注被删掉、某个关联 ID 需要解除绑定。代码跑完没报错，日志也正常，回头一查数据库，那个字段纹丝不动，还是老值。这时候就开始怀疑人生了：我明明set成null了，怎么就没更新？

这个问题的根源，其实不在updateById本身，而在于 MyBatis-Plus 默认的字段更新策略。它默认走的是FieldStrategy.NOT_NULL，翻译成人话就是：实体里为 null 的字段，不参与 SQL 拼接。所以当你把一个字段设成 null 再传给updateById，框架在生成UPDATE语句时直接把这个字段跳过了，SQL 里压根没有它，数据库自然不会有任何变化。这个设计初衷是好的——避免误把没赋值的字段覆盖成 null，但它和“主动置空”这个需求天然冲突。

除了空值不更新，还有一类高频问题：字段明明有值，但更新无效。这种情况通常更隐蔽，可能的原因包括字段名和数据库列名映射不上、@TableField配置有问题、实体主键没设对、或者被全局的更新策略拦截了。这两类问题经常被混为一谈，但排查路径完全不同，得分开看。

这篇文章面向的是已经上手 MyBatis-Plus、正在被更新问题卡住的开发者，不管你用的是 Spring Boot 2.x 还是 3.x，是单表操作还是带条件更新，下面这套拆解和实操方案都能直接对照着用。我会把默认策略的原理讲透，再把几种主流解决方案的适用场景、坑点和参数配置一个个拆开，最后给一份排查速查表，方便你出问题时按图索骥。

1.1 默认更新策略到底做了什么

要理解问题，得先看清楚updateById生成 SQL 的逻辑。MyBatis-Plus 在解析实体时，会遍历所有非静态、非瞬态的字段，对每个字段判断是否满足更新条件。默认策略NOT_NULL的判断逻辑非常直接：字段值不为 null 才纳入 SQL 的SET子句。所以一个实体如果有 10 个字段，你只 set 了 3 个，那生成的 SQL 就只有这 3 个字段的更新，其余 7 个连出现的机会都没有。

这里有个容易误解的点：很多人以为“我没 set 的字段保持原值”是数据库层面的行为，其实不是，是框架在 Java 层就把这些字段过滤掉了，SQL 里根本没有它们。这个区别很重要，因为它决定了你后续所有解决方案的切入点——要么改框架的过滤规则，要么绕过updateById自己写 SQL。

再往深一层，这个策略是可以通过全局配置、注解、以及UpdateWrapper三个层级来覆盖的，优先级从低到高。全局配置影响所有实体，注解影响单个字段，UpdateWrapper影响单次调用。理解这个优先级链条，是选对方案的前提。很多人一上来就改全局配置，结果把整个项目的更新行为都改了，引发一堆意料之外的覆盖问题，这就是没搞清楚作用范围。

1.2 为什么“有值也不更新”是另一码事

空值不更新是策略问题，但有值不更新往往是映射问题。最常见的场景是实体字段名和数据库列名对不上，比如实体叫userName，数据库列叫user_name，如果你没开驼峰映射，或者@TableField没标对，框架生成的 SQL 里列名就是错的，执行时要么报错要么静默失败。还有一种情况是主键没设对，updateById依赖主键定位记录，如果实体的主键字段是 null 或者类型不匹配，生成的WHERE条件就是错的，更新影响行数为 0，但代码不报错。

另外，逻辑删除字段也会干扰更新。如果表里配了逻辑删除，updateById会自动带上deleted = 0的条件，一旦这条记录的删除标记不是预期值，更新就会落空。这类问题排查起来比空值问题更费劲，因为现象都是“没更新”，但根因分散在映射、主键、逻辑删除等多个环节。所以我在实际排查时，第一步永远是打开 SQL 日志，看清楚框架到底生成了什么语句，这一步能砍掉一半的猜测。

2. 空值更新的四种落地方案与选型

搞清楚原理之后，解决方案其实就那么几条路，关键在于根据你的场景选对。我按侵入性从低到高、适用范围从窄到宽，把四种主流方案拆开讲，每种都给出配置方式和适用边界。

2.1 方案一：字段级注解，精准控制单个字段

如果你的需求只是某几个特定字段需要支持置空，最干净的做法是在实体字段上加@TableField注解，把更新策略改成IGNORED或ALWAYS。这两个值的区别在于：IGNORED表示完全忽略判断，字段永远参与 SQL；ALWAYS在较新版本里语义类似，推荐用FieldStrategy.ALWAYS。

public class UserEntity { private Long id; private String userName; @TableField(updateStrategy = FieldStrategy.ALWAYS) private String nickName; @TableField(updateStrategy = FieldStrategy.ALWAYS) private String remark; }

这样配置后，nickName和remark这两个字段无论是否为 null 都会出现在SET子句里。优点是影响范围精确可控，不会波及其他字段；缺点是字段多了要一个个标，而且一旦标了ALWAYS，以后所有updateById调用都会带上这个字段，如果你某次只想更新别的字段、不想动它，它也会被写成 null。这是个双刃剑，得想清楚。

注意：标了ALWAYS的字段，在“只想更新部分字段”的场景下会带来误覆盖风险。比如你只想改状态，结果把没赋值的备注也刷成了 null。所以这个方案适合那些“本来就该整体覆盖”的字段，不适合零散更新的场景。

2.2 方案二：UpdateWrapper 显式 set，绕开实体策略

当你需要“这一次调用把某字段置空”，但又不想改字段的全局策略时，UpdateWrapper是最灵活的选择。它的思路是不依赖实体字段的自动解析，而是手动指定SET内容，框架会原样拼进 SQL。

UpdateWrapper<UserEntity> wrapper = new UpdateWrapper<>(); wrapper.eq("id", 1001L) .set("nick_name", null) .set("remark", null); userMapper.update(null, wrapper);

这里第一个参数传null是有讲究的——传实体的话，框架还会去解析实体字段，可能和你 wrapper 里的 set 冲突。传 null 表示完全以 wrapper 为准。这种方式的控制力最强，想 set 什么就 set 什么，包括 null。缺点是字段名要手写字符串，容易拼错，而且失去了实体映射的便利，重构时不够安全。

我一般在这种场景下用它：一次性的数据清理、后台管理里的“清空某字段”操作、或者批量把某列置空。日常业务更新还是倾向于用实体，可读性更好。

2.3 方案三：全局配置调整，一劳永逸但有代价

如果你整个项目里大量字段都需要支持置空，逐个标注解太累，那可以考虑改全局更新策略。在配置里把update-strategy设成IGNORED或ALWAYS，所有字段的默认行为就变了。

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

这个配置一改，所有updateById都会把所有字段拼进 SQL，null 也照写。听起来很爽，但代价是：你再也没法用“不 set 就不更新”这个便利了。以前你查出一条记录、改一个字段、存回去，没动的字段自动保持原值；现在没动的字段如果是 null，就会被覆盖成 null。这在“先查后改”的经典模式里是灾难性的，很容易把数据刷坏。

所以我的建议很明确：全局配置慎用，除非你的项目更新模式统一是“全量覆盖”，否则老老实实用字段注解或 wrapper。真要用，也建议配合代码评审和充分的测试，别在存量项目上贸然开。

2.4 方案四：自定义 SQL，彻底掌控更新逻辑

当更新逻辑复杂到一定程度——比如要根据条件动态决定哪些字段更新、要配合复杂的WHERE、或者要利用数据库函数——直接写 XML 或注解 SQL 反而最省心。updateById再灵活也是框架封装的，遇到它搞不定的场景，退回到手写 SQL 是明智的。

<update id="updateSelective"> UPDATE user <set> <if test="nickName != null">nick_name = #{nickName},</if> <if test="remark != null">remark = #{remark},</if> <if test="forceClearRemark">remark = null,</if> </set> WHERE id = #{id} </update>

手写 SQL 的好处是逻辑完全透明，想怎么控制就怎么控制，还能针对特定字段做特殊处理。缺点是要自己维护，字段增减时得同步改 SQL，工作量比用框架大。我通常只在核心业务或复杂更新场景下用它，普通 CRUD 还是交给updateById。

2.5 四种方案横向对比

选型的核心判断标准就一条：你的更新是“选择性更新”还是“全量覆盖”。选择性更新占主导的项目，别碰全局配置；全量覆盖为主的项目，全局配置反而省事。搞清楚这一点，方案自然就定了。

3. 实操过程与关键环节实现

光讲方案不够，得把完整操作走一遍。我以一个典型的用户信息更新场景为例，从建表、实体配置到调用、验证，把每一步的关键点和参数选择讲清楚。这个场景包含一个需要支持置空的昵称字段和一个普通字段，正好覆盖两类需求。

3.1 环境与实体准备

先看表结构，假设有一张用户表，包含主键、用户名、昵称、备注、状态几个字段。昵称和备注需要支持置空，状态是普通更新字段。

CREATE TABLE user_info ( id BIGINT PRIMARY KEY, user_name VARCHAR(64), nick_name VARCHAR(64), remark VARCHAR(255), status TINYINT, deleted TINYINT DEFAULT 0 );

实体类对应配置，主键用@TableId标注，需要置空的字段加updateStrategy，逻辑删除字段用@TableLogic。

public class UserInfo { @TableId(type = IdType.ASSIGN_ID) private Long id; private String userName; @TableField(updateStrategy = FieldStrategy.ALWAYS) private String nickName; @TableField(updateStrategy = FieldStrategy.ALWAYS) private String remark; private Integer status; @TableLogic private Integer deleted; }

这里有个细节值得说：@TableId的type选ASSIGN_ID还是AUTO，取决于你的主键生成方式。如果是数据库自增，用AUTO；如果是雪花算法之类的应用层生成，用ASSIGN_ID。这个选错不会直接导致更新失败，但会影响插入时的主键赋值，间接影响后续updateById能否定位到记录。我在实际项目里见过因为主键类型配错，导致updateById的WHERE条件用了错误的值，更新影响行数一直是 0，排查了半天才发现是主键生成策略的问题。

3.2 调用层的关键写法

配置好实体后，调用updateById时要注意实体的构造方式。如果你只想更新昵称为 null，其他字段不动，那实体里只 set id 和 nickName 就行，其他字段保持 null。因为 nickName 标了ALWAYS，它会进 SQL；其他没标的字段是 null，会被过滤掉，正好符合“只更新昵称”的预期。

UserInfo update = new UserInfo(); update.setId(1001L); update.setNickName(null); // 主动置空 userInfoMapper.updateById(update);

生成的 SQL 大致是UPDATE user_info SET nick_name = null WHERE id = 1001 AND deleted = 0。注意deleted = 0是逻辑删除自动带上的，这也是为什么前面说逻辑删除会干扰更新——如果这条记录的deleted不是 0，更新就落空。

如果你要同时更新状态和置空昵称，那就把 status 也 set 上：

UserInfo update = new UserInfo(); update.setId(1001L); update.setNickName(null); update.setStatus(2); userInfoMapper.updateById(update);

这时候 SQL 里会同时有nick_name = null和status = 2，其他字段依然不参与。这就是字段级注解方案的精髓——精确控制哪些字段参与，哪些不参与。

3.3 用 Wrapper 处理一次性置空

如果某个字段没标ALWAYS，但某次调用需要置空，就用UpdateWrapper补位。比如 remark 字段平时是选择性更新，只有后台清理时才置空：

UpdateWrapper<UserInfo> wrapper = new UpdateWrapper<>(); wrapper.eq("id", 1001L) .set("remark", null); userInfoMapper.update(null, wrapper);

这里update的第一个参数传 null，第二个传 wrapper。生成的 SQL 是UPDATE user_info SET remark = null WHERE id = 1001 AND deleted = 0。注意 wrapper 里的eq条件会拼进WHERE，逻辑删除条件依然自动带上。

提示：UpdateWrapper的set方法第一个参数是数据库列名，不是实体字段名。如果你开了驼峰映射，实体nickName对应列nick_name，这里要写列名。写错的话 SQL 会报列不存在，这个错误很直观，但新手容易在字段名和列名之间搞混。

3.4 验证更新是否真正生效

写完代码别急着收工，得验证。最直接的方式是开 SQL 日志，看框架生成的语句是否符合预期。在配置里把 MyBatis 的日志级别调到 debug，或者用 MyBatis-Plus 自带的 SQL 打印。

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

日志里能看到完整的 SQL 和参数，重点看三件事：SET子句里有没有你要置空的字段、WHERE条件里的主键值对不对、有没有意外的逻辑删除条件。这三项都对，更新基本就没问题。如果 SQL 看着对但数据没变，那就要查事务是否提交、数据库连接是否指向了正确的库、以及是否有其他拦截器改写了语句。

我踩过的一个坑是：本地测试时连的是测试库，代码里配置的数据源却指向了另一个环境，SQL 日志显示执行成功，但查的是另一个库，自然看不到变化。这种环境错配的问题，日志里看不出来，只能靠核对数据源配置。所以验证时除了看 SQL，还要确认你查的库和更新的库是同一个。

3.5 批量更新场景的特殊处理

单条更新讲完了，批量更新是另一个高频场景。updateById只能单条，批量得用循环或者updateBatchById。循环调用简单但性能差，数据量大时建议用批量方法。不过批量方法对空值的处理和单条一致，同样受更新策略影响，所以前面的配置依然适用。

List<UserInfo> list = new ArrayList<>(); // 构造多条待更新记录 userInfoService.updateBatchById(list);

批量更新时要注意事务边界，一批数据要么全成功要么全回滚，别出现更新一半的情况。另外批量更新的 SQL 是逐条执行的（除非你用了特定的批量插件），所以性能上别期待太高，数据量特别大时考虑分批处理，每批几百条，避免一次性锁太多行。

4. 常见问题排查与避坑实录

更新问题排查最忌讳瞎猜，得有章法。我把实际项目中遇到的高频问题整理成速查表，配上排查思路和解决方法，出问题时按这个顺序走，基本能定位到根因。

4.1 更新无效问题速查表

这张表里，前两行是最常见的，占了实际问题的八成以上。第三、四行属于“有值不更新”的变种，排查时容易被忽略。最后两行是配置层面的坑，往往在项目初期埋下，后期才爆发。

4.2 三个高频坑的深度拆解

坑一：全局策略一改，选择性更新全乱套。我见过一个项目，为了支持某几个字段置空，直接把全局update-strategy改成了ALWAYS。结果上线后大量“先查后改”的逻辑出问题——查出来的实体某些字段本来就是 null，改完存回去，这些 null 被写进了数据库，把原本有值的字段刷没了。这种数据损坏是静默的，等发现时已经很难追溯。教训就是全局配置的影响面太大，改之前必须评估所有更新路径。

坑二：@TableField标了exist = false导致字段被忽略。这个坑比较隐蔽。有时候为了某个字段不参与数据库映射，会标exist = false，但后来业务需要它参与更新了，注解没去掉，结果这个字段怎么 set 都不进 SQL。排查时看 SQL 日志会发现字段压根没出现，但实体里明明有值。这种问题只能靠仔细核对注解，没有捷径。

坑三：逻辑删除字段类型不匹配。逻辑删除的标记值，实体里是Integer，数据库里是TINYINT，一般没问题。但如果实体里用了Boolean，而数据库里存的是 0/1，某些版本下条件拼接会出问题，导致WHERE deleted = false这种语句在数据库里匹配不到。统一用整型标记，能避开这类兼容性问题。

4.3 独家避坑心得

第一条心得：永远先看 SQL，再改代码。更新不生效时，人的第一反应是改代码逻辑，但十有八九问题出在生成的 SQL 上。开日志看语句，比盲目改代码高效得多。我现在的习惯是，任何更新相关的 bug，第一步就是复现并抓 SQL，看清楚框架到底干了什么。

第二条心得：字段级注解优于全局配置，Wrapper 优于注解。这个优先级是我多年踩坑总结的——控制粒度越细的方案，副作用越小。能用 Wrapper 解决的单次需求，别去动字段注解；能用字段注解解决的，别去动全局配置。每往上一层，影响面就扩大一圈，出问题的代价也更大。

第三条心得：更新前先查一次，确认记录存在且状态符合预期。很多“更新无效”其实是记录本身就不满足更新条件，比如已被逻辑删除、主键不存在。养成更新前先selectById确认的习惯，能省掉大量排查时间。当然这会多一次查询，对性能敏感的场景可以权衡，但在调试阶段这个习惯非常值。

第四条心得：批量更新务必测边界。空列表、单条、大批量、含 null 字段的混合批次，这几种情况都要测。批量更新里只要有一条数据的主键有问题，整批可能都受影响，而且错误信息往往不直观。我习惯在批量更新后校验影响行数，和预期不符就立即告警，别等数据出问题才发现。

4.4 版本差异带来的额外注意点

MyBatis-Plus 不同版本之间，更新策略的默认值和枚举名称有过调整。早期版本用FieldStrategy.IGNORED，新版本推荐ALWAYS，虽然功能类似但语义有细微差别。升级框架版本时，如果项目里大量用了旧枚举，可能出现编译警告甚至行为变化。我的做法是升级前先全局搜索FieldStrategy的使用点，逐个确认语义是否仍然符合预期，别指望升级后行为完全不变。

另外，Spring Boot 3.x 搭配的 MyBatis-Plus 版本对 Jakarta 命名空间有要求，如果依赖版本没对齐，可能出现启动报错或映射失效。这类问题不是更新逻辑本身的错，但会表现为“更新不生效”，排查时容易跑偏。确认依赖版本匹配，是排除环境问题的第一步。

5. 策略选择的决策框架

讲了这么多方案和坑，最后落到怎么选。我给一个简单的决策流程，按这个顺序问自己几个问题，答案自然指向合适的方案。

第一个问题：这个字段是不是几乎每次更新都需要参与？如果是，比如状态字段、更新时间字段，那用字段注解ALWAYS最省事，一劳永逸。如果不是，跳到第二个问题。

第二个问题：置空是常态还是偶发？偶发的话，用UpdateWrapper在需要的时候显式 set，别污染字段的默认策略。常态的话，回到第一个问题的答案，考虑字段注解。

第三个问题：整个项目的更新模式是选择性还是全量？全量覆盖为主的项目，全局配置ALWAYS可以接受；选择性更新为主的项目，坚决别碰全局配置。

第四个问题：更新逻辑是否复杂到框架搞不定？涉及多表、复杂条件、数据库函数时，直接手写 SQL，别硬套updateById。

这个框架的核心逻辑就一句话：控制粒度越细越好，影响面越小越安全。按这个原则选，基本不会出大问题。

5.1 一个真实场景的完整决策演示

假设有个订单系统，订单表有状态、备注、物流单号几个字段。需求是：状态更新是高频操作，备注支持用户清空，物流单号在发货时写入、取消时清空。

按决策框架走：状态字段高频参与更新，标ALWAYS合适，但要注意它每次都会进 SQL，所以更新时必须显式赋值，不能漏。备注字段置空是偶发需求，用UpdateWrapper在清空操作时显式 set null，平时走默认策略。物流单号写入和清空都是明确操作，也用UpdateWrapper控制，避免和状态更新混在一起。

这样配置下来，每个字段的更新行为都清晰可控，不会出现“改状态把备注刷没了”的事故。这个案例说明，同一个实体里不同字段可以用不同策略，没必要一刀切。字段级控制的价值就在这里——按需配置，各管各的。

5.2 监控与回归建议

更新逻辑改完后，建议加一层轻量监控：记录关键更新操作的入参和影响行数，影响行数为 0 时打警告日志。这样线上出问题时能快速定位是哪个调用、什么参数导致的。回归测试时重点覆盖 null 值场景和部分字段更新场景，这两类是问题高发区。

我在实际项目里还养成了一个习惯：任何涉及更新策略的配置变更，都单独提一个变更记录，写清楚改了哪个字段、为什么改、影响哪些调用方。这样后续有人再动这块时，能看到历史决策的来龙去脉，避免重复踩坑。配置这种东西，最怕的就是没人记得当初为什么这么设，然后被后来者随手改掉，引发连锁问题。

这套排查和配置的思路，我在多个项目里反复验证过，从单体应用到微服务拆分后的多数据源场景都适用。核心还是那句话：先看清楚框架生成了什么 SQL，再决定改哪里，别凭感觉调。更新问题看着琐碎，但把策略链条理清楚之后，大部分坑都能提前避开。