Master Distributed Locks in Spring Boot with Lock4j: A Complete Guide

Environment: SpringBoot 3.2.5

1. Introduction

Lock4j is a distributed lock component that offers strong extensibility and multiple backend support (Redis, Redisson, Zookeeper). It uses Spring AOP with the highest precedence, ensuring it does not interfere with other aspects such as declarative transactions.

Simple to use, powerful, highly extensible.

Supports Redisson, RedisTemplate, Zookeeper; can be mixed and extended.

If you need to build your own distributed‑lock solution, the following sections show how to implement it with annotations.

2. Practical Example

2.1 Add Dependencies

<code>&lt;properties&gt;
  &lt;lock4j.version&gt;2.2.7&lt;/lock4j.version&gt;
&lt;/properties&gt;
&lt;dependency&gt;
  &lt;groupId&gt;com.baomidou&lt;/groupId&gt;
  &lt;artifactId&gt;lock4j-redis-template-spring-boot-starter&lt;/artifactId&gt;
  &lt;version&gt;${lock4j.version}&lt;/version&gt;
&lt;/dependency&gt;</code>

If you prefer Redisson or Zookeeper, add the corresponding starter:

<code>&lt;!-- redisson --&gt;
&lt;artifactId&gt;lock4j-redisson-spring-boot-starter&lt;/artifactId&gt;
&lt;!-- zookeeper --&gt;
&lt;artifactId&gt;lock4j-zookeeper-spring-boot-starter&lt;/artifactId&gt;</code>

Configuration

<code>spring:
  data:
    redis:
      timeout: 10000
      connectTimeout: 20000
      host: 127.0.0.1
      password: xxxooo
  # if using Zookeeper
  coordinate:
    zookeeper:
      zkServers: 127.0.0.1:2181,...</code>

After configuration, you can use the @Lock4j annotation to acquire locks.

2.2 Basic Usage

<code>@Service
public class StorageService {
  private final StorageRepository storageRepository;
  public StorageService(StorageRepository storageRepository) {
    this.storageRepository = storageRepository;
  }

  @Lock4j
  public void deductStorage(Long storageId, int count) {
    // TODO
  }
}</code>

The default lock timeout is 3 seconds and the lock expires after 30 seconds.

Custom Key

Without specifying a key, Lock4j generates one automatically:

<code>lock4j:com.pack.test.lock4j.StorageServicedeductStorage#</code>

You can customize the key with SpEL:

<code>@Lock4j(key = "#storageId")
public void deductStorage(Long storageId, int count) { }</code>

Resulting key example:

<code># method call storageService.deductStorage(1, 2);
lock4j:com.pack.test.lock4j.StorageServicedeductStorage#1</code>

Or use a plain string (note the required single quotes):

<code>@Lock4j(keys = "'storageId'")
public void deductStorage(...) { }</code>

Expiration Settings

Both lock timeout and expiration can be configured:

<code>@Lock4j(keys = {"#storageId"}, expire = 3000, acquireTimeout = 3000)
public void deductStorage(Long storageId, int count) { }</code>

expire: lock expiration in milliseconds (must be longer than business processing time). acquireTimeout: time to wait for the lock in milliseconds.

2.3 Advanced Usage

Global Configuration

<code>lock4j:
  acquire-timeout: 3000
  expire: 30000
  primary-executor: com.baomidou.lock.executor.RedisTemplateLockExecutor
  lock-key-prefix: lock4j</code>

The primary‑executor determines which backend is used first (Redisson > RedisTemplate > Zookeeper).

Custom Executor (Lock Implementation)

<code>@Component
public class JdbcLockExecutor implements LockExecutor<String> {
  private final JdbcTemplate jdbcTemplate;
  public JdbcLockExecutor(JdbcTemplate jdbcTemplate) {
    this.jdbcTemplate = jdbcTemplate;
  }
  @Override
  public String acquire(String lockKey, String lockValue, long expire, long acquireTimeout) {
    // TODO; acquire lock
    return null;
  }
  @Override
  public boolean releaseLock(String key, String value, String lockInstance) {
    // TODO; release lock
    return false;
  }
}</code>

Register it as a Spring bean and use:

<code>@Lock4j(executor = JdbcLockExecutor.class)
public void deductStorage(Long storageId, int count) { }</code>

Custom Key Builder

<code>@Component
public class PackLockKeyBuilder implements LockKeyBuilder {
  @Override
  public String buildKey(MethodInvocation invocation, String[] definitionKeys) {
    // TODO; generate key
    return null;
  }
}</code>

Use it with:

<code>@Lock4j(keyBuilderStrategy = PackLockKeyBuilder.class)
public void deductStorage(Long storageId, int count) { }</code>

Custom Failure Strategy

<code>@Component
public class PackLockFailureStrategy implements LockFailureStrategy {
  @Override
  public void onLockFailure(String key, Method method, Object[] arguments) {
    // TODO
  }
}</code>

Apply it via:

<code>@Lock4j(failStrategy = PackLockFailureStrategy.class)
public void deductStorage(Long storageId, int count) { }</code>

Manual Lock/Unlock (Non‑Annotation)

<code>private final LockTemplate lockTemplate;

public StorageService(LockTemplate lockTemplate) {
  this.lockTemplate = lockTemplate;
}

public void deductStorage(Long storageId, int count) {
  String key = "xxxx";
  final LockInfo lockInfo = lockTemplate.lock(key, 30000L, 5000L, RedisTemplateLockExecutor.class);
  if (null == lockInfo) {
    throw new RuntimeException("业务处理中,请稍后再试");
  }
  try {
    // TODO business logic
  } finally {
    lockTemplate.releaseLock(lockInfo);
  }
}
</code>

Manual locking is useful for fine‑grained control but is rarely needed.

These examples cover the essential and advanced capabilities of Lock4j for building robust distributed‑lock solutions in Spring Boot.