forge-bot/runtime-smoke-20260710143823
1
0
Fork 0
Code Issues Pull requests 4 Projects Releases Packages Wiki Activity Actions

스프링 전환 계획 수립 #2

Open
forge-bot wants to merge 9 commits from forge/iss-cb35afc33813-attempt-2-run-0d580cf424c5 into main
pull from: forge/iss-cb35afc33813-attempt-2-run-0d580cf424c5
merge into: forge-bot:main
Conversation 0 Commits 9 Files changed 9 +649
9 changed files with 649 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

3
.forge/iss-cb35afc33813-attempt-2-run-0d580cf424c5.md Normal file
View file

@ -0,0 +1,3 @@
# iss-cb35afc33813-attempt-2-run-0d580cf424c5
Forge 이슈 작업 브랜치 `forge/iss-cb35afc33813-attempt-2-run-0d580cf424c5`.

101
spring-transition-plan/ARCHITECTURE.md Normal file
View file

@ -0,0 +1,101 @@
# 스프링 전환 아키텍처 설계서
## 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% 이상
- 통합 테스트 통과
- 성능 테스트 기준 충족
- 보안 취약점 스캔 통과

83
spring-transition-plan/MILESTONE.md Normal file
View file

@ -0,0 +1,83 @@
# 스프링 전환 마일스톤
## 마일스톤 개요
| 마일스톤 | 기간 | 주요 Deliverable |
|----------|------|------------------|
| M1: 기반 구축 | W1-W2 | 프로젝트 구조, CI/CD |
| M2: 도메인 전환 | W3-W5 | 엔티티, 도메인 모델 |
| M3: 데이터 접근 | W6-W9 | Repository, Query |
| M4: 서비스 전환 | W10-W13 | Business Logic |
| M5: 웹 전환 | W14-W16 | REST API |
| M6: 운영 전환 | W17-W18 | 배포, 모니터링 |
## 상세 일정
### M1: 기반 구축 (2주)
| 태스크 | 담당 | 상태 |
|--------|------|------|
| 프로젝트 구조 설계 | 아키텍트 | □ |
| Parent POM 작성 | 개발자 | □ |
| 모듈 생성 | 개발자 | □ |
| 공통 유틸리티 이전 | 개발자 | □ |
| CI/CD 파이프라인 | DevOps | □ |
### M2: 도메인 전환 (3주)
| 태스크 | 담당 | 상태 |
|--------|------|------|
| 엔티티 매핑 분석 | 개발자 | □ |
| JPA 엔티티 구현 | 개발자 | □ |
| 도메인 모델 정제 | 개발자 | □ |
| 도메인 이벤트 설계 | 개발자 | □ |
| 단위 테스트 작성 | 개발자 | □ |
### M3: 데이터 접근 (4주)
| 태스크 | 담당 | 상태 |
|--------|------|------|
| Repository 설계 | 개발자 | □ |
| Query 구현 | 개발자 | □ |
| 트랜잭션 설정 | 개발자 | □ |
| 캐시 적용 | 개발자 | □ |
| 통합 테스트 | 개발자 | □ |
### M4: 서비스 전환 (4주)
| 태스크 | 담당 | 상태 |
|--------|------|------|
| Service 계층 분석 | 개발자 | □ |
| @Service 구현 | 개발자 | □ |
| 의존성 주입 리팩토링 | 개발자 | □ |
| 비즈니스 로직 검증 | 개발자 | □ |
| 테스트 보강 | 개발자 | □ |
### M5: 웹 전환 (3주)
| 태스크 | 담당 | 상태 |
|--------|------|------|
| Controller 설계 | 개발자 | □ |
| DTO/VO 구현 | 개발자 | □ |
| Validation 적용 | 개발자 | □ |
| API 문서화 | 개발자 | □ |
| API 테스트 | 개발자 | □ |
### M6: 운영 전환 (2주)
| 태스크 | 담당 | 상태 |
|--------|------|------|
| 배포 자동화 | DevOps | □ |
| 모니터링 설정 | DevOps | □ |
| 로깅 통합 | DevOps | □ |
| 성능 테스트 | QA | □ |
| 운영 인계 | 전체 | □ |
## 리소스 배정
| 역할 | 인원 | 기간 |
|------|------|------|
| 아키텍트 | 1 | 전 기간 |
| 백엔드 개발자 | 3 | 전 기간 |
| DevOps | 1 | M1, M6 |
| QA | 1 | M3, M6 |
## 가시성
- 주간 스탠드업 미팅
- 2주 단위 스프린트 리뷰
- 월간 마일스톤 게이트 리뷰

