MySQL JSON_MERGE_PATCH 怎样按对象字段合并文档

如果一列 JSON 里保存的是用户偏好或配置补丁，最常见的需求不是把两个文档简单拼在一起，而是让“后来的对象字段覆盖前面的同名字段”。MySQL 的 JSON_MERGE_PATCH() 正好用于这种按对象成员合并的场景：第二个对象的非 null 同名成员覆盖第一个对象，第二个对象把成员写成 JSON null 时则删除该成员。

官方地址：https://dev.mysql.com/doc/refman/8.4/en/json-modification-functions.html

先记住边界：它遵循 RFC 7396 的合并语义，适合“补丁覆盖”，不是把数组元素逐个拼接。下面按最小 SQL、嵌套对象、数组与函数选择四步拆开。

先区分补字段、覆盖字段和删除字段

把第一个参数看成基础文档，把第二个参数看成补丁文档。补丁里出现新键，就把新键加入结果；出现同名键且值不是 JSON null，就用补丁值替换或递归合并；出现同名键且值是 JSON null，就从结果中移除该键。

这里的“删除”是 JSON 文档成员被移除，不等同于把数据库列更新成 SQL 的 NULL。写 SQL 时要区分 SQL NULL 与 JSON 文本中的 null。

用最小 SQL 看清对象与嵌套对象的结果

先用两个对象观察新增、覆盖和删除。代码块里的注释只说明每个输入的意图，结果以读者自己的 MySQL 环境为准。

-- 基础文档：保留主题、语言和旧的调试开关
SET @base = '{"theme":"light","lang":"zh-CN","debug":true}';
-- 补丁文档：覆盖主题，删除 debug，并加入字号
SET @patch = '{"theme":"dark","debug":null,"fontSize":14}';

-- 第二个对象的非 null 同名键覆盖，第一个对象的 debug 被删除
SELECT JSON_MERGE_PATCH(@base, @patch) AS merged;
-- 预期结构：{"fontSize": 14, "lang": "zh-CN", "theme": "dark"}

若同名成员的值还是对象，合并会递归进入下一层，而不是整段对象无条件丢弃：

-- 两边都含 profile 对象，只改其中的 region
SET @base = '{"profile":{"region":"cn","level":1}}';
SET @patch = '{"profile":{"region":"sg"}}';

-- profile.level 仍保留，profile.region 使用补丁值
SELECT JSON_MERGE_PATCH(@base, @patch) AS merged;
-- 预期结构：{"profile":{"level":1,"region":"sg"}}

这也是它和“直接替换某个 JSON 路径”不同的地方：你提交的是一个文档级补丁，MySQL 会按对象层级递归处理。若业务只允许修改一条路径，应该把路径更新规则单独设计，避免把不该变化的字段一起覆盖。

处理数组、标量和非法 JSON 的边界

数组不要套用对象字段覆盖的直觉。根据官方规则，如果第二个参数不是对象，结果就是第二个参数；因此数组补丁会整体成为结果，而不会把两个数组按下标合并。

-- 第二个参数是数组，结果整体采用第二个参数
SELECT JSON_MERGE_PATCH('[1,2]', '[3,4]') AS merged;
-- 结果： [3, 4]

-- 第二个参数是标量，同样由第二个参数决定结果
SELECT JSON_MERGE_PATCH('{"enabled":true}', 'false') AS merged;
-- 结果： false

-- NULL 是 SQL NULL，会让函数返回 SQL NULL；不要把它当成 JSON null
SELECT JSON_MERGE_PATCH('{"a":1}', NULL) AS merged;
-- 结果： NULL

如果你的目标是保留重复键的旧值并把冲突值放进数组，应对比 JSON_MERGE_PRESERVE()，而不是继续给 PATCH 增加参数。传入无效 JSON 文档时，函数会报错；这类输入应在写入边界明确处理。

按是否保留旧值选择 PATCH 或 PRESERVE

两个函数的名字相近，但承诺不同。PATCH 把冲突理解为覆盖：同名键取第二份文档的值，JSON null 还能表达删除。PRESERVE 则会保留冲突值，数组与标量冲突时可能产生数组结果。

可以用一个小查询对照冲突字段，但不要把示例输出当作线上运行结果：

-- 两份文档都提供 level，观察“覆盖”与“保留”的不同
SET @left_doc = '{"level":1,"name":"demo"}';
SET @right_doc = '{"level":2}';

-- PATCH 选择右侧冲突值；PRESERVE 会保留冲突值
SELECT
  JSON_MERGE_PATCH(@left_doc, @right_doc) AS patch_result,
  JSON_MERGE_PRESERVE(@left_doc, @right_doc) AS preserve_result;

把合并结果接回更新语句并留下可复查信号

确认函数语义后，再把它放进更新语句。关键是让“基础文档、补丁文档和结果”在同一条业务链上可追溯，避免只看到最终 JSON 却不知道哪个补丁删除了字段。

-- settings_json 存储基础配置，:patch_json 是应用提交的 JSON 补丁
UPDATE user_settings
SET settings_json = JSON_MERGE_PATCH(settings_json, :patch_json),
    -- 更新时间用于追踪最后一次补丁写入
    updated_at = CURRENT_TIMESTAMP
WHERE user_id = :user_id;

-- 更新前先确认补丁是对象，避免数组或标量替换整份配置
SELECT JSON_TYPE(:patch_json) AS patch_type;
-- 业务层只接受 OBJECT，再继续执行上面的 UPDATE

在应用层至少记录用户标识、补丁来源和变更时间；不要记录包含隐私的完整文档。若需要判断某个键是否被删除，应该在业务日志里记录补丁动作，而不是只对最终文档做猜测。

最终判断可以压缩成四句：对象补丁用于覆盖字段；嵌套对象会递归合并；JSON null 删除同名成员；数组或标量作为第二参数时可能整体替换结果。只要这四条与业务语义一致，JSON_MERGE_PATCH 就适合做文档级配置补丁。

JSON_MERGE_PATCH 能按数组下标合并吗？

不应这样理解。第二参数为非对象时，结果采用第二参数；需要按下标修改时，应使用针对路径的 JSON 函数。

为什么写了 null 后字段不见了？

这是 PATCH 的设计语义：对象补丁中的 JSON null 表示移除同名成员。若要保留一个 JSON null 值，需要重新设计数据结构或使用更明确的路径更新方式。

JSON_MERGE_PATCH 和 JSON_MERGE_PRESERVE 怎么选？

配置覆盖优先 PATCH，冲突值保留优先 PRESERVE；不要只因为函数名相似就互换。