Redis를 주 저장소로 사용해 “당일 회의실 예약”을 중복 없이 처리하는 예약 웹 서비스입니다.

• Service: meethub.inwoohub.com
• API Docs (Swagger): Swagger UI

1. 👨‍💻 프로젝트 개요
2. ⚒️ 사용 기술
3. 🌐 아키텍처
4. 🖥️ 화면 구성
5. 📌 주요 기능 설계
6. ⚠️ 트러블슈팅

MeetHub는 칠판에 이름을 적던 회의실 예약을 웹으로 디지털화한 당일 예약 서비스입니다.
Redis를 주 저장소로 사용하고 Hold + Lua 원자 처리 + TTL(자정 만료) 로 중복 예약과 일일 초기화를 해결했습니다.

• 2025.12 ~ 2026.01 (약 1개월)

• 칠판 예약: 현황 공유 어려움, 변경/취소 처리 번거로움
• 동일한 기준으로 예약 현황을 공유할 수 있는 웹 기반 예약 방식 필요

• 칠판 예약을 웹으로 전환하여 당일 예약 현황을 한 화면에서 공유
• 중복 예약/동시성 문제를 0%로 방지하는 예약 확정 로직 구현
• Redis를 주 저장소(Primary Store) 로 사용하며 키 설계/자료구조/TTL 운영 경험
• Hold(선점) 기반 UX와 Lua Script 원자 처리로 안정적인 예약 흐름 구현

MeetHub는 “당일 예약” 특성상 동시성(중복 예약) 제어와 자정 초기화(TTL) 가 핵심입니다.
Redis는 TTL과 Lua Script로 예약 확정 흐름을 단순하게 원자 처리할 수 있어 주 저장소로 선택했습니다.
또한 Redis를 캐시가 아닌 데이터 저장소 관점(키 설계, TTL, 원자 처리) 으로 설계·운영해보는 것을 학습 목표로 포함했습니다.

황인우	김소정
Github	Github
BE & FE	BE & FE
Redis 키 설계(예약/Hold/TTL) Hold(선점) Lua Script(원자 처리) Admin API 전역 예외 처리 배포(Nginx/HTTPS/도메인) FE 보조(UI/연동 일부)	예약 CRUD 예약 화면/플로우 설계 Lua Script(원자 처리) FE 메인(UI/상태관리/연동)

• Hold(String) + Reservation(Hash) 구조로 동시성/만료 정책을 구현했습니다.

• Key: hold:{date}:{slot}:{room} / Type: String / TTL: 300초

• Key: rsv:{date}:{slot} / Type: Hash / Field: room(1~7) / Value: JSON / TTL: 자정 만료

MeetHub API는 에러 응답 포맷을 항상 동일하게 내려주기 위해 전역 예외 처리 구조를 사용합니다.

• Controller/Service에서 예외가 발생해도 한 곳에서 처리
• HTTP 상태코드/에러코드/메시지를 표준화
• 클라이언트는 항상 동일한 JSON 구조 (ErrorResponse)로 에러 처리가 가능

1. ErrorCode (에러 정책 중앙화)

   에러 상황별로 HTTP status + 내부 코드 + 기본 메시지를 enum으로 정의합니다.

   • ex )

   RESERVATION_NOT_FOUND(HttpStatus.NOT_FOUND, "RESERVATION_NOT_FOUND", "예약이 존재하지 않습니다."),

2. ApiException (ErrorCode를 담아 던지는 커스텀 예외) 비즈니스 로직에서 에러가 발생하면 다음처럼 ErrorCode를 포함한 예외를 던집니다.

   • ex )

   throw new ApiException(ErrorCode.RESERVATION_NOT_FOUND);   

3. @RestControllerAdvice (예외 → ErrorResponse 변환) 요청 처리 중 발생한 예외는 DispatcherServlet을 거쳐 전파되고, @RestControllerAdvice의 @ExceptionHandler가 예외를 잡아 ErrorResponse로 매핑합니다.

   • ApiException → ErrorCode를 꺼내서 상태코드/코드/메시지 응답 생성
   • Validation / JSON / 파라미터 누락 등의 스프링 예외도 공통 포맷으로 변환

4. 응답 예시

   {
       "status": 404,
       "code": "HOLD_NOT_FOUND",
       "message": "홀드 키가 존재하지 않습니다.",
       "path": "/api/test/errors/404",
       "timestamp": "2026-01-22T11:34:41.688975599Z",
       "violations": null
   }