105
spring-transition-plan/TRANSITION-STRATEGY.md Normal file
View file

@ -0,0 +1,105 @@
# 스프링 전환 전략 문서
## 1. 전환 개요
### 1.1 목표
- 레거시 시스템 → Spring Boot 3.x 현대화
- 마이크로서비스 아키텍처 점진적 전환
- 유지보수성 및 확장성 향상
### 1.2 범위
- 백엔드 API 서버 전환
- 데이터 접근 계층 재구성
- 설정 관리 체계 개편
## 2. 전환 접근법
### 2.1 Big Bang vs 점진적
| 방식 | 장점 | 단점 | 적용 |
|------|------|------|------|
| Big Bang | 단일 시점 | 위험도 높음 | 소규모 |
| 점진적 (Strangler Fig) | 위험 분산 | 복잡한 운영 | 대규모 ✓ |
**선정**: 점진적 전환
### 2.2 전환 단계별 상세
#### Phase 1: 기반 구축 (1-2주)
- Spring Boot 프로젝트 구조 생성
- Parent POM 설정
- 공통 모듈 생성
- CI/CD 파이프라인 구축
#### Phase 2: 도메인 전환 (3-5주)
- 엔티티 매핑 전환 (JPA)
- 도메인 모델 정제
- 값 객체 구현
- 도메인 이벤트 설계
#### Phase 3: 데이터 접근 (6-9주)
- Repository 구현
- QueryDSL/JPA Criteria 적용
- 트랜잭션 경계 설정
- 캐시 전략 구현
#### Phase 4: 서비스 전환 (10-13주)
- @Service 빈 전환
- 의존성 주입 리팩토링
- 비즈니스 로직 검증
- 통합 테스트 실행
#### Phase 5: 웹 계층 전환 (14-16주)
- @RestController 구현
- DTO/VO 설계
- Validation 적용
- API 문서화 (SpringDoc)
#### Phase 6: 운영 전환 (17-18주)
- 트래픽 전환
- 모니터링 설정
- 로깅 체계 통합
- 장애 복구 테스트
## 3. 리스크 관리
### 3.1 식별된 리스크
| 리스크 | 영향 | 가능성 | 대응 |
|--------|------|--------|------|
| 데이터 불일치 | 높음 | 중간 | 이중 쓰기, CDC |
| 성능 저하 | 중간 | 낮음 | 사전 성능 테스트 |
| 호환성 문제 | 중간 | 중간 | API 버전 관리 |
| 운영 지식 부족 | 중간 | 높음 | 교육 및 문서화 |
### 3.2 롤백 계획
1. Blue/Green 배포로 즉각 롤백
2. Feature Toggle으로 기능별 비활성화
3. 레거시 시스템 유지 (최대 6개월)
## 4. 성공 기준
### 4.1 정량적 기준
| 지표 | 현재 | 목표 |
|------|------|------|
| 배포 주기 | 월 1회 | 주 1회+ |
| 빌드 시간 | 15분 | 5분 이하 |
| 테스트 커버리지 | 40% | 80% |
| 가용성 | 99.5% | 99.9% |
### 4.2 정성적 기준
- 개발팀 스프링 역량 확보
- 문서화 완료
- 운영 매뉴얼整備
## 5. 교육 계획
| 주제 | 대상 | 기간 | 방식 |
|------|------|------|------|
| Spring Boot 기초 | 전체 | 1주 | 온라인 |
| JPA 심화 | 백엔드 | 1주 | 오프라인 |
| 테스트 전략 | 전체 | 3일 | 워크숍 |
| 운영 실무 | DevOps | 3일 | 실습 |

41
spring-transition-plan/application/pom.xml Normal file
View file

