📋 目录
一、工具类功能
带虚拟节点的哈希环:把机器注册成环上的槽位、key 顺时针落到第一个节点,加机器或摘机器只搬动环上一小段 key、其余归属不变,用于分库分表、缓存分桶与负载均衡。
二、所需环境
JDK 17或以上
三、方法与调用示例(按需调用)
🔢 方法序号:1
🎯 方法用途:
- 建一个带虚拟节点数量配置的哈希环,后续加减机器都在这一个环上做
- 分片路由、缓存分桶、负载均衡开工前的第一步
🧩 方法定义:public static HashRing createRing(int virtualNodes)
🗣️ 入参解释:public static HashRing createRing(虚拟节点数)
📤 返回值解释:HashRing,空的哈希环实例
💡 边界口径:
- 虚拟节点数必须为正,给 0 抛
IllegalArgumentException - 数量越多分布越均衡,代价是环上槽位与增删开销变大
- 环是普通
TreeMap,实例非线程安全,多线程要外部加锁或每线程独占 - 建好时环是空的,路由返回空 Optional
🧪 方法示例:
createRing(200)建好的空环拿到物理节点 0 个、槽位 0 个- 虚拟节点数给 0 抛
虚拟节点数必须大于0,当前为0
🔢 方法序号:2
🎯 方法用途:
- 往环上注册一个物理节点,按
节点名#序号铺开虚拟节点 - 机器上线、分片扩容时用
🧩 方法定义:public void addNode(String nodeName)
🗣️ 入参解释:public void addNode(节点名)
📤 返回值解释:void,节点与它的虚拟槽位一起进环
💡 边界口径:
- 同名节点重复添加是幂等的,槽位不会翻倍
- 节点名与路由 key 一样拒绝 null 与空白,空白名会在环上留下永远命不中的幽灵槽位
- 每个物理节点占
virtualNodes个槽位,槽位总数随之线性增长
🧪 方法示例:
- 加 4 个节点后拿到
物理节点 4 个、槽位 800 个,每节点 200 个虚拟节点 - 同名节点重复添加是幂等的,槽位仍是
800 个 - 节点名给空白串抛
nodeName 不能为null或空白
🔢 方法序号:3
🎯 方法用途:
- 从环上摘掉一个物理节点及其全部虚拟槽位
- 机器下线、分片缩容时用
🧩 方法定义:public void removeNode(String nodeName)
🗣️ 入参解释:public void removeNode(节点名)
📤 返回值解释:void,节点不在环上时什么都不做
💡 边界口径:
- 删除不存在的节点是无操作,不报错
- 摘掉一个节点只搬动环上一小段 key,其余 key 原地不动
- 摘除后槽位数按虚拟节点数线性减少
🧪 方法示例:
- 摘掉 shard-2 后拿到
物理节点 3 个、槽位 600 个,换归属的 key 是5000/20000 个(占 25%),其余原地不动 - 再摘一次不存在的 shard-9,拿到
物理节点仍是 3 个、槽位仍是 600 个
🔢 方法序号:4
🎯 方法用途:
- 把一个 key 路由到环上顺时针第一个槽位所属的节点
- 判断某个订单、某个缓存键落在哪个分片时用
🧩 方法定义:public Optional<String> route(String key)
🗣️ 入参解释:public Optional<String> route(路由键)
📤 返回值解释:Optional<String>,节点名;环为空时是空 Optional
💡 边界口径:
- 同一 key 多次路由结果完全一致,这是分桶与缓存命中的前提
- 环为空返回
Optional.empty()而不是 null,调用方必须显式处理 - key 为 null 或空白抛
IllegalArgumentException - 分布是否均衡看虚拟节点数,实测 4 节点 20000 个 key 的最大落点 5187、最小 4728,与均值 5000 相差不到 6%
🧪 方法示例:
- 20000 个 key 的落点分布拿到
{shard-1=5187, shard-2=5000, shard-3=5085, shard-4=4728} route("order-1000")命中节点shard-4,连查五次结果完全一致是true- 空环上路由拿到
Optional.empty,不是 null - key 传 null 抛
key 不能为null或空白
🔢 方法序号:5
🎯 方法用途:
- 读环上物理节点的个数
- 监控面板、扩缩容前后对比时用
🧩 方法定义:public int nodeCount()
🗣️ 入参解释:public int nodeCount()(无入参)
📤 返回值解释:int,物理节点数,不含虚拟节点
💡 边界口径:
- 统计的是物理节点,与槽位数是倍数关系
- 新环是 0,配合
route的空 Optional 判断环是否可用 - 读它不改动环
🧪 方法示例:
- 摘节点之后
nodeCount()拿到物理节点 3 个
🔢 方法序号:6
🎯 方法用途:
- 读环上虚拟槽位的总数
- 评估环的规模、排查分布不均时用
🧩 方法定义:public int slotCount()
🗣️ 入参解释:public int slotCount()(无入参)
📤 返回值解释:int,虚拟槽位数,等于物理节点数乘每节点虚拟数
💡 边界口径:
- 与
nodeCount的比值就是建环时给的虚拟节点数 - 重复添加同名节点不会让槽位变多
- 摘节点后按每节点的虚拟数减少
🧪 方法示例:
- 摘掉一个节点后
slotCount()拿到当前环上槽位数 600
🔢 方法序号:7
🎯 方法用途:
- 算出一个 key 在环上用的哈希值,MD5 摘要前 8 字节按大端序拼成有符号 long
- 想自己核对路由结果、或者复现某个 key 的落点时用
🧩 方法定义:public static long md5Hash(String key)
🗣️ 入参解释:public static long md5Hash(键)
📤 返回值解释:long,有符号哈希值,环按其自然序排序
💡 边界口径:
- 该口径必须保持稳定,一旦改动所有已缓存 key 的分片归属都会重排
- MD5 在这里只用于均匀打散,不具备安全属性,不要用于签名或防篡改
- 64 位下两个虚拟节点撞同一哈希的概率可忽略,一旦发生会互相覆盖,只能换更强的哈希
- key 为 null 或空串都抛
IllegalArgumentException
🧪 方法示例:
md5Hash("shard-1#0")拿到719442721701827697md5Hash("alpha")拿到3177082431927771071,同一入参重复调用不变是true- 入参给空串抛
key 不能为null或空白
🔢 方法序号:8
🎯 方法用途:
- 列出环上当前的物理节点,按名称升序
- 打印拓扑、扩缩容后核对环内容时用
🧩 方法定义:public static List<String> nodes(HashRing ring)
🗣️ 入参解释:public static List<String> nodes(哈希环)
📤 返回值解释:List<String>,升序且不可变的节点名列表
💡 边界口径:
- 只给物理节点,看不到虚拟槽位
- 返回的列表不可变,改它抛
UnsupportedOperationException ring传 null 抛NullPointerException- 空环返回空列表
🧪 方法示例:
- 加满 4 个节点后
nodes(ring)拿到[shard-1, shard-2, shard-3, shard-4] - 摘掉 shard-2 之后拿到
[shard-1, shard-3, shard-4] - 环传 null 抛
ring 不能为null
四、工具类源码(可直接复制)
📦 源码文件