Redis JSON.NUMINCRBY 怎样增量修改嵌套数值

如果 RedisJSON 文档里有一个嵌套数值需要做加减，不必先把整份 JSON 取回应用层再改写。JSON.NUMINCRBY key path value 会按 JSONPath 找到目标数值并直接增加指定值；单个目标适合用点号路径，多目标匹配则应使用 $ 路径并按返回数组处理。

官方地址：https://redis.io/docs/latest/commands/json.numincrby/

最容易出错的地方不是加法本身，而是路径和返回值：点号路径偏向单值结果，$ 路径返回每个匹配节点的新值；匹配到非数字节点时，结果可能是 null，没有匹配时则是空数组。

本文使用一个包含对象和数组的 JSON 文档，说明如何定位嵌套字段、选择路径、解读返回值，并把错误和性能边界留在调用层处理。

先准备一个包含嵌套数值的 JSON 文档

假设订单文档同时保存总金额、明细数量和一个备注字段。示例中的 doc:order:1001 只是业务 key，路径才决定具体修改哪个字段。

# 写入一个包含对象和数组的 RedisJSON 文档，方便后续按路径增量修改
redis-cli JSON.SET 'doc:order:1001' '$' '{"summary":{"amount":120.5},"items":[{"count":2},{"count":5}],"note":"pending"}'

# 读取整个文档确认字段层级；生产代码可按需只读取目标路径
redis-cli JSON.GET 'doc:order:1001' '$'

这里的 summary.amount 和 items[*].count 都是数值，但 note 是字符串。后续路径如果指向字符串，命令不会把它强行转换成数字。

用点号路径修改一个嵌套数值

只修改订单总金额时，可以使用点号路径 .summary.amount。下面把金额增加 10.5，返回值就是修改后的数值字符串。

# 点号路径定位一个嵌套字段，第二个参数是要增加的数值
redis-cli JSON.NUMINCRBY 'doc:order:1001' '.summary.amount' 10.5

# 再读一次同一路径，确认应用层要展示的当前金额
redis-cli JSON.GET 'doc:order:1001' '.summary.amount'

点号路径适合“我明确知道只有一个目标”的场景。不要把它和数组通配符混在一起后仍按单值解析；当路径匹配多个数字时，点号语法的返回规则和 $ 语法不同，调用方应固定一种解析约定。

用 $ 路径一次处理多个匹配数值

如果要给所有明细数量增加 1，可以使用 $.items[*].count。这时返回的是 JSON 数组，每个匹配路径都有一个结果。

# $ 路径表达多匹配目标；每个命中的 count 都增加 1
redis-cli JSON.NUMINCRBY 'doc:order:1001' '$.items[*].count' 1

# 读取数组路径，检查所有明细数量的当前值
redis-cli JSON.GET 'doc:order:1001' '$.items[*].count'

$ 路径的结果不能只用一个浮点数接收。官方返回语义是：每个匹配节点返回新的数值；如果匹配到的节点不是数字，对应位置返回 null；如果路径完全没有匹配，返回空数组。

# 递归寻找名为 count 的字段；数值会增加，非数字节点返回 null
redis-cli JSON.NUMINCRBY 'doc:order:1001' '$..count' 1

如果业务要求“所有目标都必须是数字”，就不能看到部分更新后再忽略 null。应先约束文档结构，或在应用层把结果数组逐项映射回预期路径，并把非数字视为需要修复的数据状态。

四种结果边界要分别处理

“非数字”和“key 不存在”不是一回事。前者说明路径找到了节点但类型不满足增量条件；后者说明要修改的 JSON 文档不存在。把它们统一映射成“更新失败”会让排查缺少关键信息。

按路径数量估算调用开销

单路径命中一个值时，官方文档给出的时间复杂度是 O(1)；当路径评估为多个值时，复杂度与 key 中 JSON 文档大小相关，记作 O(N)。因此，递归路径不是“只多写一个通配符”这么简单，它可能扫描更多节点并返回更大的结果数组。

# 单点更新：路径明确，结果只对应一个数值
redis-cli JSON.NUMINCRBY 'doc:order:1001' '.summary.amount' 1

# 多点更新：通配范围要受文档结构约束，避免无意命中多个同名字段
redis-cli JSON.NUMINCRBY 'doc:order:1001' '$.items[*].count' 1

如果接口只允许修改一个字段，优先让调用方传入白名单路径，而不是把用户输入直接拼成任意递归 JSONPath。若确实需要多节点修改，应限制文档大小、明确结果数组的顺序和重试策略。

总结：路径先收敛，返回值再建模

JSON.NUMINCRBY 的最小模型可以概括为：key 指向文档，path 指向数值，value 指定增量。单值修改使用明确路径，多值修改使用 $ 路径并按数组处理；非数字、无匹配、key 不存在和结果越界要分开记录。性能上，匹配范围越大，遍历和返回成本越高。

相关问题

JSON.NUMINCRBY 可以修改字符串数字吗？不能把普通字符串当作可靠的数值字段。应在写入时保持 JSON 数值类型，并把非数字匹配作为数据结构问题处理。

为什么同一个命令有时返回数字，有时返回数组？通常是路径语法不同：点号路径偏向单值字符串结果，$ 路径按匹配节点返回数组。

没有匹配节点时应该创建字段吗？命令本身不会替你补齐任意父级结构。是否创建字段应由业务决定，先判断文档 schema 再选择 JSON.SET 或拒绝本次增量。