@ -0,0 +1,41 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.transition</groupId>
<artifactId>spring-transition-plan</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<artifactId>application</artifactId>
<packaging>jar</packaging>
<name>Application Module</name>
<dependencies>
<dependency><groupId>com.transition</groupId><artifactId>web</artifactId><version>${project.version}</version></dependency>
<dependency><groupId>com.transition</groupId><artifactId>service</artifactId><version>${project.version}</version></dependency>
<dependency><groupId>com.transition</groupId><artifactId>repository</artifactId><version>${project.version}</version></dependency>
<dependency><groupId>com.transition</groupId><artifactId>domain</artifactId><version>${project.version}</version></dependency>
<dependency><groupId>com.transition</groupId><artifactId>common</artifactId><version>${project.version}</version></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-jpa</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-actuator</artifactId></dependency>
<dependency><groupId>com.h2database</groupId><artifactId>h2</artifactId><scope>runtime</scope></dependency>
<dependency><groupId>org.postgresql</groupId><artifactId>postgresql</artifactId><scope>runtime</scope></dependency>
<dependency><groupId>org.testcontainers</groupId><artifactId>postgresql</artifactId><scope>test</scope></dependency>
<dependency><groupId>org.testcontainers</groupId><artifactId>junit-jupiter</artifactId><scope>test</scope></dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>

15
spring-transition-plan/application/src/main/java/com/transition/application/SpringTransitionApplication.java Normal file
View file

@ -0,0 +1,15 @@
package com.transition.application;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.domain.EntityScan;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
@SpringBootApplication
@EntityScan(basePackages = "com.transition.domain")
@EnableJpaRepositories(basePackages = "com.transition.repository")
public class SpringTransitionApplication {
public static void main(String[] args) {
SpringApplication.run(SpringTransitionApplication.class, args);
}
}

35
spring-transition-plan/application/src/main/resources/application.yml Normal file
View file

@ -0,0 +1,35 @@
spring:
application:
name: spring-transition-application
datasource:
url: ${DB_URL:jdbc:h2:mem:transitiondb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE}
username: ${DB_USERNAME:sa}
password: ${DB_PASSWORD:}
driver-class-name: org.h2.Driver
jpa:
hibernate:
ddl-auto: update
show-sql: true
properties:
hibernate:
format_sql: true
dialect: org.hibernate.dialect.H2Dialect
h2:
console:
enabled: true
path: /h2-console
server:
port: ${SERVER_PORT:8080}
management:
endpoints:
web:
exposure:
include: health,info,metrics
endpoint:
health:
show-details: when_authorized
logging:
level:
com.transition: DEBUG
org.springframework.web: INFO
org.hibernate.SQL: DEBUG

107
spring-transition-plan/pom.xml Normal file
View file

