🔴 Redis - Lua 스크립트

이전 글을 통해, Redis 에서 Lua 스크립트를 통해 어떠한 점을 해결하고자 하였는지, 적용한 이유에 대해서 알아보았습니다.

이번에는 간단한 Lua 스크립트 문법과 함께 Redis 에서 활용하여 RTT 를 줄이고, 로직을 포함한 데이터 처리를 학습해 보겠습니다.

Lua 문법 치트시트

Lua는 가볍고 배우기 쉬운 스크립트 언어이지만, Java나 JavaScript 같은 C 계열 언어와는 조금 다른 독특한 특징(Gotcha)들이 있습니다.

Redis 스크립트를 짜기 위해 딱 필요한 만큼만 핵심 문법을 요약해 드립니다.

로컬 변수 선언: `local`

Redis Lua 스크립트에서 변수를 선언할 때는 반드시 local 키워드를 사용해야 합니다.

만약 local을 붙이지 않으면 전역(Global) 변수가 되는데, Redis는 스크립트 간의 격리성을 유지하기 위해 전역 변수 생성을 엄격하게 금지(에러 발생)하고 있습니다.

-- ❌ 잘못된 방식 (에러 발생)
my_var = "hello" 

-- ✅ 올바른 방식
local my_var = "hello"
local count = 10

조건문 (`if ~ elseif ~ else ~ end`)

중괄호 { } 대신 then과 end로 블록을 구분합니다.

local score = tonumber(ARGV[1]) -- 파라미터는 문자열로 넘어오므로 숫자로 변환

if score >= 90 then
    return "A"
elseif score >= 80 then
    return "B"
else
    return "C"
end

🚨 주의사항 (Boolean 판별)
Java나 JS와 달리, Lua에서는 nil과 false만 거짓(False)으로 판별합니다.
숫자 0이나 빈 문자열 ""은 참(True)으로 취급되므로 조건문 작성 시 엄청난 주의가 필요합니다!
또한, '같지 않다'는 != 가 아니라 ~= 를 사용합니다.

반복문 (`for` 와 `while`)

배열(Table)을 순회하거나 특정 횟수만큼 반복할 때 사용합니다. (배열 인덱스는 1부터 시작함을 잊지 마세요!)

숫자 기반 반복 (for 초기값, 끝값, 증감폭 do)

local sum = 0
-- 1부터 10까지 1씩 증가하며 반복
for i = 1, 10, 1 do 
    sum = sum + i
end

배열(Table) 순회 (ipairs 사용) KEYS나 ARGV 배열을 순회할 때 가장 많이 사용하는 패턴입니다.

-- ARGV 배열의 모든 요소를 순회
for index, value in ipairs(ARGV) do
    redis.call('SET', 'param:' .. index, value)
end

문자열 합치기 (`..`)

문자열을 결합할 때는 +가 아니라 점 두 개(..)를 사용합니다.

local prefix = "user:"
local user_id = "123"

-- 결과: "user:123"
local redis_key = prefix .. user_id

자료구조: 테이블 (Table)

Lua에는 Array, List, Map, Dictionary 같은 구분이 없습니다.

테이블(Table) 하나로 모든 자료구조를 표현합니다.

{ } (중괄호)를 사용하여 생성합니다.

-- 1. 배열처럼 사용하기 (인덱스는 1부터 시작!)
local my_array = {"apple", "banana", "cherry"}
local first_item = my_array[1] -- "apple"

-- 2. Map(Dictionary)처럼 사용하기
local my_map = { name = "Frank", age = 30 }
local user_name = my_map["name"] -- "Frank"
-- 또는
local user_name2 = my_map.name

형 변환 (`tonumber`, `tostring`)

Redis의 클라이언트에서 넘겨주는 인자(ARGV)는 기본적으로 모두 문자열(String)로 인식됩니다.

숫자로 계산(>, <, + 등)을 해야 한다면 반드시 형 변환을 거쳐야 합니다.

local current_stock = redis.call('GET', KEYS[1])

-- GET 해온 값이 없으면(nil) 0으로 초기화, 있으면 숫자로 변환
if current_stock == false then  -- Redis에서 키가 없으면 Lua에서는 false나 nil로 매핑됨
    current_stock = 0
else
    current_stock = tonumber(current_stock)
end

