{"id":27771439,"url":"https://github.com/wuba/wlock","last_synced_at":"2025-04-29T22:39:52.418Z","repository":{"id":49844175,"uuid":"518349572","full_name":"wuba/WLock","owner":"wuba","description":"A high-reliable, high-throughput distributed lock service based on the consensus algorithm component WPaxos.","archived":false,"fork":false,"pushed_at":"2023-08-11T08:28:37.000Z","size":280136,"stargazers_count":188,"open_issues_count":1,"forks_count":22,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-29T22:39:33.402Z","etag":null,"topics":["java","lock","paxos","readwritelock","reentrantlock","synchronization"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wuba.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-27T07:13:33.000Z","updated_at":"2025-04-21T08:33:29.000Z","dependencies_parsed_at":"2023-01-22T16:15:12.372Z","dependency_job_id":null,"html_url":"https://github.com/wuba/WLock","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wuba%2FWLock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wuba%2FWLock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wuba%2FWLock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wuba%2FWLock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wuba","download_url":"https://codeload.github.com/wuba/WLock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251596590,"owners_count":21615011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","lock","paxos","readwritelock","reentrantlock","synchronization"],"created_at":"2025-04-29T22:39:51.615Z","updated_at":"2025-04-29T22:39:52.398Z","avatar_url":"https://github.com/wuba.png","language":"Java","readme":"# WLock\nWLock是一套基于一致性算法组件[WPaxos](https://github.com/wuba/WPaxos) 实现的高可靠、高吞吐分布式锁服务，可应用于分布式环境下协调多进程/线程对共享资源的访问控制、多节点Master选主等业务场景。\n\n## 核心能力\n- **丰富的锁类型：** 互斥锁、可重入锁、公平锁、优先级锁、读写锁；  \n- **灵活的锁操作：** 支持阻塞/非阻塞、同步/异步watch等方式获取锁，支持锁续约，TTL等机制；  \n- **获取锁粒度:** 进程、线程；  \n- **多租户隔离：** 提供秘钥作为集群分配、锁操作隔离、权限控制的租户单位，支持单个秘钥跨集群动态平滑迁移；  \n- **配置管理：** 提供集群节点扩/缩容，主从切换配置变更推送，客户端秘钥配置管理，秘钥归属集群平滑迁移等能力；\n\n## 特性\n- **高可靠性：**  \n  基于paxos算法实现多副本数据同步，Master节点故障时主从自动切换，在无Master或者Master漂移过程仍可保证锁状态的持续一致性，不影响正常锁操作；\n  \u003cbr\u003e\u003cbr\u003e\n- **高吞吐：**  \n  集群多节点互为主备部署，多paxos分组的Master均匀分布在所有集群节点，不同paxos分组的锁操作并行处理，相同paxos分组锁操作批量合并处理，大大提升了系统的吞吐量；\n  \u003cbr\u003e\u003cbr\u003e\n- **易用性：**\n丰富的锁接口封装，开箱即用；\n\n## 为什么选择WLock\n在分布式领域中，分布式锁已经是一种比较成熟的技术，现有的实现方案也有很多，例如基于Redis封装的Redisson Lock、RedLock，以及基于Zookeeper、Etcd等系统的封装实现，既然已经存在这么多分布式锁方案，为什么还开发WLock，优势又有哪些？接下来我们从功能、服务特性、性能三个维度，介绍下这几种分布式锁的差异化。\n#### 功能差异\n| 实现 |  wlock  |  redis（redisson）|  zookeeper(curator)  |  etcd (jetcd) \n| ------ | ------ | ------ | ------ | ------ | \n| 锁类型| 公平锁/优先级锁/读写锁 | 公平锁/非公平锁/读写锁 | 公平锁/读写锁 | 公平锁 |\n| 锁续约 | 支持（自动/主动触发） | 仅支持watchdog自动续约 | 不支持 | 支持 | \n| 异步watch机制 | 支持 | 不支持 | 支持 | 支持 |   \n| TTL机制 | 支持 | 支持 | 不支持 | 支持 |   \n| 锁粒度 | 进程/线程 | 线程 | 线程 | 进程/线程 |\n#### 服务特性\n| 实现 |  wlock  |  redis（redisson）| redis （redlock） |  zookeeper(curator)  |  etcd (jetcd)\n| ------ | ------ | ------ | ------ | ------ | ------ | \n| 可用性 | N/2 + 1可用 | 主从(异步) | N/2 + 1可用 | N/2 + 1可用 | N/2 + 1可用，但是在leader发生切换期间，不提供服务 |\n| 可靠性 | 高 | 低，主从切换数据可能丢失 | 略高，对节点间时钟一致性要求高，单节点挂掉数据不能同步恢复 | 高 | 高 |\n| 单客户端并发 | 最高到5.5W左右 | 最高到3W左右 | 最高到2.9W左右 | 最高到6.5K左右 | 最高到5.5K左右 |\n| 系统吞吐量 | 13.6万+ | 3万 | 3万 | 8750 | 6793 |\n| 响应延迟 | 700微妙+ | 200微妙+ | 600微妙+ | 2毫秒+ | 2毫秒+ |\n| 接入复杂度 | 简单，已封装接口 | 简单，已封装接口 | 简单，已封装接口  | 简单，已封装接口（非curator sdk需自行封装） | 需要封装 |\n\n#### 性能\n\n#### 测试运行环境\n```\n机器配置：\nCPU：20 x Intel(R) Xeon(R) Silver 4114 CPU @ 2.20GHz  \n内存：192 GB  \n硬盘：ssd  \n网卡：万兆网卡  \n服务端集群机器个数：3台\n```\n\n#### 测试结果\n\n**单客户端qps：**\n\n\u003cimg src=\"document/img/qps.png\" height=\"60%\" width=\"60%\" /\u003e\n\n\n**相同并发下，请求响应延迟（单位ms）**\n\n\u003cimg src=\"document/img/rt.png\" height=\"60%\" width=\"60%\" /\u003e\n\n说明：以上对比测试的中数据，redis、zk、etcd相关非官方数据，均由我们在相同环境下实际压测得到。其中，对于qps的统计，客户端请求一次加锁再请求一次释放锁合并为一次计数，更详细的压测数据及压测条件可查看[开源对比](document/BENCHMARK.md)文档。\n\n通过以上几个维度的测试分析，WLock的优势在于可靠性与系统吞吐量比较高，处理延迟略低于redis，但明显高于zookeeper与etcd，为此，对于分布式锁选型有以下建议:  \n1. 对可靠性要求不高，响应延迟比较敏感的场景，锁并发低于3W时可使用redis，高于3W建议用WLock；\n2. 对可靠性要求比较高，同时锁并发高于500的场景，可使用WLock；\n\n## 快速使用\n\n\n#### 本地运行 WLock\nWLock 运行在所有主流操作系统上，只需要安装Java JDK 8 或更高版本。  \n\n#### 快速部署与启动 :  \n通过该启动方式，会创建默认集群（default_cluster）与默认秘钥（default_key），可快速部署注册中心与服务节点进行测试，[参考文档](document/QUICKDEPLOY.md)  \n\n#### 常规部署与启动 : \n以下为生产环境正常服务部署、启动流程：\n1. **创建数据表** \n\t- wlock注册中心为方便快速启动,使用 H2 数据库,线上建议使用mysql,建表请参考 [ SQL](document/sql/create.sql).\n2. **调整数据库配置**[详情](document/DEPLOY.md#调整数据库配置)\n3. **部署注册中心并启动** - [详情](document/DEPLOY.md#部署注册中心并启动)\n4. **创建集群** - [详情](document/DEPLOY.md#通过swagger进行集群创建)\n5. **添加节点** - [详情](document/DEPLOY.md#通过swagger进行节点添加)\n6. **节点上线** - [详情](document/DEPLOY.md#通过swagger进行节点上线)\n7. **服务端初始化** - [详情](document/DEPLOY.md#服务端初始化)\n\n\n#### 客户端初始化\n\n**1. 注册秘钥**\n\n```shell\n# 访问注册中心节点通过 swagger 快速注册秘钥\nhttp://localhost:8888/swagger-ui/index.html#/key-rest/addKeyUsingPOST\n```\n\n**2. 依赖客户端jar包**\n\n```shell\n# 客户端 jar 包位置\ncd target/client\n```\n\n```xml\n\u003cdependency\u003e\n  \u003cartifactId\u003ewlock.client\u003c/artifactId\u003e\n  \u003cgroupId\u003ecom.wuba.wlock\u003c/groupId\u003e\n  \u003cversion\u003e{project.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n**3. 查看秘钥配置**\n```shell\nhttp://localhost:8888/swagger-ui/index.html#/key-rest/getKeyListUsingPOST\n```\n\n**4. 初始化**\n\n```java\nwLockClient = new WLockClient(\"D484FEEF4F6E564920FABD0DE3C58D77\", \"127.0.0.1\", 22020);\nString lockKey = \"my_test_lock\";\nWDistributedLock wdLock = wlockClient.newDistributeLock(lockKey);\n```\n\n**参数说明 :**  \n**keyHash** ：秘钥hash key,从秘钥配置中获取  \n**registryIp** ：注册中心 ip  \n**registryPort** ：注册中心端口\n**lockKey** ：分布式锁名称  \n**WDistributedLock** ：分布式锁对象封装\n\n#### 互斥锁示例\n\n```java\nString keyPath = \"/opt/wlock.key\";\nWLockClient wlockClient = new WLockClient(keyPath);\nString lockKey = \"my_test_lock\";\nWDistributedLock wdLock = wlockClient.newDistributeLock(lockKey);\n\nAcquireLockResult lockResult = wdLock.tryAcquireLock(30000, 10000, new LockExpireListener() {\n\t@Override\n\tpublic void onExpire(String key) {\n\t\tSystem.out.println(\"key expired\");\n\t}\n});\n```\n\n\n#### 读写锁示例\n```java\nWLockClient wlockClient= new WLockClient(\"test123_8\", \"127.0.0.1\", 22020);\nWReadWriteLock wReadWriteLock = wlockClient.newReadWriteLock(\"test_key\" );\nWReadLock readLock = wReadWriteLock.readLock();\nWWriteLock  writeLock = wReadWriteLock.writeLock();\nAcquireLockResult readResult = readLock.tryAcquireLock(1000 * 60, 1000 * 60);\nAcquireLockResult writeResult = writeLock.tryAcquireLock(1000 * 60, 1000 * 60);\n```\n\n**以上只是简单使用demo,详细使用说明请参考[使用文档](document/USE.md)**\n\n## 文档\n\n[开源对比](document/BENCHMARK.md)   \n[部署文档](document/DEPLOY.md)   \n[接口文档](document/USE.md)   \n[分布式锁源码实现对比](document/CONTRAST.md)  \n[其它实现原理介绍文档](https://www.zhihu.com/column/c_1669293131785773056)  \n## 参考\n[How to do distributed locking](https://martin.kleppmann.com/2016/02/08/how-to-do-distributed-locking.html)\n\n## 未来规划\n1. 提供go、php等多语言sdk\n2. 开源web管控中心、监控模块\n3. 支持分布式信号量机制\n\n## 如何贡献\n诚挚邀请对分布式锁感兴趣的同学一起参与WLock项目的开发建设，或提出宝贵意见和建议，参与方式可参考文档[CONTRIBUTING](CONTRIBUTING.md)。Star\u0026Fork也是对我们最大的支持。\n\n\n## 开源许可\nWLock项目基于[Apache License 2.0](./LICENSE)协议开源\n\n\n\n## Stargazers over time\n\n[![Stargazers over time](https://starchart.cc/wuba/WLock.svg)](https://starchart.cc/wuba/WLock)\n\n\n\n## 联系我们\n\u003cimg src=\"document/img/wlock-wechat.png\"/\u003e  \n欢迎添加58技术微信账号，加入wlock技术讨论群~\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwuba%2Fwlock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwuba%2Fwlock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwuba%2Fwlock/lists"}