주니어 백엔드 개발자가 반드시 알아야 할 실무 지식 ‐ DB로 분산 잠금 구현하기 - thought-corner/backend-roadmap GitHub Wiki

/**
 * 분산 잠금 정보를 저장하는 {@code distributed_lock} 테이블에 대한 접근을 담당한다.
 *
 * <p>이 저장소는 잠금의 <b>상호배제</b>를 두 가지 DB 성질에 의존해 구현한다.
 * <ul>
 *   <li>{@code lock_key} 컬럼의 <b>유니크 제약</b> — 동시에 INSERT해도 하나만 성공한다.</li>
 *   <li>{@code SELECT ... FOR UPDATE}의 <b>행 단위 선점 잠금</b> — 같은 키에 대한
 *       동시 획득 시도를 직렬화하여 조건 분기를 원자적으로 수행한다.</li>
 * </ul>
 *
 * <p>모든 메서드는 호출하는 서비스의 트랜잭션 경계 안에서 실행되어야 한다.
 */
@Repository
@RequiredArgsConstructor
public class DistributedLockRepository {

    private final JdbcTemplate jdbc;

    /**
     * 주어진 키의 잠금 행을 <b>선점 잠금(FOR UPDATE)</b>으로 조회한다.
     *
     * <p>행이 존재하면 이 트랜잭션이 커밋/롤백될 때까지 다른 트랜잭션의 동일 행
     * 접근을 차단한다. 이 차단 덕분에 이후의 owner/expiry 판단이 경쟁 없이
     * 원자적으로 이뤄진다.
     *
     * @param lockKey 잠글 대상 식별자 (예: {@code "order:1234"})
     * @return 잠금 행. 아직 아무도 만든 적 없으면 {@code null}
     */
    public LockRow selectForUpdate(String lockKey) {
        List<LockRow> rows = jdbc.query(
            "SELECT lock_key, owner_id, fence_token, expires_at " +
            "FROM distributed_lock WHERE lock_key = ? FOR UPDATE",
            (rs, i) -> new LockRow(
                rs.getString("lock_key"),
                rs.getString("owner_id"),
                rs.getLong("fence_token"),
                rs.getTimestamp("expires_at").toLocalDateTime()),
            lockKey);
        return rows.isEmpty() ? null : rows.get(0);
    }

    /**
     * 잠금 행이 없을 때 새 행을 삽입하여 잠금을 신규 획득한다.
     *
     * <p>선점 잠금은 <b>존재하지 않는 행</b>을 잠글 수 없으므로, 두 트랜잭션이
     * 동시에 "행 없음"으로 판단하고 함께 INSERT를 시도할 수 있다. 이때
     * 유니크 제약이 최종 안전망 역할을 하며, 진 쪽은 {@link DuplicateKeyException}을
     * 받아 {@code false}로 처리된다.
     *
     * @param key    잠금 키
     * @param owner  잠금 보유자 식별자 (인스턴스ID + 스레드ID 등)
     * @param token  이번에 발급한 펜싱 토큰
     * @param expiry 만료 시각(TTL)
     * @return 삽입 성공 시 {@code true}, 유니크 충돌로 경쟁에서 패배하면 {@code false}
     */
    public boolean insert(String key, String owner, long token, LocalDateTime expiry) {
        try {
            jdbc.update(
                "INSERT INTO distributed_lock(lock_key, owner_id, fence_token, expires_at) " +
                "VALUES (?, ?, ?, ?)", key, owner, token, expiry);
            return true;
        } catch (DuplicateKeyException e) {
            return false;
        }
    }

    /**
     * 기존 잠금 행의 소유자·펜싱 토큰·만료 시각을 갱신한다.
     *
     * <p>두 상황에서 호출된다.
     * <ul>
     *   <li>만료된 남의 락을 <b>뺏을 때</b> — owner와 token을 새 값으로 교체</li>
     *   <li>내 락의 TTL을 <b>연장할 때</b> — 기존 token을 유지한 채 expiry만 갱신</li>
     * </ul>
     *
     * @param key    잠금 키
     * @param owner  갱신 후 소유자
     * @param token  갱신 후 펜싱 토큰
     * @param expiry 새 만료 시각
     */
    public void update(String key, String owner, long token, LocalDateTime expiry) {
        jdbc.update(
            "UPDATE distributed_lock SET owner_id = ?, fence_token = ?, expires_at = ? " +
            "WHERE lock_key = ?", owner, token, expiry, key);
    }