• GlobalExceptionHandler.java
• ErrorCode.java
• ApiException.java

사용자가 예약 정보를 입력하는 "작성 단계"에서 동시에 같은 슬롯을 클릭할 수 있기 때문에, 예약 확정 이전에 선점(Hold)을 걸어 중복 예약을 차단합니다. Hold는 Redis의 String + TTL로 구현하며 토큰(token) 으로 소유자를 식별해 타인이 연장/해제하지 못하도록 보호합니다.

• 동일 날짜/슬롯/회의실에 대해 동시에 여러 요청이 와도 1명이 선점
• 작성 중 이탈/방치 케이스는 TTL로 자동 해제하여 자원 회전율 확보
• Hold 소유자만 Refresh/Release 가능 하도록 토큰 검증 적용
• Refresh/Release는 Lua Script로 원자처리 하여 레이드 컨디션 방지

1. Hold Key (String + TTL)
   • Key:hold:{date}:{slot}:{room}
   • Value : token
   • TTL : 300s

2. Acquire Hold (선점 요청)
   • Redis 명령 : SET holdKey token NX EX 300
   • NX 조건으로 키가 없을 때만 생성되므로 이미 누군가 선점 중이면 실패합니다.
   • 실패 시 409 HOLD_CONFLICT 로 응답합니다.

3. Refresh Hold (선점 연장)
   • 작성 시간이 더 필요할 때 TTL을 연장합니다.
   • GET과 EXPIRE를 분리하면 중간에 값이 바뀌는 레이스가 발생할 수 있어 Lua Script로 토큰 검증 + TTL 연장을 Redis 내부에서 수행합니다.
   • 반환값 정책
     • 1 → 200 REFRESHED
     • -1 → 404 HOLD_NOT_FOUND (키 없음/만료)
     • 0 → 403 HOLD_FORBIDDEN (토큰 불일치)

4. Release Hold (선점 해제)
   • 취소/뒤로가기 등으로 작성이 중단되면 Hold를 해제합니다.
   • Refresh와 동일하게 Lua Script로 토큰 검증 + DEL을 원자 처리합니다.
   • 반환값 정책
     • 1 → 200 RELEASED
     • -1 → 404 HOLD_NOT_FOUND
     • 0 → 403 HOLD_FORBIDDEN

• HoldRedisScriptConfig.java
• HoldRedisRepository.java
• HoldService.java
• HoldController.java

예약은 Redis를 주 저장소(Primary Store) 로 사용하며, 슬롯 단위 Hash 구조로 예약을 저장합니다.
예약 확정(Create)은 Hold 검증 + 중복 검사 + 저장 + Hold 해제 + TTL이 하나의 트랜잭션이므로, Lua Script로 원자 처리하여 중복 예약을 방지합니다.

• Hold를 선점한 사용자만 예약 확정 가능
• 동일 날짜/슬롯/회의실에 대해 중복 예약 0%
• 예약 데이터는 자정(TTL) 기준 자동 만료되어 일일 초기화 배치 없이 운영
• 비밀번호는 bcrypt hash만 저장하고, 삭제/변경은 비밀번호 검증 필수
• “수정(Update)” 대신 “변경(Change)”을 삭제 + 재생성으로 단순화

1. Reservation Key (Hash + TTL)
   • Key: rsv:{date}:{slot}
   • Type: Hash
   • Field: room (1~7)
   • Value: JSON (password는 bcrypt hash로 저장)
   • TTL: 자정 만료 (다음날 00:00)

2. Create (예약 확정) — Lua Script 원자 처리

   • 처리 흐름

     1. GET holdKey (Hold 존재 확인)
     2. token 검증 (Hold 소유자 확인)
     3. HEXISTS rsvKey room (중복 예약 확인)
     4. HSET rsvKey room json (예약 저장)
     5. DEL holdKey (Hold 해제)
     6. EXPIRE rsvKey ttl (자정 만료 TTL 적용)

   • 반환값 정책

     • 1 → 200 RESERVED (성공)
     • -1 → 404 HOLD_NOT_FOUND (Hold 만료/미생성)
     • 0 → 403 HOLD_FORBIDDEN (토큰 불일치)
     • -2 → 409 RESERVATION_CONFLICT (이미 예약됨)