-- 이제 산술 연산 가능
if current_stock > 0 then
    -- 로직 수행...
end

Redis Lua 스크립트

작성한 Spring Boot 예제는 Github 를 통해 확인하실 수 있습니다.

Spring Data Redis에서 Lua 스크립트를 실행하려면 DefaultRedisScript 객체를 생성하고, RedisTemplate.execute() 메서드를 통해 실행하면 됩니다.

실행 시 가장 중요한 포인트는 KEYS 배열은 List 형태로, ARGV 배열은 가변 인자(Varargs)로 넘겨준다는 점입니다.

// 1. 스크립트 객체 생성 및 반환 타입 지정
DefaultRedisScript<String> setGetScript = new DefaultRedisScript<>();
setGetScript.setScriptText(
    "redis.call('SET', KEYS[1], ARGV[1]) " +
    "return redis.call('GET', KEYS[1])"
);
setGetScript.setResultType(String.class); // 반환 타입 필수 지정

// 2. 스크립트 실행
// execute(스크립트객체, KEYS 리스트, ARGV 값들...)
String result = redisTemplate.execute(
    setGetScript,
    List.of("lua:test:key"), // KEYS[1] 에 매핑
    "lua-value"              // ARGV[1] 에 매핑
);

System.out.println("SET 후 GET 결과: " + result);

💡 참고: KEYS와 ARGV는 선언 없이 어떻게 쓸까?
스크립트를 보면 KEYS나 ARGV 변수를 따로 선언하거나 import 하지 않고 바로 사용하고 있습니다.
이는 Redis 내부에 내장된 Lua 엔진이 스크립트를 실행하기 직전에, 클라이언트(Spring)로부터 넘겨받은 리스트와 파라미터들을 전역 변수(Global Variable) 형태의 테이블(배열)로 알아서 매핑(주입)해 주기 때문입니다.
브라우저의 window 객체나 익스프레스의 req, res 객체처럼 Redis 환경이 알아서 제공하는 내장 객체라고 생각하시면 됩니다!

트랜잭션(MULTI/EXEC) 내부에서는 GET 결과를 즉시 변수에 담아 조건 분기(IF)를 할 수 없었지만,

Lua 스크립트 내부에서는 위 코드처럼 GET 결과를 즉시 가져와 활용할 수 있다는 것이 가장 큰 차이점입니다.

coupon 발급 예제 (선착순 처리)

💡 이전 글 - 쿠폰 발급 실패 예제 확인하기

이전 글에서 파이프라이닝이나 트랜잭션만으로는 선착순 발급 시 발생하는 초과 발급(Race Condition)을 완벽하게 막아낼 수 없음을 확인했습니다.

하지만 Lua 스크립트를 사용하면 "재고 확인(GET) → 조건 분기(IF) → 차감(DECR)" 이라는 3단계 프로세스가 단 하나의 원자적(Atomic) 연산으로 묶이기 때문에, 어떤 스레드도 중간에 끼어들 수 없습니다.

50개의 스레드가 동시에 10개의 쿠폰을 두고 경쟁하는 코드를 작성해 보겠습니다.

public void runCouponWithLuaScriptExample() throws InterruptedException {
    int initialCoupon = 10;
    int threadCount = 50;
    
    // 초기 재고 10개 세팅
    redisTemplate.opsForValue().set("coupon:lua:count", String.valueOf(initialCoupon));

    // 재고 확인 + 차감을 하나의 원자적 Lua 스크립트로 처리
    // 반환값: 1 = 발급 성공, 0 = 발급 실패(재고 소진)
    DefaultRedisScript<Long> couponScript = new DefaultRedisScript<>();
    couponScript.setScriptText(
        "local stock = tonumber(redis.call('GET', KEYS[1])) " +
        "if stock == nil or stock <= 0 then " +
        "  return 0 " +         // 재고 소진 시 0 반환
        "end " +
        "redis.call('DECR', KEYS[1]) " +
        "return 1"              // 차감 성공 시 1 반환
    );
    couponScript.setResultType(Long.class);

    AtomicInteger issuedCount = new AtomicInteger(0);
    AtomicInteger failedCount = new AtomicInteger(0);
    
    // 동시성 테스트를 위한 스레드 풀 및 CountDownLatch 세팅
    ExecutorService executor = Executors.newFixedThreadPool(threadCount);
    CountDownLatch ready = new CountDownLatch(threadCount);
    CountDownLatch start = new CountDownLatch(1);
    CountDownLatch done = new CountDownLatch(threadCount);

    for (int i = 0; i < threadCount; i++) {
        executor.submit(() -> {
            ready.countDown();
            try {
                start.await(); // 50개 스레드가 동시에 출발 대기

                // Lua 스크립트 실행
                Long result = redisTemplate.execute(couponScript, List.of("coupon:lua:count"));
                
                if (result != null && result == 1L) {
                    issuedCount.incrementAndGet(); // 발급 성공
                } else {
                    failedCount.incrementAndGet(); // 발급 실패
                }
            } catch (Exception ignored) {
            } finally {
                done.countDown();
            }
        });
    }

    ready.await();
    start.countDown(); // 일제히 시작!
    done.await();
    executor.shutdown();

    String finalCount = redisTemplate.opsForValue().get("coupon:lua:count");
    System.out.printf("발급 성공: %d장, 발급 거부: %d건, 최종 남은 재고: %s%n", 
            issuedCount.get(), failedCount.get(), finalCount);
}

