Redis JSON.SET 怎样只替换嵌套字段

RedisJSON 里已经有一份用户档案，只想把 profile.city 改成新城市，却不希望覆盖姓名、偏好等其它字段时，关键不是重新提交整份 JSON，而是把嵌套路径写进 JSON.SET。它的最小形式是：

# key 是 JSON 文档名，路径定位到嵌套成员，最后一个参数是合法 JSON 值
redis-cli JSON.SET doc $.profile.city '"Shanghai"'

如果路径命中，Redis 返回 OK，只有被定位的成员被替换。本文使用 Redis 官方命令文档作为事实依据：https://redis.io/docs/latest/commands/json.set/。下面只讨论嵌套字段替换、字段创建和返回值判断。

问题：为什么不能把整个对象重新 SET

假设文档是下面的 JSON。它有根级的 id、嵌套的 profile，以及同级的 settings。

{
  "id": 42,
  "profile": {
    "name": "Lin",
    "city": "Beijing"
  },
  "settings": {
    "theme": "dark"
  }
}

如果把新对象直接写到根路径，确实能得到新内容，但调用方必须先拼完整文档，也容易漏掉并发期间刚写入的字段。只改一处时，应把三个参数分开理解：doc 是 key，$.profile.city 是 JSONPath，"Shanghai" 是要写入的 JSON 值。

最小配方：用 JSONPath 只替换嵌套成员

先用根路径准备一份文档，再用嵌套路径更新城市。第二条命令不会覆盖 profile.name、id 或 settings.theme。

# 只有创建新文档时使用根路径；对象值必须是合法 JSON
redis-cli JSON.SET doc '$' '{"id":42,"profile":{"name":"Lin","city":"Beijing"},"settings":{"theme":"dark"}}'

# 点号路径定位 profile 下的 city，字符串值要带 JSON 双引号
redis-cli JSON.SET doc '$.profile.city' '"Shanghai"'

# 读取整个文档观察替换后的结果
redis-cli JSON.GET doc '$'

这里的路径写法是重点：根路径可以写成 $ 或 .，嵌套成员则沿着对象层级写成 $.profile.city。如果你的客户端对 $ 有额外转义要求，只需要保证最终发送给 Redis 的 path 仍然是这个字符串。

关键变体：新增末级字段可以，缺失中间节点不行

JSON.SET 不只会替换已有成员。当父对象已经存在，而最终成员不存在时，可以直接创建这个末级成员：

# profile 已经存在，因此可以在它下面新增 language
redis-cli JSON.SET doc '$.profile.language' '"zh-CN"'

# missing.parent 并不存在，中间路径缺失时不会自动补齐对象
redis-cli JSON.SET doc '$.missing.parent.city' '"Shanghai"'

两种情况不要混在一起：profile.language 的父对象 profile 存在，末级字段可以被创建；missing.parent.city 的中间节点缺失，路径不能创建，通常得到 nil。如果 key 本身不存在，则只能从根路径 $ 或 . 创建新 JSON 文档，直接写 $.profile.city 会收到“必须从根创建新对象”的错误。

安全写法：用 XX 和返回值判断是否真的改到了字段

如果更新动作不能隐式创建新字段，可以加 XX。它要求 path 至少命中一个已有位置；路径不存在或 key 不存在时返回空值，不会写入。

# 只有 city 已存在时才替换，避免把拼错的路径当成成功
redis-cli JSON.SET doc '$.profile.city' '"Shanghai"' XX

# 读取一个精确路径，便于脚本记录目标字段的最终值
redis-cli JSON.GET doc '$.profile.city'

可以把返回结果按三类处理：

• OK：路径有效且写入完成；使用 JSON.GET 读取目标路径即可继续业务流程。
• nil：路径没有可更新的位置，或 NX/XX 条件不满足；先检查 key、父对象和路径拼写。
• 错误：JSON 值非法、路径语法错误、数组下标越界，或试图从非根路径创建不存在的 key；这类情况应修正输入，而不是重复发送同一命令。

另一个容易忽略的点是，path 可能匹配多个位置。例如递归路径可能同时命中多个 a 字段，此时一次写入会替换每个匹配位置。只想改一个确定字段时，优先使用完整的对象链路，避免宽泛路径带来多处修改。

完整片段：把嵌套字段更新封装成清晰的配方

下面的 shell 片段把准备文档、精确更新和结果判断放在一起。示例没有把命令输出伪装成运行截图；关键是让调用方根据返回码决定后续动作。

#!/usr/bin/env bash
set -euo pipefail

# 先确保示例文档存在；生产代码可由初始化流程负责这一步
redis-cli JSON.SET user:42 '$' \
  '{"profile":{"name":"Lin","city":"Beijing"},"settings":{"theme":"dark"}}' >/dev/null

# XX 保证只更新已有的 city，不因路径拼写错误意外新增字段
result=$(redis-cli --raw JSON.SET user:42 '$.profile.city' '"Shanghai"' XX)
if [ "$result" = "OK" ]; then
  # 成功后只读取目标字段，避免再次传输整份 JSON
  redis-cli JSON.GET user:42 '$.profile.city'
else
  # nil 代表条件或路径未命中，交给调用方做业务分支
  echo "JSON.SET 未更新目标字段：$result" >&2
  exit 1
fi

这套配方的边界很明确：路径只到需要变更的字段，更新条件由 XX 表达，结果由 OK 或空响应区分。若业务要求“字段不存在就创建”，可以去掉 XX，但仍要保证父对象已存在。

常见问题

JSON.SET 的 value 为什么不能直接写 Shanghai？

因为 value 必须是合法 JSON 值。字符串要写成 "Shanghai"，数字、布尔值和对象则按各自的 JSON 语法传入。

为什么 $.profile.city 返回 nil？

先确认 key 存在，再确认 profile 是对象且路径拼写一致；如果使用了 XX，还要确认最终的 city 已经存在。

怎样避免误改多个嵌套字段？

不要使用过宽的递归路径，使用从根对象到目标成员的完整 JSONPath，并在更新后只读取该路径判断结果。

总结一下：Redis JSON.SET 的局部更新依赖正确的 JSONPath。父对象存在时可以创建末级成员，中间节点缺失时不能自动补齐；不存在的 key 要从根路径创建。对只允许修改既有字段的场景，加上 XX 并区分 OK、nil 和错误，就能把“只替换嵌套字段”变成稳定、可判断的最小操作。