Redis HINCRBY 命令详细教程HINCRBY对 Hash 中某个字段的整数值做加法。字段不存在时按 0 起算Key 不存在时会自动创建。整个操作在服务端原子完成适合做计数。资料合集https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338一、概览与语法HINCRBY key field increment项目说明数据类型Hash 字段的整数值支持版本Redis 2.0.0 起keyHash 的 Key不存在时自动创建field要增减的字段不存在时按 0 起算increment有符号 64 位整数可为负数实现减法返回值运算后该字段的整数值整数回复数值范围有符号 64 位整数即 -2^63 到 2^63-1时间复杂度O(1)ACLwrite、hash、fast返回的是运算后的结果值不是本次变化量也不是是否新增字段的标记。$TRAE_REF二、基础示例以下命令在测试实例的 redis-cli 中执行。文中结果是预期说明未实际连接 Redis 运行。DEL tutorial:{hincrby}:stats HSET tutorial:{hincrby}:stats views 5 HINCRBY tutorial:{hincrby}:stats views 1 HINCRBY tutorial:{hincrby}:stats views -1 HINCRBY tutorial:{hincrby}:stats views -10 HGET tutorial:{hincrby}:stats views TYPE tutorial:{hincrby}:stats预期结果HSET 返回1三次 HINCRBY 依次返回6、5、-5HGET 返回-5注意字段值以字符串形式存储TYPE 返回hash。increment 为负数即等价于减法不需要单独的递减命令。三、自动创建 Key 与字段字段不存在时按 0 起算Key 不存在时会新建一个 Hash。这一点让 HINCRBY 可以直接用于计数器初始化无需先判断存在性。DEL tutorial:{hincrby}:new HINCRBY tutorial:{hincrby}:new likes 3 HLEN tutorial:{hincrby}:new TYPE tutorial:{hincrby}:new HINCRBY tutorial:{hincrby}:new shares -1 HGETALL tutorial:{hincrby}:new预期结果第一次调用直接返回3并创建 KeyHLEN 返回1TYPE 返回hash对另一个不存在的字段使用负数增量返回-1HGETALL 显示两个字段likes 3 shares -1。字段按 0 起算意味着负数增量会得到负值业务需要自行决定是否允许。四、错误与边界情况场景行为Key 不存在自动创建 Hash字段从 0 开始累加字段不存在按 0 起算不报错字段值是普通整数文本正常运算返回运算后的值字段值不是整数如abc、1.5报错提示不是整数或超出范围字段值是3.0报错小数形式不被接受即使数值是整数运算结果超出 64 位有符号整数范围报溢出错误字段值保持不变increment 不是整数报错参数必须是整数Key 是 String、List 等非 Hash报 WRONGTYPE 错误字段带 TTL7.4 及以上运算保留该字段的 TTL见下一节DEL tutorial:{hincrby}:errors HSET tutorial:{hincrby}:errors text abc HINCRBY tutorial:{hincrby}:errors text 1 HSET tutorial:{hincrby}:errors float 1.5 HINCRBY tutorial:{hincrby}:errors float 1 HSET tutorial:{hincrby}:errors decimal 3.0 HINCRBY tutorial:{hincrby}:errors decimal 1 SET tutorial:{hincrby}:wrong text HINCRBY tutorial:{hincrby}:wrong field 1对 text 与 float 两个字段的 HINCRBY 会因值不是整数而报错对 decimal值为3.0的调用同样报错因为小数形式不被接受即使数值本身是整数。最后一条在 String 类型上报 WRONGTYPE。Redis 不会把非整数文本自动转换或截断业务应在写入时保证字段内容是合法整数。五、TTL 与 HINCRBYHINCRBY 是在原值基础上做加法不覆盖字段内容因此它保留字段已有的过期时间。这与 HSET 不同HSET 覆盖字段会清除该字段的 TTL。DEL tutorial:{hincrby}:ttl HSET tutorial:{hincrby}:ttl count 10 HEXPIRE tutorial:{hincrby}:ttl 300 FIELDS 1 count HTTL tutorial:{hincrby}:ttl FIELDS 1 count HINCRBY tutorial:{hincrby}:ttl count 5 HTTL tutorial:{hincrby}:ttl FIELDS 1 count HSET tutorial:{hincrby}:ttl count 15 HTTL tutorial:{hincrby}:ttl FIELDS 1 count预期结果设置 TTL 后 HTTL 返回递减的正数HINCRBY 之后 HTTL 仍为正数说明 TTL 被保留改用 HSET 覆盖同一字段后 HTTL 变为-1说明 TTL 被清除。字段级 TTL 需要 Redis 7.4 或更新版本。六、原子性与并发计数HINCRBY 在服务端单线程内原子执行多个客户端并发调用不会丢失更新这是它相对“先 HGET 再计算再 HSET”的核心优势。非原子写法可能丢失更新 客户端 A: HGET stats views - 5 客户端 B: HGET stats views - 5 客户端 A: HSET stats views 6 客户端 B: HSET stats views 6 B 覆盖了 A 的结果一次自增丢失 原子写法 客户端 A: HINCRBY stats views 1 - 6 客户端 B: HINCRBY stats views 1 - 7需要注意的是原子性只覆盖单条命令。如果业务需要“读当前值、判断阈值、再决定是否增加”这个判断加修改的流程仍不是原子的应使用 Lua 脚本或带 WATCH 的事务。同样先 HINCRBY 再判断返回值是否超限时已经发生的增加无法自动回退需要额外的补偿逻辑。七、客户端示例前提为已安装 redis-py 并准备好本地测试实例。importredis rredis.Redis(hostlocalhost,port6379,decode_responsesTrue)ktutorial:{hincrby}:pythontry:r.delete(k)print(r.hincrby(k,views,5))# 5Key 与字段自动创建print(r.hincrby(k,views,1))# 6print(r.hincrby(k,views,-10))# -4print(r.hget(k,views))# -4字符串r.hset(k,views,2**62)print(r.hincrby(k,views,2**62-1))# 9223372036854775807正好是上限try:r.hincrby(k,views,1)# 超过上限报错exceptredis.ResponseErrorase:print(溢出,e)finally:r.delete(k)r.close()JavaJedis示例try(JedisjedisnewJedis(localhost,6379)){System.out.println(jedis.hincrBy(tutorial:{hincrby}:java,views,5));// 5System.out.println(jedis.hincrBy(tutorial:{hincrby}:java,views,-1));// 4jedis.del(tutorial:{hincrby}:java);}八、与相近命令的区别命令作用对象数值类型返回值类型HINCRBYHash 字段64 位有符号整数整数HINCRBYFLOATHash 字段浮点数字符串INCR / INCRBY / DECRBYString Key64 位有符号整数整数HSETHash 字段任意字符串新增字段数HSETNXHash 字段任意字符串是否设置成功需要浮点运算用 HINCRBYFLOAT需要按整个 Key 计数用 INCR 系列需要在字段不存在时才写入用 HSETNX。注意 HSET 会覆盖字段并清除其 TTL而 HINCRBY 保留 TTL。九、练习、排错与总结练习新建tutorial:{hincrby}:exercise用 HINCRBY 对字段 score 依次加 10、加 5、加 -20预期返回10、15、-5用 HGET 确认值为-5再对同一字段执行HSET ... score 3.0然后 HINCRBY预期报错。最后设置字段 TTL 并再次 HINCRBY确认 TTL 未被清除。排错要点报“不是整数”时检查字段值是否含小数点、空格或单位后缀报溢出时确认业务量级是否超过 64 位范围必要时改用字符串大数或分片计数并发下计数偏小说明某处用了先读后写HGET 返回字符串需要业务自行转换转换异常不代表 Redis 出错。清理使用DEL tutorial:{hincrby}:stats tutorial:{hincrby}:new tutorial:{hincrby}:errors tutorial:{hincrby}:wrong tutorial:{hincrby}:ttl tutorial:{hincrby}:exercise。速记字段级整数自增、字段不存在按 0 起算、64 位有符号范围、返回运算后结果、单条命令原子且保留字段 TTL。