DungeonTalk 데이터베이스 아키텍처

# application-dev.properties # HikariCP Connection Pool Settings (Performance Optimization) spring.datasource.hikari.maximum-pool-size=50 spring.datasource.hikari.minimum-idle=10 spring.datasource.hikari.connection-timeout=10000 spring.datasource.hikari.idle-timeout=300000 spring.datasource.hikari.max-lifetime=600000 spring.datasource.hikari.pool-name=DungeonTalkHikariCP

@MappedSuperclass @EntityListeners(AuditingEntityListener.class) public class BaseEntity { @Id private String id; // UUIDv7 자동 생성 @CreatedDate private Instant createdAt; @LastModifiedDate private Instant updatedAt; @PrePersist public void generateIdIfNull() { if (this.id == null || this.id.isBlank()) { this.id = UuidV7Creator.create(); // UUIDv7 생성 } } }

unix_ts_ms (48비트) + rand_a (12비트) + rand_b (62비트) └─ 시간 기반 정렬 가능 ─┘ └─ 충돌 방지 랜덤 ─┘ 예시: 018d3f5a-3c7e-7000-8000-123456789abc └─ 2025-10-17 10:30:00 UTC ─┘

@Entity @Table(name = "member") public class Member extends BaseEntity { @Column(name = "password", nullable = false) private String password; // BCrypt 암호화 @Column(name = "name", length = 20, unique = true) private String name; // 로그인 ID @Column(name = "nick_name", unique = true) private String nickName; // 게임 내 닉네임 }

@Entity @Table(name = "auth") public class Auth extends BaseEntity { @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "member_id") private Member member; @Column(name = "email", length = 50) private String email; @Column(name = "access_token", columnDefinition = "text") private String accessToken; @Column(name = "refresh_token", columnDefinition = "text") private String refreshToken; }

// ❌ EAGER Loading (기본값) - N+1 문제 발생 List<Auth> authList = authRepository.findAll(); // SELECT * FROM auth for (Auth auth : authList) { auth.getMember().getName(); // SELECT * FROM member WHERE id = ? (N번 실행!) } // ✅ LAZY Loading + Fetch Join - 1번의 쿼리로 해결 @Query("SELECT a FROM Auth a JOIN FETCH a.member") List<Auth> findAllWithMember(); // SELECT * FROM auth JOIN member ...

1. 기본값을 LAZY로 설정 2. 필요한 경우에만 Fetch Join 사용 3. @EntityGraph로 동적 로딩 제어 연관 관계의 기본 FetchType: - @ManyToOne, @OneToOne: EAGER (기본값 위험!) - @OneToMany, @ManyToMany: LAZY → 모든 관계를 LAZY로 명시하는 것이 안전

@Entity @Table(name = "game_character") public class GameCharacter extends BaseEntity { @Column(name = "member_id") private String memberId; @OneToOne(fetch = FetchType.LAZY) @JoinColumn(name = "member_id", referencedColumnName = "id", insertable = false, updatable = false) private Member member; @Column(name = "race_id") private String raceId; @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "race_id", referencedColumnName = "id", insertable = false, updatable = false) private RaceStats raceStats; // 스탯 필드들 private Integer strength; private Integer willpower; private Integer intelligence; private Integer wisdom; private Integer dexterity; private Integer luck; }

-- 문제 상황: 두 개의 필드가 같은 컬럼을 참조 CREATE TABLE game_character ( id VARCHAR(255), member_id VARCHAR(255), -- ← 이 컬럼을 ... ); -- member_id 컬럼을 두 곳에서 사용 1. private String memberId; -- 직접 관리 (INSERT/UPDATE) 2. private Member member; -- 읽기 전용 (JOIN) -- insertable=false, updatable=false: -- "이 연관 관계는 읽기 전용입니다. INSERT/UPDATE 시 무시하세요"

// ✅ 올바른 사용법 GameCharacter character = new GameCharacter(); character.setMemberId("member-123"); // FK 직접 설정 characterRepository.save(character); Member member = character.getMember(); // LAZY 로딩으로 Member 조회 (읽기 전용) // ❌ 잘못된 사용법 character.setMember(member); // insertable=false이므로 DB에 반영 안 됨!

// 1번의 쿼리로 GameCharacter 조회 List<GameCharacter> characters = characterRepository.findAll(); // N번의 추가 쿼리 발생! for (GameCharacter character : characters) { String raceName = character.getRaceStats().getName(); // SELECT * FROM race_stats WHERE id = ? } // 총 쿼리 수: 1 + N (100명이면 101번!)

@Query("SELECT gc FROM GameCharacter gc JOIN FETCH gc.raceStats") List<GameCharacter> findAllWithRaceStats(); // 생성되는 SQL: SELECT gc.*, rs.* FROM game_character gc INNER JOIN race_stats rs ON gc.race_id = rs.id

@EntityGraph(attributePaths = {"member", "raceStats"}) List<GameCharacter> findAll(); // 두 개의 연관 관계를 한 번에 로딩

Before (N+1 발생): - 쿼리 수: 101번 (100명 조회 시) - 응답 시간: ~500ms After (Fetch Join): - 쿼리 수: 1번 - 응답 시간: ~50ms → 90% 성능 향상!

@Document(collection = "chat_messages") @CompoundIndex(name = "room_created_idx", def = "{'roomId': 1, 'createdAt': 1}") public class ChatMessage { @Id private String messageId; // UUIDv7 @Indexed private String roomId; // 채팅방 ID (파티셔닝 키 후보) private String senderId; private String receiverId; private String content; private MessageType type; // JOIN, TALK, LEAVE @CreatedDate private Instant createdAt; @LastModifiedDate private Instant updatedAt; }

// 1. 단일 필드 인덱스 db.chat_messages.createIndex({ "roomId": 1 }) // 2. 복합 인덱스 (쿼리 최적화) db.chat_messages.createIndex({ "roomId": 1, "createdAt": 1 }) // 실제 쿼리: db.chat_messages.find({ roomId: "room-123" }) .sort({ createdAt: -1 }) // 인덱스로 정렬 커버 .limit(50)

@Document(collection = "chat_room_members") public class ChatRoomMember { @Id private String id; @Indexed private String roomId; @Indexed private String memberId; @Enumerated(EnumType.STRING) private Status status; // ONLINE, OFFLINE private Instant joinedAt; private Instant lastSeenAt; }

# Session Valkey - ElastiCache spring.session.store-type=${SPRING_SESSION_STORE_TYPE} spring.data.session.host=${SPRING_DATA_SESSION_HOST} spring.data.session.port=${SPRING_DATA_SESSION_PORT} # Cache Valkey - EC2 로컬 spring.cache.type=${SPRING_CACHE_TYPE} spring.redis.cache.host=${SPRING_REDIS_CACHE_HOST} spring.redis.cache.port=${SPRING_REDIS_CACHE_PORT}

# Lettuce Connection Pool Settings (Performance Optimization) spring.data.redis.lettuce.pool.max-active=50 spring.data.redis.lettuce.pool.max-idle=20 spring.data.redis.lettuce.pool.min-idle=10 spring.data.redis.lettuce.pool.max-wait=3000ms spring.data.redis.timeout=5000ms

@Configuration public class ValkeyConfig { @Value("${spring.data.session.host}") private String sessionRedisHost; @Value("${spring.redis.cache.host}") private String cacheRedisHost; // Session Redis 연결 팩토리 @Bean(name = "sessionRedisConnectionFactory") @Primary public RedisConnectionFactory sessionRedisConnectionFactory() { RedisStandaloneConfiguration config = new RedisStandaloneConfiguration(); config.setHostName(sessionRedisHost); config.setPort(sessionRedisPort); LettuceClientConfiguration.LettuceClientConfigurationBuilder builder = LettuceClientConfiguration.builder() .commandTimeout(Duration.ofSeconds(10)); if (sessionRedisSslEnabled) { builder.useSsl(); // AWS ElastiCache SSL 지원 } return new LettuceConnectionFactory(config, builder.build()); } // Cache Redis 연결 팩토리 @Bean(name = "cacheRedisConnectionFactory") public RedisConnectionFactory cacheRedisConnectionFactory() { RedisStandaloneConfiguration config = new RedisStandaloneConfiguration(); config.setHostName(cacheRedisHost); config.setPort(cacheRedisPort); return new LettuceConnectionFactory(config); } // Session용 RedisTemplate @Bean(name = "sessionRedisTemplate") public RedisTemplate<String, String> sessionRedisTemplate( @Qualifier("sessionRedisConnectionFactory") RedisConnectionFactory factory) { RedisTemplate<String, String> template = new RedisTemplate<>(); template.setConnectionFactory(factory); template.setKeySerializer(new StringRedisSerializer()); template.setValueSerializer(new StringRedisSerializer()); return template; } }

// ❌ 여러 Bean이 있을 때 자동 주입 실패 @Autowired private RedisConnectionFactory connectionFactory; // 어떤 Factory를 주입할지 모호! // ✅ @Qualifier로 명시 @Autowired @Qualifier("sessionRedisConnectionFactory") private RedisConnectionFactory connectionFactory;

@Service @RequiredArgsConstructor public class ChatSessionService { private final ValkeyService valkeyService; private final ChatRoomRepository chatRoomRepository; private final ObjectMapper objectMapper; // ChatConstants에 정의된 상수 private static final int DEFAULT_SESSION_TIMEOUT_SECONDS = 1800; // 30분 /** * 세션 시작 (채팅방 입장) */ @Transactional public ChatSessionDto startSession(String roomId, String memberId, String nickname, String websocketSessionId) { log.info("채팅 세션 시작 요청: roomId={}, memberId={}, nickname={}", roomId, memberId, nickname); // 채팅방 존재 확인 ChatRoom room = chatRoomRepository.findById(roomId) .orElseThrow(() -> new ChatException(ErrorCode.CHAT_ROOM_NOT_FOUND, "roomId=" + roomId)); Instant now = Instant.now(); ChatSessionDto sessionDto = ChatSessionDto.builder() .roomId(roomId) .memberId(memberId) .nickname(nickname) .status(Status.ONLINE) .joinedAt(now) .lastActivity(now) .websocketSessionId(websocketSessionId) .build(); String sessionKey = buildSessionKey(roomId, memberId); // "chat:session:{roomId}:{memberId}" String sessionData = serializeSessionData(sessionDto); log.info("Valkey 세션 저장: sessionKey={}, timeout={}초", sessionKey, DEFAULT_SESSION_TIMEOUT_SECONDS); valkeyService.setWithExpiration(sessionKey, sessionData, DEFAULT_SESSION_TIMEOUT_SECONDS); return sessionDto; } /** * 세션 연장 (활동 시간 갱신) */ public void extendSession(String roomId, String memberId) { String sessionKey = buildSessionKey(roomId, memberId); if (!valkeyService.exists(sessionKey)) { log.warn("세션 연장 실패 - 세션이 존재하지 않음: roomId={}, memberId={}", roomId, memberId); return; } try { // 기존 세션 데이터 조회 String sessionData = valkeyService.get(sessionKey); ChatSessionDto sessionDto = objectMapper.readValue(sessionData, ChatSessionDto.class); // 마지막 활동 시간 갱신 ChatSessionDto updatedSession = sessionDto.toBuilder() .lastActivity(Instant.now()) .build(); // Valkey에 갱신된 세션 저장 및 TTL 연장 valkeyService.setWithExpiration(sessionKey, serializeSessionData(updatedSession), DEFAULT_SESSION_TIMEOUT_SECONDS); log.debug("채팅 세션 연장: roomId={}, memberId={}", roomId, memberId); } catch (JsonProcessingException e) { log.error("세션 데이터 역직렬화 실패: roomId={}, memberId={}", roomId, memberId, e); } } /** * Heartbeat 처리 (세션 유지) */ public boolean heartbeat(String roomId, String memberId) { String sessionKey = buildSessionKey(roomId, memberId); if (!valkeyService.exists(sessionKey)) { log.warn("Heartbeat 실패 - 세션이 존재하지 않음: roomId={}, memberId={}", roomId, memberId); return false; } // TTL만 연장 (데이터 재전송 없이 효율적) valkeyService.expire(sessionKey, DEFAULT_SESSION_TIMEOUT_SECONDS); log.debug("Heartbeat 처리: roomId={}, memberId={}", roomId, memberId); return true; } private String buildSessionKey(String roomId, String memberId) { return CHAT_SESSION_PREFIX + roomId + ":" + memberId; // "chat:session:" } }

문제: WebSocket 비정상 종료 시 세션 정리 안 됨 해결: 30분 후 Redis가 자동 삭제 결과: 메모리 누수 없음, 명시적 정리 코드 불필요

// 매번 DB 조회 없이 Redis 존재 여부로 판단 if (!valkeyService.exists(sessionKey)) { throw new SessionExpiredException("세션이 만료되었습니다."); }

Heartbeat 처리: Before: Session 데이터 전체 재전송 (1KB × 1000명 = 1MB/30초) After: EXPIRE 명령만 전송 (1B × 1000명 = 1KB/30초) → 네트워크 트래픽 감소

@Configuration @EnableCaching public class CaffeineCacheConfig { @Bean @Primary public CacheManager caffeineCacheManager() { CaffeineCacheManager cacheManager = new CaffeineCacheManager("worldTypes", "chatRooms"); cacheManager.setCaffeine(Caffeine.newBuilder() .maximumSize(100) // 최대 100개 항목 .expireAfterWrite(1, TimeUnit.HOURS) // 1시간 후 만료 .recordStats()); // 캐시 통계 수집 return cacheManager; } }

/** * 모든 활성화된 WorldType 엔티티 조회 (내부 서비스 간 호출용) * Caffeine 로컬 캐시 적용: 1시간 동안 메모리에 캐시 유지 */ @Cacheable(value = "worldTypes", key = "'activeWorldTypes'") public List<WorldType> findAllActiveWorldTypeEntities() { log.info("DB에서 활성화된 세계관 목록 조회 (캐시 미스)"); return worldTypeRepository.findActiveWorldTypesOrderBySortOrder(); } // 실제 Repository 쿼리: @Query("SELECT w FROM WorldType w WHERE w.isActive = true ORDER BY w.sortOrder ASC, w.id ASC") List<WorldType> findActiveWorldTypesOrderBySortOrder(); // 성능 비교: Before (DB 직접 조회): - 응답 시간: ~50ms - 동시 요청 시 DB 부하 증가 After (Caffeine Cache): - 응답 시간: ~0.1ms (500배 향상) - 서버 시작 후 1번만 DB 조회

// 문제 상황 (docs/worldtypes-query-optimization.md 참고) // 서버 시작 시 여러 스레드가 동시에 DB 조회 public List<WorldType> getAllActiveWorldTypes() { if (cachedActiveWorldTypes == null || isExpired()) { // 여러 스레드가 동시에 이 체크를 통과! cachedActiveWorldTypes = worldTypeRepository.findActiveWorldTypesOrderBySortOrder(); // DB 쿼리 3번 실행됨! } return cachedActiveWorldTypes; } // 해결: Caffeine 캐시 사용 @Cacheable(value = "worldTypes", key = "'activeWorldTypes'") public List<WorldType> findAllActiveWorldTypeEntities() { log.info("DB에서 활성화된 세계관 목록 조회 (캐시 미스)"); // Caffeine이 내부적으로 동기화 처리 // 첫 요청만 DB 조회, 나머지는 대기 후 캐시 반환 return worldTypeRepository.findActiveWorldTypesOrderBySortOrder(); }