=========Lua Script 로 선착순 쿠폰 발급 (Race Condition 해결)=========
쿠폰 재고: 10, 동시 요청: 50
발급 성공: 10장, 발급 거부: 40건, 최종 재고: 0
→ 정확히 10장만 발급됨. Lua Script 로 Race Condition 완전 해결!

실행 결과

수십, 수백 번을 실행해도 정확히 "발급 성공 10장, 남은 재고 0"이 보장됩니다.

애플리케이션 레벨의 복잡한 분산 락(Distributed Lock) 없이도, 데이터 정합성을 완벽하게 지켜낼 수 있게 되었습니다.

외부 파일(.lua)로 분리하여 관리하기

지금까지는 Java 코드 내부에 문자열(String) 형태로 Lua 스크립트를 작성했습니다.

하지만 실제로 운영할 때 코드가 길어지면 다음과 같은 치명적인 단점이 생깁니다.

가독성 저하: 띄어쓰기나 문자열 이어 붙이기(+) 실수로 인한 에러가 발생하기 쉽습니다.
IDE 지원 불가: IntelliJ 등에서 제공하는 Lua 문법 하이라이팅이나 자동 완성 기능을 전혀 받을 수 없습니다.
재사용성 하락: 동일한 스크립트를 여러 클래스에서 사용하기 번거롭습니다.

Spring은 이를 해결하기 위해 ClassPathResource를 통한 외부 .lua 파일 로드 기능을 제공합니다.

1. 파일 생성 (src/main/resources/scripts/coupon-issue.lua)

IDE의 지원을 받으며 깔끔하게 스크립트 파일만 따로 작성합니다.

반드시는 아니지만, resources의 경로가 기본 classpath 이기 때문에 빌드에 포함됩니다.
다른 경로는 사용하셔도 무관하지만 그 경우에 명시적으로 리소스 경로를 추가해줘야 합니다.

local stock = tonumber(redis.call('GET', KEYS[1]))

if stock == nil or stock <= 0 then
    return 0
end

redis.call('DECR', KEYS[1])
return 1

2. Spring 빈(Bean) 로드 및 실행

코드 내부에서는 setScriptText() 대신 setLocation()을 사용하여 파일을 지정해 주기만 하면 끝입니다!

public void runLuaScriptFromFileExample() {
    // 스크립트 객체 생성 및 리소스 위치 지정
    DefaultRedisScript<Long> couponScript = new DefaultRedisScript<>();
    couponScript.setLocation(new ClassPathResource("scripts/coupon-issue.lua"));
    couponScript.setResultType(Long.class);

    // 실행 방법은 기존과 100% 동일합니다.
    Long issued = redisTemplate.execute(couponScript, List.of("coupon:lua:file:count"));
    
    if (issued != null && issued == 1L) {
        System.out.println("쿠폰 발급 성공!");
    } else {
        System.out.println("쿠폰 재고 소진 ㅠㅠ");
    }
}

[Redis 완전 정복] Redis Lua 스크립트

스택 시리즈🔴 Redis 완전 정복 시리즈 - 자료구조부터 Redis Cluster 까지