    /**
     * 잠금을 해제한다. <b>반드시 {@code owner} 조건을 함께 걸어</b> 자신이 보유한
     * 락만 삭제한다.
     *
     * <p>owner 조건이 없으면, 내 락이 TTL 만료로 이미 다른 프로세스에게 넘어간 뒤
     * 뒤늦게 해제를 호출했을 때 <b>남의 락을 삭제</b>하는 사고가 발생한다.
     *
     * @param key   잠금 키
     * @param owner 해제를 시도하는 소유자 식별자
     * @return 삭제된 행 수. {@code 0}이면 이미 내 락이 아니었음을 의미
     */
    public int delete(String key, String owner) {
        return jdbc.update(
            "DELETE FROM distributed_lock WHERE lock_key = ? AND owner_id = ?", key, owner);
    }
}

/**
 * DB 기반 분산 잠금의 획득·해제를 담당하는 서비스.
 *
 * <p>{@link #tryAcquire(String, String)}는 다음 알고리즘을 하나의 트랜잭션 안에서
 * 수행한다.
 * <ol>
 *   <li>트랜잭션 시작 ({@link Transactional})</li>
 *   <li>선점 잠금 쿼리로 대상 행 점유</li>
 *   <li>행이 없으면 INSERT로 신규 획득</li>
 *   <li>owner가 다르고 아직 만료 전이면 획득 실패</li>
 *   <li>owner가 다르지만 만료됐으면 소유자·만료를 교체하고 획득(뺏기)</li>
 *   <li>owner가 같으면 만료만 갱신하고 획득(재진입/heartbeat)</li>
 *   <li>정상 종료 시 커밋되어 결과가 확정</li>
 *   <li>커밋 실패(롤백) 시 획득도 실패로 간주</li>
 * </ol>
 */
@Service
@RequiredArgsConstructor
public class DistributedLockService {

    private final DistributedLockRepository repo;

    /** 잠금의 기본 유효 기간(TTL). 보유자가 죽어도 이 시간이 지나면 회수 가능하다. */
    private static final Duration TTL = Duration.ofSeconds(30);

    /**
     * 잠금 획득을 시도한다.
     *
     * <p>성공하면 이번에 유효한 <b>펜싱 토큰</b>을 반환한다. 호출자는 이 토큰을
     * 임계 영역 내 실제 자원 쓰기에 함께 전달하여, TTL 만료 후 뒤늦게 깨어난
     * 좀비 프로세스의 쓰기를 자원 쪽에서 거부하도록 해야 한다.
     *
     * @param lockKey 잠글 대상 식별자
     * @param owner   호출자 식별자. 인스턴스ID와 스레드ID를 조합해 전역적으로
     *                유일해야 한다. 재진입 판단의 기준이 된다.
     * @return 획득 성공 시 펜싱 토큰을 담은 {@link Optional}, 실패 시 빈 값
     */
    @Transactional
    public Optional<Long> tryAcquire(String lockKey, String owner) {
        LocalDateTime now = LocalDateTime.now();
        LocalDateTime newExpiry = now.plus(TTL);

        LockRow row = repo.selectForUpdate(lockKey);          // 2

        if (row == null) {                                    // 3: 행 없음 → INSERT
            long token = nextToken();
            boolean ok = repo.insert(lockKey, owner, token, newExpiry);
            return ok ? Optional.of(token) : Optional.empty();
        }

        if (!row.owner().equals(owner)) {                     // owner 다름
            if (row.expiresAt().isAfter(now)) {
                return Optional.empty();                       // 4: 미만료 → 실패
            }
            long token = nextToken();                          // 5: 만료 → 뺏기
            repo.update(lockKey, owner, token, newExpiry);
            return Optional.of(token);
        }

        repo.update(lockKey, owner, row.fenceToken(), newExpiry); // 6: 재진입/heartbeat
        return Optional.of(row.fenceToken());
    }

    /**
     * 자신이 보유한 잠금을 해제한다. 이미 다른 소유자에게 넘어간 경우 아무 일도
     * 일어나지 않는다({@code owner} 조건으로 보호).
     *
     * @param lockKey 잠금 키
     * @param owner   해제를 시도하는 소유자 식별자
     */
    @Transactional
    public void release(String lockKey, String owner) {
        repo.delete(lockKey, owner);
    }

    /**
     * 새 펜싱 토큰을 발급한다.
     *
     * <p><b>단조 증가</b>가 핵심이다. 예시로 현재 밀리초를 쓰지만, 엄밀한 보장이
     * 필요하면 DB 시퀀스나 전용 카운터를 사용해야 한다.
     *
     * @return 이전에 발급한 어떤 토큰보다도 큰 값
     */
    private long nextToken() {
        return System.currentTimeMillis();
    }
}