프로젝트를 통해 공부한 클린 코드 & 클린 아키텍처

src/main/java ├── controller/ │ ├── MatchingController │ ├── ChatController │ └── RoomController ├── service/ │ ├── MatchingService │ ├── ChatService │ └── RoomService └── repository/ └── ...

src/main/java/org/com/dungeontalk ├── domain/ │ ├── matching/ # 매칭 도메인 │ │ ├── controller/ │ │ ├── service/ │ │ ├── dto/ │ │ ├── factory/ │ │ └── util/ │ ├── chat/ # 채팅 도메인 │ │ ├── controller/ │ │ ├── service/ │ │ ├── entity/ │ │ └── repository/ │ └── room/ # 룸 도메인 │ ├── controller/ │ ├── service/ │ └── dto/ └── global/ # 공통 기능 ├── exception/ ├── config/ └── security/

@Service @RequiredArgsConstructor public class MatchingService { private final MatchingQueueManager queueManager; private final AiGameRoomService aiGameRoomService; private final ChatRoomService chatRoomService; private final StringRedisTemplate redisTemplate; private final MatchingWebSocketService webSocketService; private final RoomServiceFactory roomServiceFactory;

/** * 통합된 룸 서비스 인터페이스 * AI 게임룸과 플레이어 채팅룸의 공통 기능을 정의 */ public interface RoomService { /** * 이 서비스가 지원하는 룸 타입 */ RoomType getSupportedRoomType(); /** * 새로운 룸을 생성한다 */ UnifiedRoomResponse createRoom(UnifiedRoomRequest request); /** * 룸에 참여한다 */ UnifiedRoomResponse joinRoom(String roomId, String memberId); /** * 룸에서 퇴장한다 */ UnifiedRoomResponse leaveRoom(String roomId, String memberId); }

/** * AI 게임룸 서비스 어댑터 * 기존 AiGameRoomService를 RoomService 인터페이스에 맞게 래핑 */ @Service @RequiredArgsConstructor public class AiGameRoomServiceAdapter implements RoomService { private final AiGameRoomService aiGameRoomService; private final AiGameMessageService aiGameMessageService; @Override public RoomType getSupportedRoomType() { return RoomType.AI_GAME; } @Override public UnifiedRoomResponse createRoom(UnifiedRoomRequest request) { // UnifiedRoomRequest -> AiGameRoomCreateRequest 변환 AiGameRoomCreateRequest aiRequest = AiGameRoomCreateRequest.builder() .gameId(request.getGameId()) .roomName(request.getRoomName()) .maxParticipants(request.getMaxParticipants()) .gameSettings(request.getGameSettings()) .creatorId(request.getCreatorId()) .build(); // 기존 서비스 호출하여 결과 반환 AiGameRoomResponse aiResponse = aiGameRoomService.createAiGameRoom(aiRequest); // AiGameRoomResponse -> UnifiedRoomResponse 변환 return UnifiedRoomResponse.fromAiGameRoom(aiResponse); } }

/** * 채팅룸 서비스 어댑터 * 기존 ChatRoomService를 RoomService 인터페이스에 맞게 래핑 */ @Service @RequiredArgsConstructor public class ChatRoomServiceAdapter implements RoomService { private final ChatRoomService chatRoomService; private final ChatMessageService chatMessageService; @Override public RoomType getSupportedRoomType() { return RoomType.PLAYER_CHAT; } @Override public UnifiedRoomResponse createRoom(UnifiedRoomRequest request) { // UnifiedRoomRequest -> ChatRoomCreateRequestDto 변환 ChatRoomCreateRequestDto chatRequest = ChatRoomCreateRequestDto.builder() .roomName(request.getRoomName()) .mode(request.getChatMode()) .maxCapacity(request.getMaxCapacity()) .build(); // 기존 서비스 호출 ChatRoomDto room = chatRoomService.createRoom(chatRequest); // ChatRoomDto -> UnifiedRoomResponse 변환 return UnifiedRoomResponse.fromChatRoom(room); } }

// ❌ 하나의 클래스가 너무 많은 책임을 가진 경우 public class MatchingService { // 매칭 로직 public void processMatching() { } // 대기 시간 계산 (다른 책임!) public String calculateWaitTime(int position) { } // 방 생성 (또 다른 책임!) public Room createRoom() { } // WebSocket 알림 (또 다른 책임!) public void sendNotification() { } }

/** * 매칭 대기 시간 계산 유틸리티 */ @Component @RequiredArgsConstructor public class MatchingTimeCalculator { private final MatchingProperties matchingProperties; /** * 큐 내 위치를 기반으로 예상 대기 시간 메시지 계산 */ public String calculateEstimatedWaitMessage(int position) { if (position <= 1) { return "곧 매칭될 예정입니다"; } else if (position == 2) { int estimatedSeconds = matchingProperties.getTiming().getEstimatedSecondsPerMatch(); return "약 " + estimatedSeconds + "초 후 매칭 예정"; } else { int estimatedMinutes = calculateEstimatedMinutes(position); return "약 " + estimatedMinutes + "분 후 매칭 예정"; } } /** * 현재 대기자 수를 기반으로 큐 상태 메시지 계산 */ public String calculateQueueStatusMessage(int currentWaiting) { if (currentWaiting == 0) { return "대기자 없음"; } else if (currentWaiting <= 2) { return "곧 매칭 가능"; } else { int estimatedMinutes = calculateEstimatedMinutes(currentWaiting); return "약 " + estimatedMinutes + "분 대기"; } } private int calculateEstimatedMinutes(int count) { return (count / MatchingConstants.REQUIRED_PARTICIPANTS) + 1; } }

/** * 룸 서비스 팩토리 * 룸 타입에 따라 적절한 RoomService 구현체를 반환 */ @Component @RequiredArgsConstructor public class RoomServiceFactory { private final List<RoomService> roomServices; // 모든 구현체 자동 주입 private Map<RoomType, RoomService> serviceMap; /** * 팩토리 초기화 * 등록된 모든 RoomService 구현체를 맵에 저장 */ private void initializeServiceMap() { if (serviceMap == null) { serviceMap = roomServices.stream() .collect(Collectors.toMap( RoomService::getSupportedRoomType, Function.identity() )); log.info("RoomServiceFactory 초기화 완료. 등록된 서비스: {}", serviceMap.keySet().stream() .map(RoomType::getDisplayName) .collect(Collectors.joining(", "))); } } /** * 룸 타입에 해당하는 서비스를 반환합니다 */ public RoomService getService(RoomType roomType) { if (roomType == null) { throw new IllegalArgumentException("룸 타입이 null입니다"); } initializeServiceMap(); RoomService service = serviceMap.get(roomType); if (service == null) { throw new IllegalArgumentException( String.format("지원하지 않는 룸 타입입니다: %s", roomType.getDisplayName()) ); } return service; } }

// 1. 먼저 기존 서비스 작성 (또는 이미 존재하는 서비스 활용) @Service public class PvpBattleRoomService { public PvpBattleRoom createBattleRoom(PvpBattleRoomRequest request) { // PVP 배틀룸 생성 로직 } } // 2. Adapter만 추가하면 됨! 기존 코드는 수정 불필요 @Service public class PvpBattleRoomServiceAdapter implements RoomService { private final PvpBattleRoomService pvpBattleRoomService; @Override public RoomType getSupportedRoomType() { return RoomType.PVP_BATTLE; } @Override public UnifiedRoomResponse createRoom(UnifiedRoomRequest request) { // 요청 변환 PvpBattleRoomRequest pvpRequest = convertToPvpRequest(request); // 기존 서비스 호출 PvpBattleRoom battleRoom = pvpBattleRoomService.createBattleRoom(pvpRequest); // 응답 변환 return UnifiedRoomResponse.fromPvpBattleRoom(battleRoom); } }

// 어떤 RoomService 구현체든 동일하게 동작 public void createAndJoinRoom(RoomType roomType, String memberId) { RoomService service = roomServiceFactory.getService(roomType); // AI 게임룸이든, 채팅룸이든 동일한 인터페이스로 사용 UnifiedRoomResponse room = service.createRoom(request); service.joinRoom(room.getRoomId(), memberId); }

// 목적별로 분리된 인터페이스 public interface RoomService { // 필수 메서드만 정의 RoomType getSupportedRoomType(); UnifiedRoomResponse createRoom(UnifiedRoomRequest request); UnifiedRoomResponse getRoom(String roomId); void deleteRoom(String roomId); } // 메시지 처리가 필요한 경우에만 구현 public interface MessageProcessable { void processMessage(UnifiedMessageRequest request); void sendSystemMessage(String roomId, String message); } // 상태 관리가 필요한 경우에만 구현 public interface RoomStateManageable { boolean isRoomActive(String roomId); boolean canJoinRoom(String roomId, String memberId); }

// ❌ 구체 클래스에 직접 의존 @Service public class MatchingService { private final AiGameRoomServiceAdapter aiGameRoomAdapter; private final ChatRoomServiceAdapter chatRoomAdapter; public void createRooms() { // 구체 클래스에 의존하므로 변경에 취약 aiGameRoomAdapter.createRoom(request); chatRoomAdapter.createRoom(request); } }

@Service @RequiredArgsConstructor public class MatchingService { // Factory를 통해 간접적으로 의존 private final RoomServiceFactory roomServiceFactory; public Map<String, String> createUnifiedRooms(String gameSessionId, List<String> participants, WorldType worldType) { Map<String, String> roomIds = new HashMap<>(); // 인터페이스(RoomService)에 의존 RoomService aiRoomService = roomServiceFactory.getService(RoomType.AI_GAME); UnifiedRoomResponse aiRoom = aiRoomService.createRoom(aiRoomRequest); // 인터페이스(RoomService)에 의존 RoomService chatRoomService = roomServiceFactory.getService(RoomType.PLAYER_CHAT); UnifiedRoomResponse chatRoom = chatRoomService.createRoom(chatRoomRequest); return roomIds; } }

// ❌ 조건문 지옥 public Room createRoom(RoomType type) { if (type == RoomType.AI_GAME) { return new AiGameRoom(); } else if (type == RoomType.PLAYER_CHAT) { return new PlayerChatRoom(); } else if (type == RoomType.PVP_BATTLE) { return new PvpBattleRoom(); } // 새 타입 추가할 때마다 이 코드를 수정해야 함! }

/** * 매칭 시스템에서 사용되는 방 생성을 담당하는 Factory 클래스 */ @Component @RequiredArgsConstructor public class MatchingRoomFactory { private final AiGameRoomService aiGameRoomService; private final ChatRoomService chatRoomService; /** * AI 게임방 생성 */ public AiGameRoomResponse createAiGameRoom(RoomCreationContext context) { log.debug("AI 게임방 생성 시작: sessionId={}, worldType={}", context.getGameSessionId(), context.getWorldType()); AiGameRoomCreateRequest request = AiGameRoomCreateRequest.builder() .gameId(context.getGameSessionId()) .roomName(buildAiGameRoomName(context.getWorldType())) .maxParticipants(MatchingConstants.REQUIRED_PARTICIPANTS) .gameSettings(context.getWorldType().getGameSettings()) .creatorId(selectCreator(context.getParticipants())) .build(); AiGameRoomResponse response = aiGameRoomService.createAiGameRoom(request); log.info("AI 게임방 생성 완료: roomId={}, sessionId={}", response.getId(), context.getGameSessionId()); return response; } /** * AI 게임방 이름 생성 */ private String buildAiGameRoomName(WorldType worldType) { return new StringBuilder() .append(worldType.getDisplayName()) .append(" 랜덤 매칭") .toString(); } /** * 방 생성자 선택 (첫 번째 참가자를 생성자로) */ private String selectCreator(List<String> participants) { if (participants == null || participants.isEmpty()) { throw new IllegalArgumentException("참가자 목록이 비어있습니다"); } return participants.get(0); } }

@Getter @Builder public class RoomCreationContext { private String gameSessionId; private List<String> participants; private WorldType worldType; }

RoomCreationContext context = RoomCreationContext.builder() .gameSessionId(sessionId) .participants(participants) .worldType(worldType) .build(); AiGameRoomResponse room = matchingRoomFactory.createAiGameRoom(context);

@Getter @Builder public class MatchingCompleteResponse { private String gameSessionId; private String aiGameRoomId; private String chatRoomId; private WorldType worldType; private List<String> participants; private Instant matchedAt; /** * 정적 팩토리 메서드 + Builder 조합 */ public static MatchingCompleteResponse of(String gameSessionId, String aiGameRoomId, String chatRoomId, WorldType worldType, List<String> participants) { return MatchingCompleteResponse.builder() .gameSessionId(gameSessionId) .aiGameRoomId(aiGameRoomId) .chatRoomId(chatRoomId) .worldType(worldType) .participants(participants) .matchedAt(Instant.now()) // 자동으로 현재 시간 설정 .build(); } }

// 런타임에 전략 선택 RoomService strategy = roomServiceFactory.getService(roomType); UnifiedRoomResponse room = strategy.createRoom(request);

// ❌ 기존 코드를 모두 뜯어고치는 방식 public class AiGameRoomService implements RoomService { // 기존 메서드들을 모두 RoomService 인터페이스에 맞게 수정 // 위험하고 시간 소모적! }

/** * Adapter 패턴: 기존 서비스를 새로운 인터페이스에 맞게 변환 */ @Service @RequiredArgsConstructor public class AiGameRoomServiceAdapter implements RoomService { // 기존 서비스를 그대로 사용 private final AiGameRoomService aiGameRoomService; private final AiGameMessageService aiGameMessageService; @Override public UnifiedRoomResponse createRoom(UnifiedRoomRequest request) { // 1. 새 인터페이스의 요청을 기존 서비스의 요청으로 변환 AiGameRoomCreateRequest aiRequest = AiGameRoomCreateRequest.builder() .gameId(request.getGameId()) .roomName(request.getRoomName()) .maxParticipants(request.getMaxParticipants()) .gameSettings(request.getGameSettings()) .creatorId(request.getCreatorId()) .build(); // 2. 기존 서비스 호출 (수정 없음!) AiGameRoomResponse aiResponse = aiGameRoomService.createAiGameRoom(aiRequest); // 3. 기존 서비스의 응답을 새 인터페이스의 응답으로 변환 return UnifiedRoomResponse.fromAiGameRoom(aiResponse); } }

// RoomServiceFactory가 Adapter들을 관리 RoomService aiRoomService = roomServiceFactory.getService(RoomType.AI_GAME); // 반환되는 것은 AiGameRoomServiceAdapter RoomService chatRoomService = roomServiceFactory.getService(RoomType.PLAYER_CHAT); // 반환되는 것은 ChatRoomServiceAdapter // 클라이언트는 둘 다 RoomService로만 사용 aiRoomService.createRoom(request); chatRoomService.createRoom(request);

// ❌ 오타 가능성, 컴파일 타임 검증 불가 public class MatchingService { public void updateStatus(String status) { if (status.equals("WAITING")) { // 오타 위험! // ... } } }

@Getter @RequiredArgsConstructor public enum MatchingStatus { WAITING("대기중", "매칭 큐에서 대기중"), MATCHED("매칭완료", "매칭이 완료되어 게임방 생성중"), COMPLETED("완료", "게임방 생성 완료"), CANCELLED("취소", "사용자가 매칭을 취소함"), EXPIRED("만료", "대기 시간이 만료됨"), ERROR("오류", "매칭 처리 중 오류 발생"); private final String displayName; private final String description; }

// 컴파일 타임 검증, IDE 자동완성 지원 public void updateStatus(MatchingStatus status) { if (status == MatchingStatus.WAITING) { // ... } }

@Getter @RequiredArgsConstructor public enum ErrorCode { // AI Chat 관련 AI_GAME_ROOM_NOT_FOUND("404-AC01", "AI 게임방을 찾을 수 없습니다"), AI_GAME_ROOM_CANNOT_JOIN("400-AC02", "입장할 수 없는 게임방입니다"), AI_GAME_ROOM_ALREADY_JOINED("400-AC03", "이미 참여중인 게임방입니다"), // 매칭 관련 MATCHING_USER_ALREADY_IN_QUEUE("400-MT01", "이미 매칭 대기 중입니다"), MATCHING_QUEUE_FULL("400-MT02", "매칭 대기열이 가득 찼습니다"), MATCHING_USER_NOT_IN_QUEUE("404-MT03", "매칭 대기 중이 아닙니다"), MATCHING_PROCESSING_ERROR("500-MT04", "매칭 처리 중 오류가 발생했습니다"), // 채팅 관련 CHAT_ROOM_NOT_FOUND("404-CH01", "채팅방을 찾을 수 없습니다"), CHAT_MEMBER_NOT_FOUND("404-CH02", "사용자 정보를 찾을 수 없습니다"), CHAT_CAPACITY_EXCEEDED("409-CH03", "채팅방 정원을 초과했습니다"); private final String errorCode; private final String message; }

// ❌ 생성자: 의미가 불명확 MatchingCompleteResponse response = new MatchingCompleteResponse( sessionId, aiRoomId, chatRoomId, worldType, participants, Instant.now() ); // ✅ 정적 팩토리 메서드: 의도가 명확 MatchingCompleteResponse response = MatchingCompleteResponse.of( sessionId, aiRoomId, chatRoomId, worldType, participants );

@Getter // ✅ Getter만 제공 @Builder public class MatchingCompleteResponse { private String gameSessionId; private String aiGameRoomId; private String chatRoomId; private WorldType worldType; private List<String> participants; private Instant matchedAt; // ❌ Setter 없음 }

@Getter @RequiredArgsConstructor public class AiChatException extends RuntimeException { private final ErrorCode errorCode; public AiChatException(ErrorCode errorCode, String customMessage) { super(customMessage); this.errorCode = errorCode; } public AiChatException(ErrorCode errorCode, Throwable cause) { super(cause); this.errorCode = errorCode; } }

public MatchingStatusResponse joinMatching(String memberId, WorldType worldType) { log.info("매칭 참가 요청: memberId={}, worldType={}", memberId, worldType); // 1. 중복 참가 체크 if (queueManager.isUserInQueue(memberId)) { throw new AiChatException(ErrorCode.MATCHING_USER_ALREADY_IN_QUEUE); } try { // 2. 큐에 사용자 추가 queueManager.addToQueue(memberId, worldType); // ... 비즈니스 로직 return MatchingStatusResponse.of( memberId, worldType, MatchingStatus.WAITING, userPosition, queueSize, Instant.now() ); } catch (Exception e) { log.error("매칭 참가 중 오류 발생: memberId={}, worldType={}", memberId, worldType, e); throw new AiChatException(ErrorCode.MATCHING_PROCESSING_ERROR, e.getMessage()); } }

// ❌ 불명확한 이름 public class Manager { public void process(String data) { // 무엇을 처리하는지 알 수 없음 } }

// ✅ 명확한 이름 public class MatchingQueueManager { public void addToQueue(String memberId, WorldType worldType) { // 매칭 큐에 추가하는 것이 명확 } public List<String> extractThreeUsers(WorldType worldType) { // 3명의 사용자를 추출한다는 것이 명확 } }

/** * AI 게임방 생성 * @deprecated 통합 룸 생성 메서드 createUnifiedRooms() 사용 권장 */ @Deprecated private AiGameRoomResponse createAiGameRoom(String gameSessionId, List<String> participants, WorldType worldType) { AiGameRoomCreateRequest request = AiGameRoomCreateRequest.builder() .gameId(gameSessionId) .roomName(worldType.getDisplayName() + " 랜덤 매칭") .maxParticipants(DEFAULT_MAX_PARTICIPANTS) .gameSettings(worldType.getGameSettings()) .creatorId(participants.get(0)) .build(); return aiGameRoomService.createAiGameRoom(request); }

/** * 통합된 룸 생성 메서드 (신규 - 중복 제거용) * AI 게임룸과 채팅룸을 한 번에 생성하고 ID 맵을 반환 */ public Map<String, String> createUnifiedRooms(String gameSessionId, List<String> participants, WorldType worldType) { log.info("통합 룸 생성 시작: gameSessionId={}, participants={}, worldType={}", gameSessionId, participants, worldType); Map<String, String> roomIds = new HashMap<>(); try { // 1. AI 게임룸 생성 (통합 API 사용) UnifiedRoomRequest aiRoomRequest = UnifiedRoomRequest.builder() .roomType(RoomType.AI_GAME) .roomName(worldType.getDisplayName() + " 랜덤 매칭") .maxParticipants(DEFAULT_MAX_PARTICIPANTS) .creatorId(participants.get(0)) .participantIds(participants) .gameId(gameSessionId) .gameSettings(worldType.getGameSettings()) .build(); UnifiedRoomResponse aiRoom = roomServiceFactory .getService(RoomType.AI_GAME) .createRoom(aiRoomRequest); roomIds.put("ai", aiRoom.getRoomId()); // 2. 플레이어 채팅룸 생성 (통합 API 사용) UnifiedRoomRequest chatRoomRequest = UnifiedRoomRequest.builder() .roomType(RoomType.PLAYER_CHAT) .roomName(worldType.getDisplayName() + " 채팅방") .maxParticipants(DEFAULT_MAX_PARTICIPANTS) .creatorId(participants.get(0)) .participantIds(participants) .chatMode(ChatMode.MULTI) .build(); UnifiedRoomResponse chatRoom = roomServiceFactory .getService(RoomType.PLAYER_CHAT) .createRoom(chatRoomRequest); roomIds.put("chat", chatRoom.getRoomId()); log.info("통합 룸 생성 완료: aiRoomId={}, chatRoomId={}", roomIds.get("ai"), roomIds.get("chat")); return roomIds; } catch (Exception e) { log.error("통합 룸 생성 중 오류 발생: gameSessionId={}", gameSessionId, e); throw new AiChatException(ErrorCode.MATCHING_PROCESSING_ERROR, "룸 생성 실패: " + e.getMessage()); } }

// ❌ 하드코딩, 중복 코드, 책임 분리 안됨 private AiGameRoomResponse createAiGameRoom(...) { // AI 게임방만 생성 } private ChatRoomDto createChatRoom(...) { // 채팅방만 생성 } // 두 메서드를 각각 호출해야 함 AiGameRoomResponse aiRoom = createAiGameRoom(...); ChatRoomDto chatRoom = createChatRoom(...);

// 통합된 인터페이스, Factory 패턴, 중복 제거 public Map<String, String> createUnifiedRooms(...) { // Factory 패턴을 통해 다형성 활용 UnifiedRoomResponse aiRoom = roomServiceFactory .getService(RoomType.AI_GAME) .createRoom(aiRoomRequest); UnifiedRoomResponse chatRoom = roomServiceFactory .getService(RoomType.PLAYER_CHAT) .createRoom(chatRoomRequest); return Map.of("ai", aiRoom.getRoomId(), "chat", chatRoom.getRoomId()); }

// ✅ 테스트하기 쉬운 코드 @Test void calculateEstimatedWaitMessage_Position1_ReturnsImmediateMessage() { // Given MatchingTimeCalculator calculator = new MatchingTimeCalculator(properties); // When String message = calculator.calculateEstimatedWaitMessage(1); // Then assertEquals("곧 매칭될 예정입니다", message); }

// ✅ 비즈니스 로직이 명확히 드러남 if (queueManager.canProcessMatching(worldType)) { processMatchingAsync(worldType); }