dicraft-framework-spi-lock

中文文档 ｜ English

distributedLock Tool A declarative distributed lock component based on Redisson, providing method-level distributed locking via annotation + Spring AOP.

Highlights

• Zero Intrusion — Just add @DistributeLock annotation, no boilerplate lock code needed
• SpEL Support — Dynamic lock key resolution via Spring Expression Language
• Flexible Configuration — Annotation-level and global-level config with clear priority chain
• Auto Renewal — Redisson Watchdog enabled by default, no worry about lock expiration
• Observable — Full lifecycle logging for lock acquisition, hold time and release

Quick Start

Add Dependency

<dependency>
    <groupId>cn.dicraft</groupId>
    <artifactId>dicraft-framework-spi-lock</artifactId>
    <version>1.0.1</version>
</dependency>

Usage

@DistributeLock(scene = "order", key = "#orderId")
public void createOrder(String orderId) {
    // business logic
}

More examples

// Scene-only lock (no key), locks on the entire scene
@DistributeLock(scene = "inventory-sync")
public void syncInventory() { ... }

// Custom lease time and wait time
@DistributeLock(scene = "payment", key = "#paymentId", leaseTime = 10000, waitTime = 5000)
public void processPayment(String paymentId) { ... }

Annotation Parameters

Parameter	Type	Default	Description
scene	String	required	Business scene identifier for the lock
key	String	""	Lock key parameter, supports SpEL expression
leaseTime	long	unset	Lock lease time (ms), falls back to global config or default
waitTime	long	unset	Lock wait time (ms), falls back to global config or default

Global Configuration

Configure global lease time, wait time and key prefix in application.yml or application.properties:

dicraft:
  lock:
    lease-time: 30000  # global lock lease time (ms)
    wait-time: 5000    # global lock wait time (ms)
    key-prefix: my-app # global lock key prefix (optional)

Configuration Priority: Annotation > Global Config > Default (-1)

Source	Description
Annotation	@DistributeLock(leaseTime = 10000) — highest priority
Global Config	dicraft.lock.lease-time / dicraft.lock.wait-time — used when annotation value is not set
Default	-1 — enables Watchdog auto-renewal / waits indefinitely

Lock Key Generation

The final lock key format is scene#key, where key is resolved via SpEL. If key is empty, only scene is used as the lock key.

When dicraft.lock.key-prefix is configured, the prefix is prepended with a colon separator:

key-prefix	scene	key	Final Lock Key
(not set)	order	#orderId → 123	order#123
(not set)	order	(empty)	order
my-app	order	#orderId → 123	my-app:order#123
my-app	order	(empty)	my-app:order

This is useful when multiple microservices share the same Redis instance — each service can use its own prefix to avoid lock key collisions.

Locking Strategy

waitTime	leaseTime	Behavior
-1 (default)	-1 (default)	lock() — wait indefinitely + Watchdog auto-renewal
-1 (default)	custom	lock(leaseTime, ms) — wait indefinitely + fixed lease
custom	-1 (default)	tryLock(waitTime, ms) — timed wait + Watchdog renewal
custom	custom	tryLock(waitTime, leaseTime, ms) — timed wait + fixed lease

Prerequisites

• Java 8+
• Spring Context 5.x / 6.X
• Spring Boot 2.x / 3.x (auto-configuration compatible with both)
• Redisson 3.x (requires a RedissonClient bean configured by the user)

License

Copyright 2025 dicraft.

Distributed under the terms of the Apache License 2.0.