README "JDK 1.8+ up to the latest version", pom.xmlmaven.compiler.release=8
Redis 지원
3.0 ~ 최신
README
Valkey 지원
7.2.5 ~ 최신
README
라이선스
Apache License 2.0 — 변경 없음
pom.xml<licenses> = "Apache v2"
상용 에디션
Redisson PRO (pro.redisson:redisson) 별도 존재 — 4.x에서 새로 생긴 것 아님
공식 docs
주의: 4.x는 Java 버전 상향을 요구하지 않는다. "메이저 버전 올리면 Java 17 필요하겠지"라는 가정으로 JDK를 먼저 올리지 말 것. 다만 Spring Boot 4.x 스타터를 함께 쓴다면 Spring Boot 4.x가 요구하는 JDK(17 이상)를 따라야 한다 — 제약의 출처는 Redisson이 아니라 Spring Boot다.
주의: 라이선스는 Apache 2.0 그대로다. 단, 일부 신규 기능은 커뮤니티 에디션에 없다(§8 참조). 릴리스 노트 헤드라인 기능을 무료 에디션 기준으로 착각하지 말 것.
Spring Boot 호환
redisson-spring-boot-starter는 Spring Boot 1.3.x ~ 4.1.x를 커버하며, 스타터 아티팩트는 가장 최신 Spring Boot에 맞는 redisson-spring-data-XX 모듈을 기본 번들한다.
주의: "Redisson 4.x = Spring Boot 4.x 필수"가 아니다. Spring Boot 3.x에 머문 채 Redisson만 4.x로 올리는 것이 가능하며, 이 경우 스타터가 끌어오는 redisson-spring-data-41을 exclude하고 자기 Boot 버전에 맞는 모듈을 직접 선언해야 한다(§2 참조). 이것을 놓치면 Spring Data Redis 4.1 클래스가 클래스패스에 섞여 NoSuchMethodError/ClassNotFoundException이 런타임에 터진다.
Spring Boot 3.x 유지 + Redisson만 4.x로 (실무에서 가장 흔한 조합)
<dependency><groupId>org.redisson</groupId><artifactId>redisson-spring-boot-starter</artifactId><version>4.7.0</version><exclusions><exclusion><groupId>org.redisson</groupId><artifactId>redisson-spring-data-41</artifactId><!-- Boot 4.1용 기본 번들 제거 --></exclusion></exclusions></dependency><dependency><groupId>org.redisson</groupId><artifactId>redisson-spring-data-35</artifactId><!-- Spring Boot 3.5 --><version>4.7.0</version></dependency>
Spring Cache / Spring Transaction을 쓴다면 — 별도 의존성 필수 (4.1.0 변경)
스타터 pom.xml은 redisson-spring-cache·redisson-spring-transaction을 <optional>true</optional>로 선언한다. optional 의존성은 하위 프로젝트로 전이(transitive)되지 않으므로, 스타터만 넣으면 RedissonSpringCacheManager를 찾을 수 없다.
<!-- @EnableCaching + RedissonSpringCacheManager 사용 시 --><dependency><groupId>org.redisson</groupId><artifactId>redisson-spring-cache</artifactId><version>4.7.0</version></dependency><!-- RedissonTransactionManager 사용 시 --><dependency><groupId>org.redisson</groupId><artifactId>redisson-spring-transaction</artifactId><version>4.7.0</version></dependency>
주의: 3.x에서 4.x로 올린 직후 가장 많이 터지는 컴파일 에러가 RedissonSpringCacheManager / RedissonTransactionManager **미해결(cannot find symbol)**이다. 코드가 잘못된 게 아니라 모듈이 분리된 것이다(4.1.0).
주의: BaseConfig의 이동 대상 setter들은 제거된 게 아니라 @Deprecated로 남아 있다. 그래서 3.x 코드가 컴파일은 그대로 통과한다. "빌드 됐으니 마이그레이션 끝"이라고 판단하면 안 된다 — 특히 YAML 설정 파일은 컴파일 대상이 아니므로 조용히 무시되거나 파싱 오류로 기동 시점에 터진다. §4의 설정 파일 이관을 반드시 수행한다.
다수 인스턴스가 동시에 재접속을 시도하는 클러스터/장애복구 상황에서는 ConstantDelay보다 jitter 계열을 쓴다.
4-2. YAML 설정 파일 — 최상위 레벨로 키 이동
# ❌ 3.x — 인증/ssl/tcp 키가 서버 블록 안에 있음singleServerConfig:address:"redis://127.0.0.1:6379"username:"app"password:${REDIS_SECRET}tcpNoDelay:truesslVerificationMode:"STRICT"connectionPoolSize:64timeout:3000codec:!<org.redisson.codec.Kryo5Codec> {}
# ✅ 4.x — 인증/ssl/tcp/nameMapper 는 루트 레벨singleServerConfig:address:"redis://127.0.0.1:6379"database:0connectionPoolSize:64connectionMinimumIdleSize:24subscriptionConnectionPoolSize:50idleConnectionTimeout:10000connectTimeout:10000timeout:3000retryAttempts:3username:"app"password:${REDIS_SECRET}tcpNoDelay:truesslVerificationMode:"STRICT"codec:!<org.redisson.codec.Kryo5Codec> {}
threads:16nettyThreads:32
spring:data:redis:# Spring Boot 3.x·4.x 공통 (Boot 2.7 이하는 spring.redis.*)host:localhostport:6379redis:redisson:file:classpath:redisson.yaml# ← 4.x에서도 그대로 spring.redis.redisson.*
주의: Redisson 전용 키는 4.x에서도 여전히 spring.redis.redisson.config / spring.redis.redisson.file 두 개뿐이다(@ConfigurationProperties(prefix = "spring.redis.redisson")). spring.data.redis.redisson.*로 옮기면 조용히 무시된다 — 3.x와 동일한 함정이다.
// ❌ 4.0.0에서 제거된 Redisson 자체 Spring Session 구현// (org.redisson.spring.session.* 기반 설정)// ✅ 표준 spring-session-data-redis 사용 + RedissonConnectionFactory@EnableRedisHttpSession@ConfigurationpublicclassSessionConfig { }
redisson-spring-data-XX가 제공하는 RedissonConnectionFactory가 spring-session-data-redis의 백엔드로 동작한다.
주의: getMapCacheNative()·getMapCacheNativeV2()는 공식 docs 표에서 Redisson PRO 기능으로 표기된다. 커뮤니티 에디션 프로젝트라면 getMapCache()(스크립트 eviction) 또는 TTL 필요 엔트리를 개별 RBucket으로 분리하는 설계를 택한다.
RMap<String, User> users = redisson.getMap("users");
users.put("u1", user); // 이전 값을 반환 → 값 전송 발생
users.fastPut("u1", user); // 이전 값 반환 안 함 → 네트워크 왕복 절약 (반환값 불필요 시 항상 이 쪽)
users.putIfAbsent("u1", user);
Map<String, User> some = users.getAll(Set.of("u1", "u2"));
users.fastRemove("u1", "u2"); // remove()와 달리 이전 값을 가져오지 않음
주의: keySet()·values()·entrySet()는 전체 스캔이다. 대형 맵에서는 keyIterator()·entryIterator() 같은 스트리밍 API를 쓰거나 아예 호출하지 않는다.
Cache-Aside 패턴 (락으로 캐시 스탬피드 방지)
public User findUser(Long id) {
RBucket<User> cache = redisson.getBucket("cache:user:" + id);
Usercached= cache.get();
if (cached != null) return cached;
RLocklock= redisson.getLock("lock:cache:user:" + id);
booleanacquired=false;
try {
acquired = lock.tryLock(2, 5, TimeUnit.SECONDS);
if (!acquired) {
return userRepository.findById(id).orElseThrow(); // 락 실패 시 DB 직행(폴백)
}
Useragain= cache.get(); // 이중 확인 — 대기 중 다른 스레드가 채웠을 수 있음if (again != null) return again;
Userloaded= userRepository.findById(id).orElseThrow();
cache.set(loaded, Duration.ofMinutes(10));
return loaded;
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
thrownewIllegalStateException(e);
} finally {
if (acquired && lock.isHeldByCurrentThread()) lock.unlock();
}
}
주의: 코덱 교체는 저장 포맷 변경이다. 이미 Redis에 들어 있는 값은 새 코덱으로 역직렬화되지 않는다. 마이그레이션 시 ① 캐시성 데이터는 키 프리픽스를 바꿔 자연 소멸시키거나 ② 영속 데이터는 이관 배치를 돌린다. 무중단 배포 중 두 버전이 공존하면 양쪽 다 깨진다 — 프리픽스 분리가 가장 안전하다.
8. 4.x 신규 기능 (커뮤니티/PRO 구분 주의)
기능
버전
에디션
Reliable Pub/Sub (RReliablePubSubTopic, subscription/consumer, ACK, Dead Letter Topic, seek/replay)
4.0.0
PRO 전용 — docs 명시 "This feature is available only in Redisson PRO edition"
Spring Boot 4.0 / Spring Data Redis 4.0 모듈, Quarkus 3.30.x
4.0.0
커뮤니티
Spring AI Vector Store, Jackson3 코덱군, RBloomFilterNative(BF.*)
4.2.0
커뮤니티
JMS API 구현, RCuckooFilter
4.3.0
커뮤니티
GCRA Rate Limiter, Non-Reentrant Lock, Hibernate 7.3.x, io_uring 전송
4.4.0
커뮤니티
Micronaut 5.0, Array/BitVector Store 컬렉션
4.5.0
커뮤니티
T-digest / Top-k 확률형 자료구조, Spring Boot·Data Redis 4.1
4.6.0
커뮤니티
RMaps(벌크 맵 연산), 배열 기반 Circular Buffer, @RGetter/@RSetter
4.7.0
커뮤니티
주의: 릴리스 노트 헤드라인 기능이라도 PRO 전용일 수 있다. 특히 Reliable Pub/Sub는 4.0의 대표 기능이지만 커뮤니티 에디션에서는 쓸 수 없다. 커뮤니티에서 신뢰성 있는 메시징이 필요하면 RStream(Redis Streams) + consumer group을 사용한다.
9. 커넥션 풀 설정
SingleServerConfig의 풀 관련 setter는 4.x에서 변경·deprecated 없음.
singleServerConfig:address:"redis://127.0.0.1:6379"connectionPoolSize:64# 기본 64connectionMinimumIdleSize:24# 기본 24subscriptionConnectionPoolSize:50# 기본 50subscriptionConnectionMinimumIdleSize:1# 기본 1subscriptionsPerConnection:5idleConnectionTimeout:10000connectTimeout:10000timeout:3000retryAttempts:3pingConnectionInterval:30000dnsMonitoringInterval:5000threads:16# Redisson 작업 스레드nettyThreads:32# Netty I/O 스레드
설정
튜닝 관점
connectionPoolSize
락 대기가 많은 워크로드는 상향. 단, Redis 서버의 maxclients와 인스턴스 수를 곱해 초과하지 않도록
subscriptionConnectionPoolSize
RLock은 pub/sub으로 해제 통지를 받는다. 락 사용량이 많으면 이 풀이 먼저 마른다 → getSpinLock() 검토
pingConnectionInterval
방화벽/LB의 idle 커넥션 끊김 방지. 클라우드 환경에서는 반드시 설정
timeout vs connectTimeout
전자는 명령 응답 대기, 후자는 TCP 연결 수립. 혼동 주의
retryAttempts + retryDelay
retryAttempts × retryDelay가 상위 HTTP 타임아웃을 넘지 않도록 계산
주의: Cluster 모드는 database 인덱스를 쓸 수 없다(Redis Cluster는 DB 0만 허용). 논리 분리는 키 프리픽스나 nameMapper로 한다 — 4.x에서 nameMapper는 Config 최상위에 설정한다.
10. 마이그레이션 체크리스트 (3.x → 4.x)
Spring Boot 버전을 먼저 고정한다 — Boot 3.x 유지면 redisson-spring-data-41exclude + 3X 모듈 명시
redisson-spring-cache / redisson-spring-transaction 의존성 추가 (Spring Cache·Transaction 사용 시)
.json Redisson 설정 파일 → YAML 변환
YAML의 인증·ssl*·tcp*·nameMapper 키를 루트 레벨로 이동
Java Config의 useXxxServer().setPassword/setSsl*/setTcp* → config.setXxx()로 이동
