MySQL ROW_COUNT 为什么可能返回匹配行数或实际修改行数

执行 UPDATE 后，MySQL 的 ROW_COUNT() 到底表示“匹配了多少行”，还是“真正改了多少行”，关键不在函数名，而在客户端连接采用的 affected rows 语义。默认情况下，UPDATE 关注实际发生变化的行；如果客户端连接启用了 CLIENT_FOUND_ROWS，返回值会转为 WHERE 匹配行数。

官方参考地址：https://dev.mysql.com/doc/refman/8.4/en/information-functions.html

先记住一句话：做同步、审计和“是否真的写入”的判断时优先使用实际修改数；做“条件命中了多少对象”的统计时，才选择匹配数。两种语义都合理，但必须在接口契约里写清楚。

先分清 ROW_COUNT 返回的是哪种计数

把一次更新拆成三件事最容易理解：WHERE 产生匹配集合，赋值表达式决定这些行是否发生值变化，ROW_COUNT() 再把本次语句的 affected rows 暴露给当前连接。也就是说，匹配行不等于改变行。

例如，下面的示例把两行都纳入条件，但其中一行已经是目标值。它用于说明取值时机和语义，不把示例输出当成某台数据库的运行证据。

-- 建立一个最小示例，status 已经是目标值的行不会产生实际变化
CREATE TABLE task_demo (
    id INT PRIMARY KEY,
    status VARCHAR(20) NOT NULL
);

INSERT INTO task_demo (id, status)
VALUES (1, 'done'), (2, 'pending');

-- WHERE 可能匹配两行，但只有 pending 这一行真的改变
UPDATE task_demo
SET status = 'done'
WHERE id IN (1, 2);

-- ROW_COUNT() 应紧跟在 UPDATE 后取，避免被下一条语句改写语义
SELECT ROW_COUNT() AS affected_rows;

在默认 affected rows 语义下，这次更新的重点是“实际改变了多少行”；如果业务要统计命中对象，就不能只看这个默认结果。

比较三种常见返回语义

把候选方案放在一起看，选择会更稳：

第三种场景尤其容易误判：官方文档说明，重复键更新时每行可能按 1、2 或 0 计数，分别对应插入、更新已有行和已有值不变；启用 CLIENT_FOUND_ROWS 后，已有值不变的情况会按 1 计数。它不是简单的“匹配数开关”，需要单独约定。

连接参数决定 UPDATE 的语义

CLIENT_FOUND_ROWS 是客户端连接选项，不是给当前 SQL 临时加上的关键字。MySQL C API 文档把它与 mysql_real_connect() 的连接标志关联起来；驱动或连接池如何暴露这个标志，要以对应驱动文档为准。

这也是“同一条 SQL 在两个服务里返回不同数量”的常见原因：SQL 文本相同，但连接初始化方式、驱动默认值或连接池配置不同。排查时先记录驱动、连接参数和连接池初始化位置，再比较 SQL，而不是先改业务判断。

-- 只展示契约写法：应用应在同一连接中紧接 UPDATE 读取计数
UPDATE task_demo
SET status = 'done'
WHERE id = 2;

-- 中文注释说明：这里读取的是当前连接刚执行语句的计数
SELECT ROW_COUNT() AS rows_for_current_connection;

按业务场景选择，不要把两个数字混成一个字段

如果接口返回的是“本次实际更新条数”，使用默认语义更直观；只有值发生变化时才让调用方认为资源被修改。若页面要展示“筛选条件命中了多少条”，则应显式命名为 matched_rows，并确保连接启用了匹配数语义，或者在业务层单独用计数查询得到它。

生产代码还要注意三点：第一，ROW_COUNT() 是当前连接上的语句结果，不能跨连接读取；第二，必须紧跟目标 DML，日志查询或其它语句可能让调用时机失去意义；第三，基于 statement-based replication 时不要把它当成跨副本可靠的事实，官方文档明确提示该函数在这种复制方式下不可靠。

常见问题

为什么 UPDATE 了相同值，ROW_COUNT() 可能是 0？

因为默认语义统计实际改变的行；WHERE 匹配到了记录，但赋值后值没有变化，所以实际修改数为 0。

只执行 SQL 能切换成匹配行数吗？

不能把它理解成 SQL 关键字。它依赖客户端连接标志；应在驱动或连接池初始化处确认是否启用了 CLIENT_FOUND_ROWS，并把结果字段命名成匹配数或修改数。

ROW_COUNT() 能不能作为同步事件的唯一依据？

不建议直接把它当成跨副本事实。对于同步事件，最好结合明确的业务版本、更新时间或变更日志；行数只表达本次语句在当前连接中的 affected rows 语义。

总结：先决定业务要“匹配数”还是“实际修改数”，再检查连接选项，最后让接口字段名体现语义。这样即使 SQL 不变，也不会因为连接配置不同而误判结果。