# distributed-lock-spring-boot-starter

**Repository Path**: ChildrenGreens/distributed-lock-spring-boot-starter

## Basic Information

- **Project Name**: distributed-lock-spring-boot-starter
- **Description**: distributed-lock-spring-boot-starter 是一个面向 Spring Boot 的分布式锁启动器，致力于以最小侵入和统一抽象的方式，为应用提供可靠且可扩展的分布式锁能力。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

= Distributed-Lock-Spring-Boot-Starter

link:README.adoc[English]

== 概述
这是一个 Spring Boot Starter，通过 AOP 提供基于注解的分布式锁能力。
支持的后端：Redisson、Zookeeper（Curator）和 Etcd（jetcd）。

== 特性
- +@DistributedLock+ 注解实现方法级加锁
- 基于 SpEL 的锁键解析并提供默认策略
- 多种锁类型：可重入、公平、读、写
- 按客户端 Bean 自动配置执行器

== 运行环境
- Java 17+
- Spring Boot 4.0.x

== 版本策略
- Spring Boot 3.x 用户请使用 0.0.x 发布线
- Spring Boot 4.x 用户请使用 0.1.x 发布线

== 安装
添加 Starter 依赖，并选择一个后端客户端依赖。

Maven:
[source,xml]
----
<dependency>
  <groupId>com.childrengreens</groupId>
  <artifactId>distributed-lock-spring-boot-starter</artifactId>
  <version>${latest-version}</version>
</dependency>
----

后端依赖（可选其一或多个）：
[source,xml]
----
<dependency>
  <groupId>org.redisson</groupId>
  <artifactId>redisson</artifactId>
  <version>4.0.0</version>
</dependency>
<dependency>
  <groupId>org.apache.curator</groupId>
  <artifactId>curator-recipes</artifactId>
  <version>5.9.0</version>
</dependency>
<dependency>
  <groupId>io.etcd</groupId>
  <artifactId>jetcd-core</artifactId>
  <version>0.8.6</version>
</dependency>
----

== 配置
application.yml:
[source,yaml]
----
distributed:
  lock:
    prefix: lock
----

- +distributed.lock.prefix+（默认：+lock+）
- +distributed.lock.provider+（可选：+redisson+、+zookeeper+、+etcd+）

== 使用方式
在方法上添加 +@DistributedLock+：
[source,java]
----
import com.childrengreens.distributedlock.annotation.DistributedLock;
import com.childrengreens.distributedlock.annotation.LockType;

@DistributedLock(key = "#orderId", prefix = "order", waitTime = 3, leaseTime = 10, lockType = LockType.FAIR)
public void process(String orderId) {
    // business logic
}
----

SpEL 示例：
[source,java]
----
@DistributedLock(key = "#user.id + ':' + #order.id")
public void pay(User user, Order order) {
}

@DistributedLock(key = "@tenantProvider.tenantId + ':' + #p0")
public void handle(String id) {
}
----

默认 key 行为：
- 当 +key+ 为空时，默认生成：
+
+DeclaringClass.methodName:<SimpleKey>+

Prefix 行为：
- +@DistributedLock(prefix = "...")+ 优先于 +distributed.lock.prefix+
- 两者都为空时不使用前缀

Provider 选择：
- 当多个客户端同时存在时，可设置 +distributed.lock.provider+ 明确指定后端

== 后端配置
当存在对应客户端 Bean 时，Starter 会自动配置执行器。

=== Redisson
[source,java]
----
import org.redisson.Redisson;
import org.redisson.api.RedissonClient;
import org.redisson.config.Config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
class RedissonConfig {
    @Bean
    RedissonClient redissonClient() {
        Config config = new Config();
        config.useSingleServer().setAddress("redis://127.0.0.1:6379");
        return Redisson.create(config);
    }
}
----

=== Zookeeper (Curator)
[source,java]
----
import org.apache.curator.framework.CuratorFramework;
import org.apache.curator.framework.CuratorFrameworkFactory;
import org.apache.curator.retry.ExponentialBackoffRetry;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
class CuratorConfig {
    @Bean(initMethod = "start", destroyMethod = "close")
    CuratorFramework curatorFramework() {
        return CuratorFrameworkFactory.newClient(
            "127.0.0.1:2181",
            new ExponentialBackoffRetry(1000, 3)
        );
    }
}
----

=== Etcd (jetcd)
[source,java]
----
import io.etcd.jetcd.Client;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
class EtcdConfig {
    @Bean(destroyMethod = "close")
    Client etcdClient() {
        return Client.builder().endpoints("http://127.0.0.1:2379").build();
    }
}
----

== 锁类型
- +REENTRANT+：默认可重入锁
- +FAIR+：后端支持时使用公平锁
- +READ+：读锁（读写锁）
- +WRITE+：写锁（读写锁）

映射说明：
- Redisson：直接映射到对应锁类型
- Zookeeper：+FAIR+ 使用可重入互斥锁实现
- Etcd：仅一种锁类型；+LockType+ 用于解锁时的跟踪

== 错误处理
- 获取锁失败会抛出 +DistributedLockException+
- 解锁异常会记录日志并被吞掉，避免影响业务异常

== 自定义
可以提供自定义 +DistributedLockExecutor+ Bean 以覆盖自动配置。
也可以替换 +LockKeyResolver+ 实现自定义的 key 解析逻辑。