Go hash/fnv 生成稳定字符串分片键的实现方式

把租户名、用户 ID 或缓存键分到固定分片时，关键不是“随便算一个哈希”，而是固定三件事：输入按什么字节编码、使用 FNV-1 还是 FNV-1a、结果按多少位参与取模。Go 的 hash/fnv 提供了轻量的非加密哈希实现，适合路由、分桶和缓存键；它不适合密码、签名或令牌。

为什么分片键要先固定哈希口径

分片函数的输入应是业务上稳定的逻辑键，例如规范化后的租户 ID，而不是带随机前缀的临时字符串。Go 字符串转成 []byte 时按 UTF-8 参与计算，所以“租户A”和经过不同 Unicode 规范化处理的同形字符串可能得到不同结果。跨服务调用时，先约定原始字节、大小写规则和空白处理，再把哈希结果用于路由。

FNV-1 与 FNV-1a 都是非加密哈希，区别在于乘法与异或的计算顺序。工程上选定一种后要保持不变；同一项目不要让一部分代码调用 New32，另一部分调用 New32a。下面使用更常见的 FNV-1a，并把分片数作为显式参数。

用 New32a 生成稳定的字符串分片值

实现时先拒绝非法的分片数量，再创建哈希对象并写入完整键。Write 的错误在标准库实现中不会产生，但接口仍返回错误，便于未来替换为其他写入源；Sum32 返回固定宽度的无符号值，最后取模得到范围为 0 到 shards-1 的编号。

package shard

import (
    "errors"
    "hash/fnv"
)

// BucketFor 把稳定的业务键映射到 [0, shards) 的分片编号。
func BucketFor(key string, shards uint32) (uint32, error) {
    // 分片数为 0 时不能取模，先把配置错误交给调用方。
    if shards == 0 {
        return 0, errors.New("shards must be greater than zero")
    }

    h := fnv.New32a()
    // 统一使用 key 的 UTF-8 字节，调用方应先完成规范化。
    if _, err := h.Write([]byte(key)); err != nil {
        return 0, err
    }

    // Sum32 是非加密哈希值；取模只用于分片路由，不是安全校验。
    return h.Sum32() % shards, nil
}

空字符串不是错误，它会得到一个确定的编号；是否允许空键应由业务层决定。对于请求路由，建议在进入该函数前把租户 ID 缺失识别为参数错误，避免所有缺失键集中到同一个分片。

位宽、展示格式与扩容边界怎样分开

32 位足够覆盖普通分片编号、内存分桶和短期缓存路由，但它不是“32 位安全摘要”。如果哈希值要长期落盘、跨系统传递，或对象规模明显增大，可以使用 New64a；不过最终分片编号仍应由统一的无符号值取模得到，不要先转成带符号整数再参与计算。

最容易被忽略的是扩容：从 8 个分片改成 16 个分片后，原来的 hash % 8 不能直接兼容 hash % 16，大量键会换位置。扩容前要列出旧分片到新分片的迁移计划、双读或双写窗口，以及失败回滚方式。只要要求尽量少迁移，就应把一致性哈希作为独立设计议题，而不是把 FNV 取模函数硬改成“自动扩容”。

上线前的四项检查

1. 确认所有调用方使用同一套键规范化规则，特别是大小写、空白和 Unicode 输入。
2. 确认 FNV 变体、位宽和展示格式已经写入协议或配置说明，而不是依赖默认习惯。
3. 对 shards=0、空键、超长键和分片数变更分别测试，并记录预期行为。
4. 确认 FNV 只负责非加密分桶；权限校验、密码存储和签名验证不能复用这段逻辑。

常见问题

FNV-1 和 FNV-1a 能互换吗？

不能。两者输出规则不同，替换后已有键可能落到不同分片；除非同步迁移全部依赖哈希结果的数据。

为什么不能把 FNV 当成密码摘要？

FNV 的目标是快速、非加密的哈希，不提供抗碰撞和保密能力。密码、签名和令牌应使用专门的密码学方案。

分片数变化后怎样保持旧键可读？

先保留旧映射或建立迁移表，通过双读、后台搬迁和回滚窗口逐步切换；直接修改取模除非业务接受大规模迁移。