分库分表缓存分桶,这个Java一致性Hash工具类有8个方法

简介: 这是一个基于虚拟节点的哈希环(Consistent Hash Ring)Java工具类,支持动态增删节点、精准key路由、槽位统计与拓扑查看,适用于分库分表、缓存分桶和负载均衡场景,要求JDK 17+,线程不安全,开箱即用。(239字)

📋 目录

一、工具类功能

带虚拟节点的哈希环:把机器注册成环上的槽位、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") 拿到 719442721701827697
  • md5Hash("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

四、工具类源码(可直接复制)

📦 源码文件

相关文章
|
17天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
7084 53
|
4天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
5天前
|
云安全 人工智能 安全
|
17天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5487 65
|
12天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
2764 9
|
4天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
9天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1792 1
|
2天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1210 0
|
8天前
|
人工智能 iOS开发 开发者
2026年 Codex 下载地址更新:codexdown.cn 已更换为 codexdown.cc(附 Codex 客户端下载)
2026年Codex官方下载站已由codexdown.cn正式迁移至codexdown.cc,提供Windows/macOS最新客户端、历史版本、安装教程及配置指南,开发者可一站式获取稳定、安全、签名验证的AI编程工具资源。(239字)
1640 0