ShedLock 함정 모음

1. 개요

Spring @Scheduled 는 레플리카가 둘이면 둘 다 돈다. ShedLock 은 공유 저장소(Redis, DB)에 락을 걸어 한 번만 돌게 한다. 어노테이션 하나로 끝나서 좋은데, “조용히” 라는 단어가 자꾸 따라붙는다. 락이 있으면 본문을 조용히 건너뛴다. 이게 설계 의도이고, 테스트와 만나면 함정이 된다.

---

2. 핵심 내용

2-1. 기본 동작

@Scheduled(cron = "0 * * * * *")
@SchedulerLock(name = "expireReservations", lockAtMostFor = "PT10M", lockAtLeastFor = "PT30S")
public void expireReservations() { ... }

• 실행 전에 name 으로 락을 시도한다. 이미 있으면 본문을 실행하지 않고 정상 종료 한다. 예외 없음. 로그는 DEBUG.
• lockAtMostFor: 잡이 죽어도 이 시간 뒤엔 락이 풀린다. 실행 시간의 상한보다 넉넉하게.
• lockAtLeastFor: 실행이 빨리 끝나도 이 시간은 락을 유지한다. 레플리카 간 시계 차이로 같은 cron 이 두 번 도는 것을 막는다.

2-2. 함정 1: 테스트가 프록시 빈을 직접 호출한다

통합테스트가 간헐적으로 실패했다. expected: EXPIRED but was: WAITLISTED. 재실행하면 통과. 세 겹이었다.

1. 테스트 프로파일에서 @EnableScheduling 이 두 곳에 있어 한쪽만 꺼도 진짜 cron 이 스위트 중에 돈다.
2. 그 cron 이 lockAtLeastFor = PT30S 짜리 락을 잡는다. 실행은 3ms 지만 락은 30초.
3. 테스트가 @Autowired 로 받은 스케줄러 빈은 ShedLock 프록시 다. 그 30초 안에 테스트가 scheduler.expireReservations() 를 부르면 프록시가 “락 있음” 으로 본문을 건너뛴다.

테스트는 본문이 돌았다고 믿고 결과를 단언한다. 본문은 안 돌았다. 실패. 확률은 30초 창 / 스위트 길이 ≈ 10%. 딱 “가끔”.

// 프록시를 벗겨 본문을 직접 호출
ReservationScheduler target = AopTestUtils.getTargetObject(schedulerBean);
target.expireReservations();

또는 테스트 프로파일에서 @EnableScheduling 을 확실히 끄고(두 곳 모두), ShedLock 을 @Profile("!test") 로 뺀다. 결정적 재현은 Redis 에 락 키를 미리 심는 것.

배운 것: 실패하지 않고 실행되지 않는 코드 는 catch 에도 로그에도 안 남는다. 그리고 처음 세운 “쿼리 경합” 가설은 틀렸다. 후보 행이 항상 1건인 걸 확인하고 나서야 가설을 버렸다.

2-3. 함정 2: 동적 잡에는 어노테이션이 안 걸린다

SchedulingConfigurer.addTriggerTask() 로 등록한 잡(주기를 런타임에 바꾸는 잡)은 AOP 프록시를 거치지 않는다. @SchedulerLock 을 붙여도 아무 일이 안 일어난다. 조용히. 레플리카 둘이 둘 다 돈다.

// 프로그래밍 방식 락
lockingTaskExecutor.executeWithLock(
    Runnable { syncCalendars() },
    LockConfiguration(Instant.now(), "iCalSync", Duration.ofMinutes(10), Duration.ofSeconds(30))
)

DefaultLockingTaskExecutor 를 빈으로 두고 직접 감싼다. 어노테이션이 안 걸리는 곳은 이것뿐이 아니다. 같은 클래스 안에서 this.method() 로 부르는 것도 프록시를 안 탄다. @Transactional 과 같은 함정.

2-4. 함정 3: lockAtLeastFor 를 길게 잡으면 수동 실행이 막힌다

관리자 화면에 “지금 동기화” 버튼이 있다. 이 버튼이 스케줄러와 같은 락 이름을 쓰면, cron 이 방금 돌아 lockAtLeastFor 창 안이면 버튼이 조용히 아무것도 안 한다. 사용자는 “버튼이 고장났다”.

선택지는 둘이다. 수동 실행은 다른 락 이름을 쓰거나(그러면 cron 과 겹칠 수 있다), 락 획득 실패를 사용자에게 알린다. executeWithLock 의 반환값이나 LockProvider.lock() 의 Optional 이 비었는지 보고 “방금 동기화됐습니다. 잠시 후 다시” 를 띄웠다.

2-5. 함정 4: 락 저장소가 죽으면

Redis 를 락 저장소로 쓰면 Redis 가 죽었을 때 @SchedulerLock 메서드는 예외로 실패 한다. 락을 못 잡으면 실행하지 않는 것이 ShedLock 의 안전 방향이라 맞다. 그런데 Redis 클라이언트의 타임아웃이 기본 60초면, cron 스레드가 60초를 기다린다. 스케줄러 스레드 풀이 작으면 다른 잡도 밀린다. Redis 타임아웃은 짧게(3초).

2-6. 몇 개까지 두나

한 프로젝트에 @SchedulerLock 이 15곳이다. 예약 만료, 노쇼 처리, 알림 리마인더, 외부 데이터 동기화, 파일 정리, 탈퇴 데이터 퍼지, 백필 러너. 락 이름이 15개다. 이름이 겹치면 서로 막는다. 이름 목록을 한 enum 이나 상수 클래스에 모아 중복을 컴파일 시점에 잡는 편이 낫다.

백필처럼 한 번 돌고 끝날 잡은 킬 스위치를 따로 둔다. Redis 에 플래그 키를 두고 잡이 시작할 때 읽는다. 잡이 잘못 돌기 시작했을 때 재배포 없이 멈출 수 있다. dry-run 모드를 먼저 한 바퀴 돌리고 켜는 2단계.

---

3. 마무리

요약

• ShedLock 은 락이 있으면 본문을 조용히 건너뛴다. 예외도 로그도 없다.
• 테스트가 프록시 빈을 부르면 진짜 cron 의 락 창에서 스킵된다. AopTestUtils.getTargetObject 로 벗긴다.
• 동적 잡·this. 호출은 어노테이션이 안 걸린다. LockingTaskExecutor 로 직접.
• 수동 실행 버튼은 락 획득 실패를 사용자에게 말해야 한다.
• 락 저장소 타임아웃은 짧게. 락 이름은 한 곳에 모아 중복을 잡는다.

---