엔지니어링에서 가장 까다로운 요구 중 하나는 "운영 중인 서비스의 기능을 100% 동일하게 유지하면서 백엔드를 완전히 다시 짜달라"는 것입니다.
명세서가 따로 없고 수년간 누적된 코드 자체가 유일한 스펙인 상황에서, 기존 기능을 하나도 빠뜨리지 않고 새 프레임워크(Bun/Elysia)로 안전하게 이전하는 실전 방법론을 기록했습니다.
손으로 일일이 옮기면 반드시 누락이 발생한다
수백 개의 API 엔드포인트를 사람이 눈으로 확인하며 옮기면, '무엇을 빠뜨렸는지조차 모르는 사태'가 반드시 발생합니다.
거의 호출되지 않는 숨은 경로, 특정 조건에서만 동작하는 예외 분기, 프론트엔드가 암묵적으로 의존하고 있던 사소한 응답 필드 등은 수동 검증으로는 절대 잡아낼 수 없습니다.
해결: 소스코드에서 계약(Contract) 자동 추출 및 CI 게이트
- 자동화된 API 계약 추출: 기존 레거시 코드베이스를 정적 분석하여 모든 엔드포인트의 경로, 파라미터, 응답 스키마를 담은 12,000줄 규모의 명세서를 기계적으로 생성했습니다. 사람이 작성한 문서가 아니므로 실제 런타임과 오차가 없습니다.
- CI 패리티 검증 게이트(Parity Gate):
- 누락 검사: 기존 시스템에는 존재하지만 새 시스템에 아직 구현되지 않은 엔드포인트 개수를 추적합니다.
- 타입 및 스키마 검사: 새 엔드포인트의 입출력 타입이 기존 명세와 완벽히 호환되는지 빌드 파이프라인에서 자동 검증합니다.
기준선(Baseline) 기반의 점진적 이전
마이그레이션 초기에는 당연히 구현되지 않은 엔드포인트가 많습니다. 단순히 "차이 0개"를 목표로 CI를 설정하면 개발 기간 내내 빌드가 실패하여 CI가 무용지물이 됩니다.
따라서 현재 시점의 미구현 개수를 '기준선(Baseline)'으로 기록하고, 미구현 수가 늘어나는 머지만 차단하며 줄어드는 머지만 허용하는 방식을 적용했습니다. 이를 통해 수개월에 걸친 대규모 작업을 안전하고 점진적으로 완수할 수 있었습니다.
전면 재작성을 결정하기 전 따져보아야 할 것
단순히 "기존 코드가 지저분하다"는 이유는 재작성의 명분이 될 수 없습니다. 지저분한 코드는 리팩토링의 대상이지 재작성의 대상이 아닙니다.
전면 재작성이 정당화되는 순간은 기존 런타임이나 아키텍처 자체가 한계에 부딪혀 비즈니스 확장을 가로막을 때뿐입니다.
요약
대규모 마이그레이션의 성공을 결정짓는 것은 개발자의 기억력이나 집중력이 아니라, 기계적으로 결함을 걸러내는 자동화된 검증 파이프라인입니다.