@ -0,0 +1,107 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.2.0</version>
<relativePath/>
</parent>
<groupId>com.transition</groupId>
<artifactId>spring-transition-plan</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<name>Spring Transition Plan</name>
<description>스프링 전환 계획 프로젝트</description>
<modules>
<module>common</module>
<module>domain</module>
<module>repository</module>
<module>service</module>
<module>web</module>
<module>application</module>
</modules>
<properties>
<java.version>17</java.version>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<lombok.version>1.18.30</lombok.version>
<testcontainers.version>1.19.3</testcontainers.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>testcontainers-bom</artifactId>
<version>${testcontainers.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>${lombok.version}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<source>${java.version}</source>
<target>${java.version}</target>
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>${lombok.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.11</version>
<executions>
<execution>
<goals><goal>prepare-agent</goal></goals>
</execution>
<execution>
<id>report</id>
<phase>test</phase>
<goals><goal>report</goal></goals>
</execution>
</executions>
</plugin>
</plugins>
</pluginManagement>
</build>
</project>

159
spring-transition-plan/test_reference.md Normal file
View file

@ -0,0 +1,159 @@
# 스프링 전환 테스트 참조 문서
## 1. 테스트 전략 개요
### 1.1 테스트 피라미드
```
▲
/E2E\ (End-to-End)
/──────\
/Integration\ (Integration)
/────────────\
/ Unit Tests \ (Unit)
/────────────────\
```
### 1.2 목표 커버리지
| 테스트 유형 | 목표 | 도구 |
|------------|------|------|
| 단위 테스트 | 80% | JUnit 5, Mockito |
| 통합 테스트 | 70% | Spring Test, TestContainers |
| E2E 테스트 | 50% | RestAssured |
## 2. 단위 테스트 기준
### 2.1 Service Layer 테스트
```java
@SpringBootTest
class UserServiceTest {
@Autowired private UserService userService;
@MockBean private UserRepository userRepository;
@Test
void shouldCreateUserSuccessfully() {
// Given
UserDto dto = new UserDto("test@example.com", "password");
when(userRepository.save(any(User.class))).thenAnswer(i -> i.getArgument(0));
// When
User result = userService.createUser(dto);
// Then
assertThat(result.getEmail()).isEqualTo("test@example.com");
verify(userRepository).save(any(User.class));
}
@Test
void shouldThrowExceptionForDuplicateEmail() {
// Given
String email = "existing@example.com";
when(userRepository.findByEmail(email)).thenReturn(Optional.of(new User()));
// When/Then
assertThatThrownBy(() -> userService.createUser(new UserDto(email, "pass")))
.isInstanceOf(DuplicateEmailException.class);
}
}
```
### 2.2 Repository 테스트
```java
@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
class UserRepositoryTest {
@Autowired private UserRepository userRepository;
@Autowired private TestEntityManager entityManager;
@Test
void shouldFindByEmail() {
// Given
User user = new User("test@example.com", "encoded");
entityManager.persist(user);
// When
Optional<User> found = userRepository.findByEmail("test@example.com");
// Then
assertThat(found).isPresent();
}
}
```
### 2.3 Controller 테스트
```java
@WebMvcTest(UserController.class)
class UserControllerTest {
@Autowired private MockMvc mockMvc;
@MockBean private UserService userService;
@Test
void shouldCreateUser() throws Exception {
// Given
CreateUserRequest request = new CreateUserRequest("test@example.com", "password");
when(userService.createUser(any())).thenReturn(new User(1L, "test@example.com"));
// When/Then
mockMvc.perform(post("/api/users")
.contentType(MediaType.APPLICATION_JSON)
.content(objectMapper.writeValueAsString(request)))
.andExpect(status().isCreated())
.andExpect(jsonPath("$.email").value("test@example.com"));
}
}
```
## 3. 통합 테스트 기준
### 3.1 Database Integration Test
```java
@SpringBootTest
@Testcontainers
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
class UserRepositoryIntegrationTest {
@Container
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15");
@DynamicPropertySource
static void properties(DynamicPropertyRegistry registry) {
registry.add("spring.datasource.url", postgres::getJdbcUrl);
registry.add("spring.datasource.username", postgres::getUsername);
registry.add("spring.datasource.password", postgres::getPassword);
}
@Test
void shouldPersistAndRetrieveUser() {
User user = new User("integration@test.com", "password");
User saved = userRepository.save(user);
Optional<User> found = userRepository.findById(saved.getId());
assertThat(found).isPresent();
}
}
```
## 4. 테스트 실행 기준
| 테스트 유형 | 실행 시점 | 실패 시 동작 |
|-----------|----------|-------------|
| 단위 테스트 | 매 커밋 | 빌드 실패 |
| 통합 테스트 | PR 생성 | 빌드 실패 |
| E2E 테스트 | 일 1회 | 알림 발송 |
| 성능 테스트 | 주 1회 | 보고 |
## 5. 검증 체크리스트
### 전환 완료 기준
- [ ] 단위 테스트 커버리지 80% 이상
- [ ] 모든 Service 메서드 테스트 coverage
- [ ] 모든 Repository 쿼리 테스트 coverage
- [ ] 모든 Controller endpoint 테스트 coverage
- [ ] Integration Test Database 환경 독립적 실행
- [ ] Mock 객체 주입 검증
- [ ] 예외 처리 경로 테스트 coverage
- [ ] 테스트 격리 확인
### 코드 품질 기준
- [ ] SonarQube Quality Gate 통과
- [ ] Cyclomatic Complexity < 10
- [ ] 테스트 명명 규칙 준수
- [ ] Given-When-Then 패턴 적용