Lock4j Distributed Lock Component: Features, Configuration, and Usage Guide

Lock4j is a distributed lock component for Java, supporting Spring AOP‑based declarative and programmatic locking, and can work with RedisTemplate, Redisson, and Zookeeper.

Features

Simple to use, powerful, highly extensible.

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

Preparation

Add one of the following Maven dependencies according to the desired implementation:

<dependency>
  <groupId>com.baomidou</groupId>
  <artifactId>lock4j-redis-template-spring-boot-starter</artifactId>
  <version>2.2.4</version>
</dependency>

<dependency>
  <groupId>com.baomidou</groupId>
  <artifactId>lock4j-redisson-spring-boot-starter</artifactId>
  <version>2.2.4</version>
</dependency>

Configure Redis in application.yml (or application.properties) as follows:

spring:
  redis:
    database: 0
    host: 127.0.0.1
    port: 6379
    password:
    jedis:
      pool:
        max-active: 200
        max-wait: -1
        max-idle: 10
        min-idle: 0
    timeout: 6000

Annotation Attributes

package com.baomidou.lock.annotation;

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@Documented
public @interface Lock4j {
    String name() default "";
    Class<? extends LockExecutor> executor() default LockExecutor.class;
    String[] keys() default {""};
    long expire() default -1L;
    long acquireTimeout() default -1L;
    boolean autoRelease() default true;
}

Simple Usage

Example controller:

@RestController
@RequestMapping("/mock")
public class MockController {
    @GetMapping("/lockMethod")
    @Lock4j(keys = {"#key"}, acquireTimeout = 1000, expire = 10000)
    public Result lockMethod(@RequestParam String key) {
        ThreadUtil.sleep(5000);
        return Result.OK(key);
    }
}

Calling http://localhost:8080/mock/lockMethod?key=123 returns a successful lock response; if the lock cannot be acquired, a LockFailureException is thrown and can be handled globally.

Advanced Usage

Custom executor:

@Component
public class CustomRedissonLockExecutor extends AbstractLockExecutor {
    @Override
    public Object acquire(String lockKey, String lockValue, long expire, long acquireTimeout) {
        return null;
    }
    @Override
    public boolean releaseLock(String key, String value, Object lockInstance) {
        return false;
    }
}

Custom key builder:

@Component
public class CustomKeyBuilder extends DefaultLockKeyBuilder {
    public CustomKeyBuilder(BeanFactory beanFactory) {
        super(beanFactory);
    }
}

Custom lock‑failure strategy:

@Component
public class GrabLockFailureStrategy implements LockFailureStrategy {
    @Override
    public void onLockFailure(String key, Method method, Object[] arguments) {
        // custom handling
    }
}

Manual lock and release:

@Service
public class LockServiceImpl implements LockService {
    @Autowired
    private LockTemplate lockTemplate;
    @Override
    public void lock(String resourceKey) {
        LockInfo lock = lockTemplate.lock(resourceKey, 10000L, 2000L, CustomRedissonLockExecutor.class);
        if (lock == null) {
            throw new FrameworkException("业务处理中，请稍后再试...");
        }
        try {
            doBusiness();
        } finally {
            lockTemplate.releaseLock(lock);
        }
    }
    private void doBusiness() {
        // TODO business logic
    }
}

This guide provides a complete overview of Lock4j, from basic concepts and configuration to advanced customization, enabling developers to integrate distributed locking into Spring Boot applications efficiently.