Redis Hash HINCRBY 为什么会报错：字符串值、类型转换与修复顺序

线上计数接口突然返回 WRONGTYPE Operation against a key holding the wrong kind of value，或者 HINCRBY 直接提示 value is not an integer，通常不是 Redis “不会自增”，而是同一个字段被不同写入路径当成了不同类型。先确认 key 的数据结构，再确认 hash field 的实际字符串，最后决定清理、迁移还是换 key，排查会快很多。

HINCRBY key field increment 要求 key 是 Hash，field 的值必须是可解析的十进制整数；key 类型错看 TYPE，字段值错看 HGET，不要一上来就 DEL。

先把两类错误分开：key 类型错，还是 field 值错

这两个报错看起来都发生在 HINCRBY，但修复动作完全不同。假设业务使用 article:42:stats 保存阅读次数，字段是 views，可以先用下面几条命令建立现场记录：

TYPE article:42:stats
HGET article:42:stats views
HKEYS article:42:stats
HINCRBY article:42:stats views 1

注意：TYPE 只告诉你 key 是 string、hash、list 等，不会告诉你 hash 内每个 field 是否可自增。key 是 hash 仍然可能在某个 field 上失败。

HINCRBY 的最小规则：Hash 加整数，不负责业务清洗

当 key 不存在时，HINCRBY 会创建一个 Hash，并把 field 初始化为 0 后加上增量；当 field 不存在时，也会按 0 处理。但只要 field 已经有值，Redis 就需要把这个字符串解析为整数。

DEL article:42:stats
HINCRBY article:42:stats views 1
HGET article:42:stats views
# "1"

HSET article:42:stats views 12
HINCRBY article:42:stats views 3
# "15"

下面这些值都不是安全的整数输入：

HSET article:42:stats views ""
HSET article:42:stats views "12.5"
HSET article:42:stats views "12 views"
HSET article:42:stats views "null"

这时业务代码如果把数据库格式化结果、带单位的展示文本或 JSON 字段直接写回 Redis，下一次 HINCRBY 就会失败。Redis 不会替你把展示层字符串还原成计数。

代码对比：把展示值和计数值分开存

比较稳妥的约定是：Hash 里只保存机器要运算的整数，带单位的文本在读取后再生成。Go 客户端可以把递增和读取放在同一套字段约定里：

type ArticleStats struct {
    Views int64
}

func addView(ctx context.Context, rdb *redis.Client, articleID int64) error {
    key := fmt.Sprintf("article:%d:stats", articleID)
    return rdb.HIncrBy(ctx, key, "views", 1).Err()
}

func readViews(ctx context.Context, rdb *redis.Client, articleID int64) (int64, error) {
    key := fmt.Sprintf("article:%d:stats", articleID)
    value, err := rdb.HGet(ctx, key, "views").Int64()
    if err != nil {
        return 0, fmt.Errorf("read views: %w", err)
    }
    return value, nil
}

页面需要显示“1.2 万次”时，在 Go 层格式化；不要为了展示方便执行 HSET views "1.2 万次"。字段名也要固定，view、views、read_count 三套命名同时存在，会让修复看起来像数据问题，实际是契约问题。

已经写脏的数据怎么修：先留证，再选方案

生产环境先记录 key、field、原值、服务版本和最近写入时间。只有确认这是一次性脏数据，并且写入方已经修复，才适合原地转换：

HGET article:42:stats views
HSET article:42:stats views 12
HINCRBY article:42:stats views 1
HGET article:42:stats views

如果原值是 12.5，不能悄悄四舍五入；如果原值是 12 views，也不能凭猜测截取数字。应先根据业务定义决定取整、回滚、丢弃还是迁移。需要保留旧值时，可以把它写入带过期时间的诊断 key，或先导出到审计系统，不要把诊断文本继续放在计数 field 中。

如果 key 本身不是 Hash，例如曾经执行过 SET article:42:stats ...，更安全的方式通常是新建 article:42:stats:v2，让新版本服务双读或回填，再切换写入。直接 DEL 会丢掉可能仍被其他接口使用的数据。

部署前验收：让错误不会在下一次发布后回来

修复代码后不要只点一次接口。至少覆盖首次创建、已有整数、空值和错误 key 四条路径：

DEL article:99:stats
HINCRBY article:99:stats views 1
HINCRBY article:99:stats views 2
HGET article:99:stats views

HSET article:99:stats views "12 views"
HINCRBY article:99:stats views 1
# 这里应被测试捕获，而不是吞掉错误

应用层要保留 Redis 命令错误的上下文，例如 key、field 和业务动作，但不要把完整用户输入写进日志。监控上可以统计 WRONGTYPE 与 value is not an integer 的次数，发布后观察错误是否归零；如果只是把错误改成默认值 0，问题会变成静默少计数。

常见问题

HINCRBY 能不能直接处理浮点数？

不能。整数计数使用 HINCRBY；需要浮点增量时使用 HINCRBYFLOAT，并仍要保证 field 中是可解析的浮点字符串。

为什么 HGET 看起来是数字，HINCRBY 仍然失败？

显示结果可能包含不可见空格、单位或小数点。把原始返回值按字节检查，并确认实际 field 名，不要只看管理后台的格式化显示。

修复 WRONGTYPE 最快是不是直接 DEL？

只有确认 key 可以丢弃时才这样做。共享 key、会话数据和统计数据应先留证，再用新 key 迁移或安排低峰切换。

小结

排查 HINCRBY 先看 TYPE，再看 HGET；修复时把计数值与展示文本分离，把字段命名和写入契约固定下来。对无法解释的旧值，保留现场比立即清零更重要；对不确定是否共享的 key，新版本 key 往往比原地改写更稳。