3. Read (예약 조회)
   • HGETALL rsvKey로 슬롯 전체를 조회한 뒤 name + passwordEncoder.matches 조건을 만족하는 예약만 반환합니다.
   • 응답 DTO에는 passwordHash를 포함하지 않습니다.

4. Delete (예약 삭제)
   • 비밀번호 검증은 Java에서 수행하고, Redis에서는 Lua Script로 (존재 확인 + HDEL)을 원자적으로 처리합니다.

5. Change (시간/회의실 변경)
   • slot/room 변경은 Key/Field 이동이 필요해 단일 Update로 처리하면 복잡도가 증가합니다.
   • 따라서 Change는 삭제 + 재예약 모델로 단순화했습니다.
     • (1) 기존 예약 조회 + 비밀번호 검증
     • (2) 기존 예약 삭제
     • (3) 새 슬롯/회의실에 대해 Hold → Create 흐름으로 재예약

• ReservationRedisScriptConfig.java
• ReservationRedisRepository.java
• ReservationService.java
• ReservationController.java

관리자 기능은 운영 중 발생하는 예약/취소 상황에 대응하기 위해 예약 현황 조회 및 강제 취소 API를 제공합니다. 관리자 인증은 DB없이 환경 변수 기반 로그인 + Redis 토큰으로 단순화하여 운영 편의성을 확보했습니다.

• 운영 목적상 관리자 전용 조회/강제 취소 기능 제공
• 관리자 계정은 DB가 아닌 환경변수(ADMIN_NAME / ADMIN_PASSWORD) 로 관리
• 로그인 성공 시 Redis에 토큰을 발급/저장하고, 이후 요청은 X-Admin-Token 헤더로 검증
• 만료/위조 토큰은 401 UNAUTHORIZED로 차단하여 관리자 API를 보호

1. Admin Login (ENV 기반 인증 + 토큰 발급)
   • POST /api/admin/login에서 {name, password}를 입력받아 환경변수와 비교해 검증합니다.
   • 성공 시 UUID 토큰을 발급하고 Redis에 저장한 뒤 { role: "admin", token }을 반환합니다.

2. Admin Token (Redis String + TTL)
   • Key: admin:token:{token}
   • Type: String
   • Value: "true" (키 존재 여부만 필요)
   • TTL: 12시간

3. Admin API Guard (헤더 검증)
   • 관리자 API 요청 시 X-Admin-Token: {token} 헤더를 요구합니다.
   • 검증 성공 시 관리자 전용 API를 수행합니다.
     • readAll: 슬롯 전체 예약 조회
     • forceDelete: 특정 예약 강제 취소
     • readRoomAllSlots: 특정 회의실의 하루 전체 슬롯 조회

• ReservationService.java
• AdminService.java
• AdminController.java

// 저장
redis.opsForValue().set(PREFIX + token, "true", TTL);

// 검증
Boolean.TRUE.equals(redis.hasKey(PREFIX + token));

public HoldRedisRepository(
        StringRedisTemplate redis,
        DefaultRedisScript<Long> holdRefreshScript
) {
    this.redis = redis;
    this.holdRefreshScript = holdRefreshScript;
}

@Configuration
public class RedisConfig {

    @Bean(name = "holdRefreshScript")
    public RedisScript<Long> holdRefreshScript() {
        String lua = """
            local v = redis.call('GET', KEYS[1])
            if not v then return -1 end
            if v ~= ARGV[1] then return 0 end
            redis.call('EXPIRE', KEYS[1], tonumber(ARGV[2]))
            return 1
        """;
        DefaultRedisScript<Long> script = new DefaultRedisScript<>();
        script.setScriptText(lua);
        script.setResultType(Long.class);
        return script;
    }
}

@Repository
public class HoldRedisRepository {

    private final StringRedisTemplate redis;
    private final RedisScript<Long> holdRefreshScript;

    public HoldRedisRepository(
            StringRedisTemplate redis,
            @Qualifier("holdRefreshScript") RedisScript<Long> holdRefreshScript
    ) {
        this.redis = redis;
        this.holdRefreshScript = holdRefreshScript;
    }
}

boolean holdExists = repo.existsHold(holdKey);
boolean reservationExists = reservationRepo.getReservation(rsvKey, room).isPresent();
boolean blocked = holdExists || reservationExists;

// 이름 불일치 → skip
if (!r.name().equals(name)) return null;

// 비밀번호 불일치 → skip
if (!passwordEncoder.matches(password, r.passwordHash())) return null;