Redis 哈希字段如何用 HINCRBY 做原子计数：不存在字段初始化与整数错误处理

线上接口要统计“某个用户今天完成了多少次操作”时，把每个用户拆成一个 Redis key 往往太散；把计数放进一个哈希，又容易在并发请求下写出丢增量。更稳妥的做法是让 Redis 直接执行 HINCRBY，把读取、加法和写回收成一次原子命令，同时明确处理字段不存在、旧值不是整数和整数范围这三类边界。

HINCRBY key field increment 会返回递增后的整数值；key 或 field 不存在时按 0 初始化，但已有字段若不是整数，命令会失败而不会替你纠正数据。

先把计数器的状态边界说清楚

假设哈希 key 是 user:42:daily，字段是 completed。第一次写入前，这个 key 甚至不存在，最小可复现命令如下：

DEL user:42:daily
HINCRBY user:42:daily completed 1
HGET user:42:daily completed

第二条命令返回整数 1，第三条命令也读到 1。这里的关键不是客户端先查空值，而是 Redis 在命令内部把不存在的 field 当成 0，再加上 increment。key 不存在时，Redis 会创建一个哈希；field 不存在时，同样从 0 开始。

成功响应也有明确含义：返回的是递增后的值，不是本次增量。接口可以直接把这个整数作为“完成次数”，少做一次回读。HINCRBY 的时间复杂度是 O(1)，increment 可以是负数，因此撤销一次操作可以传入 -1，但这不等于业务上允许计数器跌到负数，是否允许仍要由业务规则判断。

错误值要在写入前拦住

原子并不代表任何输入都能成功。如果历史数据是 unknown、1.5 这类非整数文本，直接执行：

HSET user:42:daily completed unknown
HINCRBY user:42:daily completed 1

第二条命令会返回错误，常见表现是不能把字符串解析成整数。它不会把 unknown 当成 0，也不会悄悄覆盖旧值。这个失败分支很重要：如果程序把所有 Redis 错误都当成“计数成功”，接口就会返回错误的完成次数。

在 Go 服务里，可以先读出已有值做数据质量判断，再决定是否调用 HINCRBY。这个检查不是为了替代原子递增，而是为了把坏数据变成可观测的业务错误：

raw, err := rdb.HGet(ctx, "user:42:daily", "completed").Result()
if err != nil && err != redis.Nil {
    return fmt.Errorf("read counter: %w", err)
}
if raw != "" {
    if _, err := strconv.ParseInt(raw, 10, 64); err != nil {
        return fmt.Errorf("counter is not integer: %w", err)
    }
}
next, err := rdb.HIncrBy(ctx, "user:42:daily", "completed", 1).Result()
if err != nil {
    return fmt.Errorf("increment counter: %w", err)
}
return next, nil

这段检查适合修复历史脏数据或给出更清楚的告警；在高并发核心路径中，真正的写入仍应依靠 HINCRBY 的原子执行，并配合数据初始化约束，避免把“读取后判断”误当成完整的并发锁。

上线前验收三个可观察结果

第一，删除 key 后直接执行 HINCRBY，返回值应为传入的 increment；第二，连续执行两次 HINCRBY user:42:daily completed 1，结果应从 1 变成 2，而不是出现覆盖；第三，把字段临时写成 unknown 后再递增，应收到错误并保留原值。

还要留意整数范围。官方命令页说明 HINCRBY 支持的是 64 位有符号整数；接近上限时继续递增会失败。因此不要只在应用层使用更大的无界整数就认为 Redis 能接受，计数器的上限、溢出告警和降级策略要在接口契约里写明。

常见问题

field 不存在时需要先 HSET 0 吗？

不需要。HINCRBY 自己会把不存在字段按 0 处理；额外 HSET 只会增加一次写操作。

HINCRBY 能处理小数吗？

不能。它面向整数；小数场景应评估 HINCRBYFLOAT，并单独设计精度和展示规则。

为什么 HGET 后再 HINCRBY 仍要小心并发？

HGET 只是数据质量检查，两个请求之间仍可能交错。真正的加法和写回必须交给 HINCRBY，不能改成客户端计算后 HSET。

小结

Redis 哈希计数器的最小可靠路径是：用 HINCRBY 完成原子递增，利用不存在字段的 0 初始化语义，把返回值直接作为新计数；对已有值先做整数校验，对错误和 64 位边界留下清晰的监控与处理分支。这样既减少一次回读，也不会把脏数据和并发覆盖藏起来。