runtime-smoke-20260710143823/spring-transition-plan/ARCHITECTURE.md

스프링 전환 아키텍처 설계서

1. 개요

1.1 목적

본 문서는 기존 시스템을 스프링 프레임워크 기반으로 전환하기 위한 아키텍처 설계를 정의한다.

1.2 기존 vs 스프링 시스템 비교

구분	기존 시스템	스프링 기반 시스템
프레임워크	레거시	Spring Boot 3.2.0
DI 방식	수동	Spring IoC/DI
설정	XML	Java Config + YAML
트랜잭션	수동	@Transactional
웹	서블릿	Spring MVC

2. 대상 아키텍처

2.1 계층 구조

┌─────────────────────────────────────┐
│   Presentation (REST Controllers)   │
├─────────────────────────────────────┤
│   Service (Business Logic)          │
├─────────────────────────────────────┤
│   Repository (Data Access)          │
├─────────────────────────────────────┤
│   Domain (Entity/Model)             │
└─────────────────────────────────────┘

2.2 모듈 구조

spring-transition-project/
├── pom.xml (Parent BOM)
├── common/          # 공통 유틸리티
├── domain/          # 도메인 엔티티
├── repository/      # 데이터 접근
├── service/         # 비즈니스 로직
├── web/             # 웹 프레젠테이션
└── application/     # 메인 애플리케이션

2.3 핵심 의존성

의존성	버전	용도
spring-boot	3.2.0	코어
spring-boot-starter-web	3.2.0	REST API
spring-boot-starter-data-jpa	3.2.0	ORM
spring-boot-starter-validation	3.2.0	검증
lombok	1.18.30	코드 생성
h2	2.2.224	인메모리 DB

3. 전환 전략

3.1 Strangler Fig Pattern

1. 프록시 계층: API Gateway 배치
2. 점진적 전환: 모듈별 순차 전환
3. 트래픽 분기: 신규→스프링, 기존→레거시

3.2 전환 우선순위

단계	대상	기간	위험도
1	공통 유틸리티	2주	낮음
2	도메인/엔티티	3주	중간
3	Repository	4주	중간
4	Service	4주	높음
5	Web	3주	높음
6	통합 테스트	2주	중간

4. 기존 시스템과의 관계

4.1 공존 모델

┌──────────────┐     ┌──────────────┐
│ Legacy (RO)  │────▶│ Spring (WO)  │
└──────────────┘     └──────────────┘
         └──────────┬───────────┘
                    ▼
            ┌──────────────┐
            │  Shared DB   │
            └──────────────┘

4.2 인터페이스

인터페이스	방향	프로토콜
REST API	양방향	HTTP/JSON
내부 이벤트	단방향	Spring Events
메시지 큐	단방향	Kafka/RabbitMQ

5. 검증 기준

• 단위 테스트 커버리지 80% 이상
• 통합 테스트 통과
• 성능 테스트 기준 충족
• 보안 취약점 스캔 통과