Post

JSP 기반 시스템의 구조적 문제를 해결한 아키텍처 전환기: API 명세 없는 레거시 시스템의 신규 시스템 이관 전략

API 명세가 없는 레거시 시스템을 새로운 시스템으로 이관하는 것은 많은 기업에서 실제로 겪는 어려운 과제입니다. 이 경우 소스코드 분석, 트래픽 리버스 엔지니어링, 실시간 미러링 테스트, 그리고 점진적 이관 전략을 병행하여야 안정적으로 마이그레이션할 수 있습니다. 아래는 이를 계획, 분석, 구현, 전환, 운영 단계로 나눠 상세히 설명한 전략입니다.

🧭 API 명세 없는 레거시 시스템의 신규 시스템 이관 전략

1. 🧱 사전 준비 단계

✅ 목표 설정

  • 기존 시스템을 유지하면서 신규 시스템으로 점진적 전환
  • 데이터/비즈니스 로직 정합성 보장
  • 다운타임 없이 제로 다운타임 이관 지향

✅ 주요 리스크

  • API 명세 부재 → 기능 정의 모호
  • 비즈니스 로직이 SQL 또는 JSP에 직접 하드코딩
  • 예상치 못한 입력 값/흐름으로 인한 예외 발생

2. 🔍 레거시 분석 단계

✅ 2.1 트래픽 리버스 엔지니어링

방법

  • 브라우저 개발자 도구 또는 Proxy툴(Fiddler, mitmproxy) 활용
  • HTTP 요청/응답을 캡처하여:

    • URL, Method, 파라미터
    • 헤더 구조
    • 응답 데이터 구조(JSON, HTML, XML 등) 확인
1
2
GET /api/user?id=123  
→ 응답: { \"id\": 123, \"name\": \"John\", \"status\": \"ACTIVE\" }

자동화 도구

  • OpenReplay / Requestly 등 트래픽 리플레이 툴
  • API Gateway 로그 or WAS Access 로그 활용

✅ 2.2 소스코드 기반 API 추적

MyBatis 기반일 경우

  • mapper.xml 또는 SQL 구문에서 쿼리 패턴 확인
  • @RequestMapping, @ResponseBody 등 컨트롤러 분석

자동화 도구 활용

  • IDE의 Call Hierarchy / Find Usage
  • ArchUnit, JDepend, JArchitect 등으로 패키지 의존 분석

3. 🧰 신규 시스템 설계 및 구성

✅ DTO / Entity 설계

  • 기존 응답/요청 데이터 포맷을 기준으로 DTO 정의
  • DB 구조를 재사용하면서도 도메인 중심으로 JPA Entity 설계

✅ Enum / 코드값 전략 수립

  • 정합성 안 맞는 enum 대응: UNKNOWN, SafeEnumConverter 활용
  • code → label 방식이면 코드테이블 설계 고려

4. 🔁 병렬 이관 및 검증

✅ 4.1 Shadow/Mirroring 테스트

  • 실제 유저 요청을 레거시 시스템에 먼저 전달, 동시에 신규 시스템에도 미러링
  • 결과 비교 후 차이점 분석
1
2
3
Client → Legacy API → Response  
              ↘  
               New API → Compare Response

도구 예시:

  • NGINX dual proxy 설정
  • Java/Spring Interceptor 내 미러링 로직 삽입

✅ 4.2 Canary/Blue-Green 전환 전략

  • 특정 트래픽(10%)만 신규 시스템으로 분기
  • 점진적으로 전체 전환
1
2
- 사용자 IP 해시 기반으로 라우팅
- 또는 회원 등급/테스트 그룹으로 제한

5. 🚦 점진적 전환 및 운영

✅ 운영 전략

  • 트래픽 로그로 신규 API의 실제 사용 범위 수집
  • 신규 시스템 응답 시간 / 실패율 모니터링 → 문제 생기면 자동 롤백

✅ 문서화 자동화

  • 수집한 API 패턴 기반으로 자동 Swagger 문서화

    • 예: Spring REST Docs, Swagger/OpenAPI Generator

✅ 전환 전략 요약

단계설명도구/기술
사전 준비목표 설정, 리스크 분석Notion, Jira
리버스 엔지니어링트래픽 캡처, 코드 추적devtools, mitmproxy, grep
신규 시스템 설계DTO, Entity, Enum 전략Spring Boot + JPA
병렬 운영Shadow, Canary 테스트NGINX, Spring Interceptor
전환트래픽 전환, 모니터링Prometheus, Grafana, Kibana

🧩 팁: 자주 사용하는 패턴들

  • @RequestBody → DTO 검증 (@Valid, enum 매핑)
  • MyBatis SQL → JPQL로 이관 시 조건절 해석 주의
  • XML 응답 → Jackson XML Module 활용
  • 동작 로직이 쿼리 내부에 있는 경우 → @QueryProjection, nativeQuery로 이관

📌 마무리

명세 없는 레거시 시스템은 “살아있는 문서인 트래픽”을 분석하는 것이 핵심입니다. 정확한 분석 → 안전한 구조 설계 → 점진적 검증 → 안정적 전환 순으로 진행하면, 예기치 못한 오류 없이 새로운 시스템으로 성공적인 이관이 가능합니다.

This post is licensed under CC BY 4.0 by the author.