헥사고날 아키텍처로 전환하기 (To Hexagonal Architecture)
기존 리포지토리를 심층 분석하여 **헥사고날 아키텍처(포트와 어댑터)**로의 원자적이고 단계적인 리팩토링 계획을 설계합니다. 외부 계약이나 관찰 가능한 동작을 전혀 변경하지 않습니다.
사용자 요청과 동일한 언어로 응답합니다. **계획 모드(Plan Mode)**로 엄격하게 작동합니다: 먼저 코드베이스를 검사하고, 파일을 수정하기 전에 완전한 계획을 전달합니다.
사용 시기
- 사용자가 기존 프로젝트를 헥사고날 아키텍처 또는 포트와 어댑터로 마이그레이션하거나 리팩토링하도록 요청할 때
- 사용자가 비즈니스 로직을 웹 프레임워크, ORM, 데이터베이스, 메시지 브로커, 외부 SDK로부터 분리하고자 할 때
- 사용자가 기존 동작을 전혀 변경하지 않는 안전하고 점진적인 아키텍처 리팩토링 계획을 요청할 때
핵심 원칙
- 제로 브레이킹 체인지(황금 규칙): 모든 기존 외부 계약을 유지합니다. 라우트, HTTP 메서드, 상태 코드, 요청/응답 페이로드 스키마, 헤더, 오류 형식, CLI 플래그, 큐 메시지 형식이 동일해야 합니다.
- 리팩토링 전 특성화: 자동화된 계약/특성화 테스트가 기존 엔드포인트 또는 진입점을 커버할 때까지 프로덕션 로직을 이동하거나 삭제하지 않습니다.
- 엄격한 종속성 규칙: 소스 코드 종속성은 항상 내부의
domain을 향해야 합니다. 도메인 계층은 웹 프레임워크, 데이터베이스 드라이버, ORM, 직렬화 라이브러리, 외부 SDK에서 임포트가 없어야 합니다. - 스택 관용적 적응: 디렉토리 경로, 명명 규칙, 타이핑 구조, 테스트 러너를 프로젝트의 감지된 언어와 생태계(예: TypeScript/Node, Python, Go, Java/Kotlin, C#, Rust)에 맞게 조정합니다.
워크플로우
1단계: 코드베이스 탐색
폴더 트리 또는 마이그레이션 단계를 제안하기 전에 리포지토리를 스캔합니다:
- 스택 및 도구: 종속성 매니페스트, 컴파일러/린터 설정, 테스트 러너를 검사하여 언어, 프레임워크, 유효성 검사 라이브러리, ORM/쿼리 빌더, 의존성 주입 접근 방식을 식별합니다.
- 진입점 및 계약: 모든 구동 진입점(HTTP 라우트, GraphQL 리졸버, gRPC 서비스, 메시지 컨슈머, 크론 잡), 그 유효성 검사 스키마, 미들웨어/인터셉터, 전역 오류 핸들러를 인벤토리화합니다.
- 외부 종속성: 모든 구동 부작용(데이터베이스, 캐시, HTTP/RPC 클라이언트, 큐, 파일 저장소, 환경 설정, 로거)을 인벤토리화합니다.
- 현재 실행 흐름: 데이터가 진입점에서 지속성/외부 호출로 어떻게 흐르고 돌아오는지 추적하며, 비즈니스 규칙이 전송 또는 지속성 세부 사항과 혼합된 부분을 기록합니다.
2단계: 대상 헥사고날 레이아웃 설계
세 가지 동심원 레이어를 프로젝트의 관용적 소스 루트(예: TypeScript/Rust의 src/, Go의 internal/, JVM의 src/main/<lang>/, Python의 메인 패키지 디렉토리)에 매핑합니다:
domain/(순수 비즈니스 코어 – 프레임워크나 I/O 종속성 없음):entities/및value-objects/: 비즈니스 규칙, 불변 조건, 자체 검증을 캡슐화하는 도메인 모델ports/in/: 유스 케이스 계약을 정의하는 구동 포트 인터페이스ports/out/: 리포지토리, 외부 서비스, 이벤트 퍼블리셔,LoggerPort계약을 정의하는 구동 포트 인터페이스errors/: 의미 있는 도메인 예외 (예:ResourceNotFoundError,DomainValidationError,ConflictError)
application/(유스 케이스 오케스트레이션):use-cases/:ports/in을 구현하며 도메인 엔티티와ports/out을 조정dtos/: 전송 페이로드 및 지속성 엔티티로부터 분리된 불변 입력/출력 데이터 구조
infrastructure/(기술 세부 사항 및 어댑터):adapters/in/: 구동 어댑터(HTTP 컨트롤러/핸들러, 컨슈머 핸들러), 전송 유효성 검사 스키마, 매퍼(TransportInput -> InputDTO,OutputDTO -> TransportOutput),domain/errors를 정확한 레거시 오류 응답으로 변환하는 전역 오류 매퍼adapters/out/:ports/out의 구체적인 구현(데이터베이스 리포지토리, HTTP 클라이언트, 브로커) 및 지속성/외부 매퍼로 ORM 모델이나 SDK 유형이domain으로 누출되지 않도록 함config/: 환경 변수 및 런타임 설정의 엄격한 로딩 및 시작 유효성 검사di/(구성 루트): 생성자 주입을 통해 구동 어댑터, 유스 케이스, 구동 어댑터를 명시적으로 연결하며, 숨겨진 싱글톤이나 서비스 로케이터를 피함
- 부트스트랩 분리: 애플리케이션 구성(
buildApp/ 격리된 통합 테스트를 위한 팩토리 함수)을 서버/프로세스 시작(main/listen)과 분리
3단계: 계획에 엔지니어링 표준 적용
계획의 각 단계에서 다음을 강제합니다:
- 강력한 타이핑 및 불변성: 타입되지 않은 이스케이프(예:
any, 타입 구조가 적용되어야 하는 곳에서 원시 타입되지 않은 맵)를 금지하고 불변 DTO 및 값 객체(readonly, 동결 데이터클래스, 레코드, 값 유형)를 선호합니다. - SOLID 및 생성자 주입: 클래스와 함수를 작고 단일 책임으로 유지하고, 생성자를 통해 인터페이스를 주입합니다.
- 결합 없는 관찰 가능성: 구조화된 로깅과 요청 상관 관계 컨텍스트를 유지하면서도
domain/과application/이LoggerPort를 통해 특정 로깅 라이브러리로부터 분리되도록 합니다. - 피라미드 테스트:
domain/(순수 불변 조건) 및application/(ports/out모킹)을 위한 단위 테스트- 스택의 네이티브 인메모리 테스트 클라이언트(예:
fastify.inject, SuperTest, FastAPITestClient, SpringMockMvc, Gohttptest)를 사용하여 실제 구동 어댑터를 애플리케이션 와이어링에 대해 검증하는 통합/계약 테스트
출력 형식 (계획 모드)
응답을 다음 정확한 섹션으로 구성하여 전달합니다:
- 현재 아키텍처 진단: 감지된 스택, 진입점/엔드포인트, 외부 종속성, 주요 결합 핫스팟의 간결한 인벤토리
- 대상 디렉토리 트리: 리포지토리에서 찾은 실제 모듈 및 기능 이름을 사용한 제안된 폴더 구조 전체
- 단계별 실행 계획: 5개의 원자적이고 검증 가능한 단계:
- 1단계 – 특성화 테스트 및 기본 스캐폴딩: 현재 동작을 잠그는 계약 테스트 생성, 대상 폴더, 구성 로더, 구성 루트(
di/) 생성 - 2단계 – 도메인 추출: 엔티티, 값 객체, 도메인 오류,
ports/in+ports/out인터페이스를 단위 테스트와 함께 추출 - 3단계 – 애플리케이션 유스 케이스 및 구동 어댑터: 유스 케이스, DTO,
adapters/out리포지토리/클라이언트, 지속성 매퍼 구현 - 4단계 – 구동 어댑터 및 오류 변환: 컨트롤러/핸들러를 리팩토링하여 매퍼를 통해 유스 케이스에 위임하고, 전역 오류 변환을 연결하며,
di/연결 - 5단계 – 레거시 정리 및 최종 검증: 사용되지 않는 파일 제거, 전체 테스트 스위트, 린터, 타입 체커 실행, 제로 계약 이탈 확인
- 1단계 – 특성화 테스트 및 기본 스캐폴딩: 현재 동작을 잠그는 계약 테스트 생성, 대상 폴더, 구성 로더, 구성 루트(
- 검증 체크포인트: 각 단계 종료 시 아무것도 깨지지 않았음을 증명하는 명시적 명령 또는 검사
주의사항
- 코드를 조기에 편집하지 마세요: 사용자가 명시적으로 1단계를 즉시 실행하도록 요청하지 않는 한, 계획만 먼저 출력하여 모듈 경계를 검토할 수 있도록 합니다.
- 단순 CRUD에 대한 과도한 추상화 피하기: 여전히
domain,application,infrastructure를 깔끔하게 분리하지만, 통과형 유스 케이스는 간결하게 유지하고 인위적인 도메인 복잡성을 만들지 않습니다. - 레거시 특이사항 일치: 기존 엔드포인트가 비표준 상태 코드나 오류 필드 이름을 반환하는 경우 1단계에서 문서화하고
infrastructure오류 매퍼에서 유지하여 기존 클라이언트가 깨지지 않도록 합니다.