Redis JSON.SET 路径不存在为什么没有创建对象

Redis JSON.SET 没有按预期创建对象，通常不是 JSON 值写错了，而是把“创建文档”和“新增末级字段”当成了同一件事。不存在的 key 只能从根路径 $ 或 . 开始创建；已有 JSON 对象时，才可以在已存在的父对象下面新增最后一级成员。中间任何一级不存在，路径都不能被自动补齐。

官方文档：https://redis.io/docs/latest/commands/json.set/

先看 key 是否存在，再看 path 是否是根路径；如果 key 已有内容，确认父对象已经存在。最后一级字段可以新增，中间路径不会自动生成。

• key 不存在：只能用 $ 或 . 写入完整根文档。
• 父对象存在：可以用 $.profile.email 新增末级 email。
• 中间对象缺失：$.profile.contact.email 在 contact 不存在时不会自动创建。

先把“文档不存在”和“字段不存在”分开

JSON.SET 的 path 是 JSONPath，不是会自动创建目录的路径。Redis 官方规则是：key 不存在时，只有根路径可以创建一份新的 JSON 文档；key 已经存在时，如果 path 的最后一个 token 是不存在的对象成员，并且它的父对象确实存在，才会新增这个成员。

因此，下面两条命令的失败原因不同：第一条试图在一个不存在的 key 上直接写子路径；第二条虽然 key 已存在，但中间的 x 没有对象可以继续向下走。

# 清理演示 key，避免旧文档改变判断结果
redis-cli DEL user:100

# key 不存在，非根路径不能直接创建新文档
redis-cli JSON.SET user:100 $.name '"小林"'

# 先建立一个根文档，后续才有父对象可以定位
redis-cli JSON.SET user:100 $ '{"name":"小林"}'

# key 已存在，但 x 是缺失的中间路径
redis-cli JSON.SET user:100 $.x.y 2

(error) ERR new objects must be created at the root
OK
(nil)

新 key 要先从根路径初始化

当业务第一次写入用户资料、订单快照或配置文档时，建议把初始化动作明确成一次根路径写入。根值可以是对象，也可以是数组、字符串或数字；如果后续要写嵌套字段，最容易维护的是先创建对象骨架。

# 用根路径建立对象骨架，profile 也一并准备好
redis-cli JSON.SET user:100 $ '{"name":"小林","profile":{}}'

# profile 已存在，因此 email 作为最后一级成员可以被新增
redis-cli JSON.SET user:100 $.profile.email '"xiaolin@example.com"'

# 读取整个文档，确认新增字段位于预期父对象中
redis-cli JSON.GET user:100 $

这里的关键不是先后顺序本身，而是父对象是否已经存在。初始化时也可以直接把 profile 和 email 一起放进根 JSON；这样能减少“先写子路径、发现父路径缺失”的分支。

只允许新增最后一级，不会补齐中间对象

假设文档是 {"profile":{}}，执行 JSON.SET user:100 $.profile.email ... 可以成功，因为 profile 是已有对象，email 是最后一级的新成员。可是如果文档只有 {}，执行 $.profile.email 时，profile 本身就是中间路径，Redis 不会替你决定它应该是对象还是数组，也不会自动创建它。

# 只有根对象，没有 profile；profile 是缺失的中间路径
redis-cli JSON.SET user:101 $ '{}'
redis-cli JSON.SET user:101 $.profile.email '"xiaolin@example.com"'

# 先补齐父对象，再写入最后一级字段
redis-cli JSON.SET user:101 $.profile '{}'
redis-cli JSON.SET user:101 $.profile.email '"xiaolin@example.com"'

如果路径还包含数组下标，也要先确认数组本身和目标位置已存在。不要把 JSONPath 书写正确理解成“路径上的对象都会自动创建”；JSON.SET 只负责替换匹配位置，或在已有对象父节点下增加一个末级成员。

根据返回值处理 NX、XX 和空路径

JSON.SET 成功时返回 OK。当 key 已存在但路径不存在且不能创建，通常得到空响应；当 key 不存在且 path 不是根路径，则是明确的 ERR new objects must be created at the root 错误。应用层不要把这两类结果都当成“字段为空”，它们代表的修复动作不同。

# NX 只在路径没有匹配项时写入，适合做一次性初始化
redis-cli JSON.SET user:102 $ '{"state":"new"}' NX

# XX 要求目标路径已经存在；条件不满足时返回空响应
redis-cli JSON.SET user:102 $.missing 1 XX

# 普通写入时，仍然要把空响应转换成“父路径未准备好”的业务分支
redis-cli JSON.SET user:102 $.profile.email '"xiaolin@example.com"'

如果使用 Go、Node.js 或 Python 客户端，建议把命令返回封装成三种状态：成功写入、条件或路径未匹配、命令错误。重试前先读取文档结构或执行一次受控的父对象初始化，不要无限重试同一条无法创建的中间路径。

常见问题

key 不存在时能不能直接写 $.user.name？

不能。新文档必须先用 $ 或 . 写入根值，之后才能继续修改内部路径。

已有 key 时，所有不存在字段都能新增吗？

只有最后一级对象成员可以在父对象存在时新增；缺失的中间对象不会自动生成。

为什么有时返回 nil，有时返回 root 错误？

key 已存在但路径无法创建时通常是空响应；key 不存在且 path 非根路径时，Redis 会返回要求从根创建的错误。

最稳妥的初始化方式是什么？

先用根路径写入完整对象骨架，再按业务需要更新末级字段。这样父对象是否存在是明确的，不依赖隐式创建。

总结

遇到 Redis JSON.SET 路径不存在的问题，可以按“key、根路径、父对象、中间路径、最后一级”五个位置检查：新 key 从根路径初始化；已有父对象时可以新增最后一级；中间路径缺失就先补齐对象；最后依据 OK、空响应或根创建错误选择业务分支。理解这条边界后，JSON.SET 的行为就不会再像普通对象赋值那样令人意外。