尧图网页设计 
DiceDB JSON.NUMINCRBY 命令详解基于 JSONPath 的原子数值自增操作【免费下载链接】dicedbOpen-source, low-latency key/value engine built on Valkey with query subscriptions and hierarchical storage tiers.项目地址: https://gitcode.com/GitHub_Trending/dic/dicedbJSON.NUMINCRBY是 DiceDB JSONDiceDBJSON模块提供的数值操作命令用于对 JSON 文档中指定路径下的数值字段执行原子自增并返回更新后的新值。本文以命令参考文档为主体结合 DiceDB 仓库中该命令的元数据定义、核心实现internal/eval/store_eval.go与单元/集成测试internal/eval/eval_test.go、tests0/json_test.go完整讲解语法、参数、返回值、全部边界场景与源码级实现原理。读完本文你将能熟练使用JSON.NUMINCRBY完成计数器、余额累加、批量数值更新等实战任务并理解它在引擎内部的完整执行链路。命令概览JSON.NUMINCRBY属于 DiceDBJSON 模块专门用于对存储在 DiceDB 中的 JSON 文档执行数值字段的自增操作。其典型应用场景包括购物车数量累加、账户余额变动、访问计数、埋点统计等需要原子更新 JSON 内嵌数值的业务。语法JSON.NUMINCRBY key path increment参数说明参数描述类型是否必填keyJSON 文档所存储的键名String是path指定待自增数值位置的 JSONPath 表达式String是increment自增的数值增量可为整数或浮点数Floating Point / Integer是从源码看increment参数同时支持整数与浮点数两种形态引擎会根据增量中是否包含小数点.自动选择strconv.ParseInt或strconv.ParseFloat解析路径见 internal/eval/store_eval.go。返回值条件返回值命令执行成功数组包含更新后各匹配路径的新值键不存在或 JSONPath 无效error底层执行流程JSON.NUMINCRBY在命令表中被声明为已迁移命令IsMigrated: true元数据位于 internal/eval/commands.go实际处理函数为evalJSONNUMINCRBY。其执行流程如下参数校验参数少于 3 个时返回wrong number of arguments错误store_eval.go。键查找与类型断言通过store.Get(key)取对象键不存在返回could not perform this operation on a key that doesnt exist再通过object.AssertType(obj.Type, object.ObjTypeJSON)校验必须是 JSON 类型否则返回WRONGTYPE错误store_eval.go。JSONPath 解析使用jp.ParseString(path)解析路径表达式解析失败返回invalid JSONPath错误store_eval.go。增量解析逐字符校验增量内容非法字符会触发expected value at line 1 column N或trailing characters at line 1 column N错误随后根据是否含小数点决定按浮点或整数解析store_eval.go。路径求值与原地修改执行expr.Get求值结果为空时返回空数组[]。若路径是根路径$直接对根值自增否则通过expr.Modify对每个匹配节点调用incrementValue完成原地修改store_eval.go。incrementValue是自增的核心逻辑它依据 JSON 字段类型分派处理store_eval.go浮点数字oldVal incrFloat结果按是否浮点增量格式化整数字浮点增量时先转float64累加否则oldVal incrInt其他类型字符串、对象、布尔、数组、null 等保持原值不变isModified置为false结果中对应位置返回null。这一设计保证了“部分匹配、部分跳过”的语义同一路径下数值字段被自增非数值字段被安全跳过而非报错。完整使用示例以下示例均基于 DiceDB 默认端口7379。准备示例文档127.0.0.1:7379 JSON.SET user:1001 $ {name: John Doe, age: 30, balance: 100.50, account: {id: 0, lien: 0, balance: 100.50}} OK基础用法整数自增将age字段自增 1127.0.0.1:7379 JSON.NUMINCRBY user:1001 $.age 1 [31]浮点自增将balance字段自增 25.75127.0.0.1:7379 JSON.NUMINCRBY user:1001 $.balance 25.75 [126.25]递归匹配所有同名路径使用递归下降符$..balance同时自增顶层与account内两个balance字段127.0.0.1:7379 JSON.NUMINCRBY user:1001 $..balance 25.75 [126.25,126.25]注意返回数组中各元素依次对应每个匹配路径更新后的新值可用于校验递归匹配是否全部生效。对非数值字段自增对字符串字段name执行自增非数值节点被跳过返回null127.0.0.1:7379 JSON.NUMINCRBY user:1001 $.name 5 [null]对不存在的路径自增路径无匹配节点时返回空数组不产生错误127.0.0.1:7379 JSON.NUMINCRBY user:1001 $.nonexistent 10 []非法路径使用非法的 JSONPath 会直接报错127.0.0.1:7379 JSON.NUMINCRBY user:1001 . 5 (error) ERROR invalid JSONPath不存在的键对不存在的键执行自增127.0.0.1:7379 JSON.NUMINCRBY user:1002 . 5 (error) ERROR could not perform this operation on a key that doesnt exist错误处理速查表错误场景错误消息触发条件参数数量不足(error) ERR wrong number of arguments for json.numincrby command命令参数少于 3 个见 tests0/json_test.go键不存在(error) ERROR could not perform this operation on a key that doesnt exist指定键未存储任何对象键类型错误WRONGTYPE Operation against a key holding the wrong kind of value键存在但存储的不是 JSON 类型对象JSONPath 无效(error) ERROR invalid JSONPath路径表达式无法被jp.ParseString解析增量格式非法(error) ERROR expected value at line 1 column N/trailing characters at line 1 column N增量包含非数字字符错误位置精确到列号源码级验证测试用例解读仓库对JSON.NUMINCRBY提供了完善的测试覆盖可作为理解其行为边界的权威参考。单元测试testEvalJSONNUMINCRBY在 internal/eval/eval_test.go 中覆盖了 7 类场景整数字段自增{a: 2}加 3 得[5]浮点字段自增{a: 2.5}加 1.5 得[4.0]多字段递归自增对{a: 2, b: 10, c: [15, {d: 20}]}执行$..*加 5所有数值节点含嵌套数组一并自增非数值位置返回null数组元素自增$.a[1]对{a: [1, 2, 3]}中的下标 1 元素加 5 得[7]不存在字段返回[]且不报错混合类型字段$..*加 2 时字符串字段被跳过、数值字段被更新深层嵌套字段$..c可命中任意层级的c字段。集成测试TestJSONNumIncrBy在 tests0/json_test.go 中通过真实连接验证了完整命令链路其中几个值得注意的用例空参数、单参数、双参数三种写法均返回参数数量错误增量含非法字符如时按字符位置精确报错非根路径$..a自增后JSON.GET能验证文档内数值确实被原地修改支持负数增量-2实现“自减”且多次操作后可回滚到原值。这些测试从侧面印证了本文档中的行为描述也为读者提供了可自行复现的验证清单。使用建议与注意事项路径尽量精确使用$根路径或$..*全量递归会影响更多节点返回数组也更长业务上应尽量使用$.field、$.account.balance或$.arr[1]等精确路径减少无谓扫描。理解null语义非数值节点不会导致命令失败而是返回null占位若希望“遇到非数值即报错”需要先借助JSON.TYPE或JSON.GET校验字段类型。空数组不等于报错路径无匹配时返回[]与“路径非法”的错误是不同的两者应分别处理。整数与浮点的选择增量不带小数点时按整数累加输出不含小数尾缀带小数点时按浮点累加例如测试中 2.5 1.5 输出为[4.0]。请根据精度需求显式选择增量形态。原子性该命令在引擎内部一次完成“读-改-写”适合并发场景下的计数器与余额类业务同时文档中的age、balance示例也印证了它可作为 Redis 风格INCR/INCRBY的 JSON 内嵌替代方案。更多 JSON 命令如JSON.SET、JSON.GET、JSON.ARRAPPEND等可参考 docs/src/_skipped_commands 目录下的对应文档构建完整的 JSON 数据处理能力。【免费下载链接】dicedbOpen-source, low-latency key/value engine built on Valkey with query subscriptions and hierarchical storage tiers.项目地址: https://gitcode.com/GitHub_Trending/dic/dicedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DiceDB JSON.NUMINCRBY 命令详解：基于 JSONPath 的原子数值自增操作
DiceDB JSON.NUMINCRBY 命令详解基于 JSONPath 的原子数值自增操作【免费下载链接】dicedbOpen-source, low-latency key/value engine built on Valkey with query subscriptions and hierarchical storage tiers.项目地址: https://gitcode.com/GitHub_Trending/dic/dicedbJSON.NUMINCRBY是 DiceDB JSONDiceDBJSON模块提供的数值操作命令用于对 JSON 文档中指定路径下的数值字段执行原子自增并返回更新后的新值。本文以命令参考文档为主体结合 DiceDB 仓库中该命令的元数据定义、核心实现internal/eval/store_eval.go与单元/集成测试internal/eval/eval_test.go、tests0/json_test.go完整讲解语法、参数、返回值、全部边界场景与源码级实现原理。读完本文你将能熟练使用JSON.NUMINCRBY完成计数器、余额累加、批量数值更新等实战任务并理解它在引擎内部的完整执行链路。命令概览JSON.NUMINCRBY属于 DiceDBJSON 模块专门用于对存储在 DiceDB 中的 JSON 文档执行数值字段的自增操作。其典型应用场景包括购物车数量累加、账户余额变动、访问计数、埋点统计等需要原子更新 JSON 内嵌数值的业务。语法JSON.NUMINCRBY key path increment参数说明参数描述类型是否必填keyJSON 文档所存储的键名String是path指定待自增数值位置的 JSONPath 表达式String是increment自增的数值增量可为整数或浮点数Floating Point / Integer是从源码看increment参数同时支持整数与浮点数两种形态引擎会根据增量中是否包含小数点.自动选择strconv.ParseInt或strconv.ParseFloat解析路径见 internal/eval/store_eval.go。返回值条件返回值命令执行成功数组包含更新后各匹配路径的新值键不存在或 JSONPath 无效error底层执行流程JSON.NUMINCRBY在命令表中被声明为已迁移命令IsMigrated: true元数据位于 internal/eval/commands.go实际处理函数为evalJSONNUMINCRBY。其执行流程如下参数校验参数少于 3 个时返回wrong number of arguments错误store_eval.go。键查找与类型断言通过store.Get(key)取对象键不存在返回could not perform this operation on a key that doesnt exist再通过object.AssertType(obj.Type, object.ObjTypeJSON)校验必须是 JSON 类型否则返回WRONGTYPE错误store_eval.go。JSONPath 解析使用jp.ParseString(path)解析路径表达式解析失败返回invalid JSONPath错误store_eval.go。增量解析逐字符校验增量内容非法字符会触发expected value at line 1 column N或trailing characters at line 1 column N错误随后根据是否含小数点决定按浮点或整数解析store_eval.go。路径求值与原地修改执行expr.Get求值结果为空时返回空数组[]。若路径是根路径$直接对根值自增否则通过expr.Modify对每个匹配节点调用incrementValue完成原地修改store_eval.go。incrementValue是自增的核心逻辑它依据 JSON 字段类型分派处理store_eval.go浮点数字oldVal incrFloat结果按是否浮点增量格式化整数字浮点增量时先转float64累加否则oldVal incrInt其他类型字符串、对象、布尔、数组、null 等保持原值不变isModified置为false结果中对应位置返回null。这一设计保证了“部分匹配、部分跳过”的语义同一路径下数值字段被自增非数值字段被安全跳过而非报错。完整使用示例以下示例均基于 DiceDB 默认端口7379。准备示例文档127.0.0.1:7379 JSON.SET user:1001 $ {name: John Doe, age: 30, balance: 100.50, account: {id: 0, lien: 0, balance: 100.50}} OK基础用法整数自增将age字段自增 1127.0.0.1:7379 JSON.NUMINCRBY user:1001 $.age 1 [31]浮点自增将balance字段自增 25.75127.0.0.1:7379 JSON.NUMINCRBY user:1001 $.balance 25.75 [126.25]递归匹配所有同名路径使用递归下降符$..balance同时自增顶层与account内两个balance字段127.0.0.1:7379 JSON.NUMINCRBY user:1001 $..balance 25.75 [126.25,126.25]注意返回数组中各元素依次对应每个匹配路径更新后的新值可用于校验递归匹配是否全部生效。对非数值字段自增对字符串字段name执行自增非数值节点被跳过返回null127.0.0.1:7379 JSON.NUMINCRBY user:1001 $.name 5 [null]对不存在的路径自增路径无匹配节点时返回空数组不产生错误127.0.0.1:7379 JSON.NUMINCRBY user:1001 $.nonexistent 10 []非法路径使用非法的 JSONPath 会直接报错127.0.0.1:7379 JSON.NUMINCRBY user:1001 . 5 (error) ERROR invalid JSONPath不存在的键对不存在的键执行自增127.0.0.1:7379 JSON.NUMINCRBY user:1002 . 5 (error) ERROR could not perform this operation on a key that doesnt exist错误处理速查表错误场景错误消息触发条件参数数量不足(error) ERR wrong number of arguments for json.numincrby command命令参数少于 3 个见 tests0/json_test.go键不存在(error) ERROR could not perform this operation on a key that doesnt exist指定键未存储任何对象键类型错误WRONGTYPE Operation against a key holding the wrong kind of value键存在但存储的不是 JSON 类型对象JSONPath 无效(error) ERROR invalid JSONPath路径表达式无法被jp.ParseString解析增量格式非法(error) ERROR expected value at line 1 column N/trailing characters at line 1 column N增量包含非数字字符错误位置精确到列号源码级验证测试用例解读仓库对JSON.NUMINCRBY提供了完善的测试覆盖可作为理解其行为边界的权威参考。单元测试testEvalJSONNUMINCRBY在 internal/eval/eval_test.go 中覆盖了 7 类场景整数字段自增{a: 2}加 3 得[5]浮点字段自增{a: 2.5}加 1.5 得[4.0]多字段递归自增对{a: 2, b: 10, c: [15, {d: 20}]}执行$..*加 5所有数值节点含嵌套数组一并自增非数值位置返回null数组元素自增$.a[1]对{a: [1, 2, 3]}中的下标 1 元素加 5 得[7]不存在字段返回[]且不报错混合类型字段$..*加 2 时字符串字段被跳过、数值字段被更新深层嵌套字段$..c可命中任意层级的c字段。集成测试TestJSONNumIncrBy在 tests0/json_test.go 中通过真实连接验证了完整命令链路其中几个值得注意的用例空参数、单参数、双参数三种写法均返回参数数量错误增量含非法字符如时按字符位置精确报错非根路径$..a自增后JSON.GET能验证文档内数值确实被原地修改支持负数增量-2实现“自减”且多次操作后可回滚到原值。这些测试从侧面印证了本文档中的行为描述也为读者提供了可自行复现的验证清单。使用建议与注意事项路径尽量精确使用$根路径或$..*全量递归会影响更多节点返回数组也更长业务上应尽量使用$.field、$.account.balance或$.arr[1]等精确路径减少无谓扫描。理解null语义非数值节点不会导致命令失败而是返回null占位若希望“遇到非数值即报错”需要先借助JSON.TYPE或JSON.GET校验字段类型。空数组不等于报错路径无匹配时返回[]与“路径非法”的错误是不同的两者应分别处理。整数与浮点的选择增量不带小数点时按整数累加输出不含小数尾缀带小数点时按浮点累加例如测试中 2.5 1.5 输出为[4.0]。请根据精度需求显式选择增量形态。原子性该命令在引擎内部一次完成“读-改-写”适合并发场景下的计数器与余额类业务同时文档中的age、balance示例也印证了它可作为 Redis 风格INCR/INCRBY的 JSON 内嵌替代方案。更多 JSON 命令如JSON.SET、JSON.GET、JSON.ARRAPPEND等可参考 docs/src/_skipped_commands 目录下的对应文档构建完整的 JSON 数据处理能力。【免费下载链接】dicedbOpen-source, low-latency key/value engine built on Valkey with query subscriptions and hierarchical storage tiers.项目地址: https://gitcode.com/GitHub_Trending/dic/dicedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考