점진 마이그레이션 중간 상태, 뭘 먼저 정리해야 할까?
권한을 역할별로 나누는 RBAC를 도입하면서, 컨트롤러 구조도 새 패턴으로 바꾸기 시작했습니다. 신규 기능부터 역할 기반 폴더에 컨트롤러를 두는 방식이었습니다. 한 번에 전부 옮기지 않고, 새로 만드는 것부터 점진적으로 새 패턴을 적용했습니다.
문제는 시간이 지나면서 생겼습니다. 새 패턴과 옛 패턴이 공존하다 보니, 어느 위치가 정답인지 모호한 파일이 쌓였습니다. 정리는 하고 싶은데, 한 번에 다 옮기자니 호출처가 많이 묶인 파일이 섞여 있어 잘못 건드리면 깨질 위험이 컸습니다.
옮기기 전에, 코드 위치부터 숫자로 셌습니다
손대기 전에 현황을 매트릭스로 정리했습니다. 코드 위치를 셋으로 나눠 세어보니 새 패턴 폴더에 34건, 옛 패턴 폴더에 18건, 그리고 둘 중 어디에도 깔끔하게 속하지 않는 "어중간한 위치"에 4건이 있었습니다.
정리 우선순위는 이 분포에서 바로 드러났습니다. 새 패턴 34건은 이미 제자리에 있고, 옛 패턴 18건은 한 덩어리로 묶여 있어 함부로 못 건드립니다. 진짜 손볼 곳은 어중간하게 떠 있는 4건이었습니다.
같은 날 시간 처리 로직도 점진적으로 정리하고 있었는데, 둘 다 "숫자로 현황을 먼저 보고 우선순위를 정한다"는 같은 방식이었습니다.
세 가지 길을 두고 골랐습니다
선택지는 세 가지였습니다.
1번은 공존하는 걸 한 번에 다 정리하는 방식입니다. PR은 커지고, 호출처가 많은 파일을 잘못 옮기면 그 자리에서 깨집니다.
2번은 그냥 공존을 유지하는 방식입니다. 안전하지만 코드 위치가 모호한 상태가 계속 누적됩니다.
3번은 단계를 나누는 방식입니다. 어중간한 위치부터 우선 정리하고, 호출처가 많은 명확한 잔존물은 호출처를 먼저
옮긴 뒤에 처리합니다. 3번을 골랐습니다.
점진 전환에서 신·구를 공존시키며 단계적으로 넘어간 경험은 전에도 있었습니다.
외부 호출처가 0인 것만 옮겼습니다
어중간한 위치 4건 중, 외부에서 부르는 호출처가 0건인 3건만 이번에 옮겼습니다. 파일을 새 패턴 폴더로 이동하고, 패키지 선언을 바꾸고, 같은 패키지에 기대던 의존 클래스는 import를 명시적으로 보강했습니다. 마지막으로 컴파일과 백엔드 재시작으로 확인했습니다.
외부 호출처가 0이라는 게 핵심입니다. 이 경우 파일 이동은 바깥에 아무 영향이 없어서, 컴파일과 재시작만 통과하면 검증이 끝납니다.
남은 1건은 옮기지 않고 보류했습니다. 옛 엔드포인트 하나가 deprecated 표시는 돼 있었지만, 웹 18곳과 내부 작업에서 지금도 호출 중이었습니다. deprecated 딱지가 붙었다고 곧바로 지울 수 있는 게 아닙니다. 호출처 18곳을 새 경로로 다 옮긴 뒤에야 안전하게 삭제할 수 있어서, 별도 작업으로 분리했습니다.
호출처가 많은 걸 함부로 건드리면 어디까지 깨지는지는, 기능 하나를 제거하려다 도미노로 번진 경험에서 이미 겪었습니다.
어중간한 위치와 명확한 잔존물은 다릅니다
점진 마이그레이션 중간 상태를 정리할 때, 두 종류를 구분하는 게 핵심이었습니다. 하나는 "어중간한 위치", 어디에 속하는지 모호하지만 호출처가 없는 코드입니다. 다른 하나는 "명확한 잔존물", 옛 패턴인 게 분명하지만 호출처가 많이 묶인 코드입니다.
전자는 호출처가 0이면 단순 이동으로 끝납니다. 후자는 deprecated 라벨이 붙어 있어도, 호출처를 먼저 옮기지 않으면 삭제가 곧 장애입니다. 그래서 삭제 가능 여부의 기준은 라벨이 아니라 호출처 수입니다.
한 번에 다 정리하려다 호출처 많은 곳에서 깨지면, 점진 마이그레이션 자체에 대한 신뢰가 떨어집니다. 단계를 나눠 안전한 것부터 처리하고, 위험한 것은 선행 작업을 명시해 다음 리스트로 넘기는 편이 결국 빠릅니다.
점검 체크리스트
신·구 패턴이 공존하는 코드를 정리할 때 다음을 점검하면 안전합니다.
코드 위치 분포를 숫자로 측정했는가 (어디에 몇 건인지)
정리 대상이 "어중간한 위치"인지 "명확한 잔존물"인지 구분했는가
이동·삭제 전에 외부 호출처 수를 셌는가
호출처가 많은 deprecated는 호출처 마이그레이션을 선행 작업으로 분리했는가
단순 이동은 컴파일·재시작으로 검증 가능한 범위인가
빠른 길은 한 번에 옮기는 게 아니었습니다
이번에 실제로 옮긴 건 어중간한 위치의 3건뿐이고, 가장 지우고 싶었던 deprecated 엔드포인트는 손대지 않았습니다. 호출처 18곳이 남아 있는 한, 라벨이 무엇이든 그건 아직 살아 있는 코드입니다. 점진 마이그레이션에서 빠른 길은 한 번에 다 옮기는 게 아니라, 안전한 것과 위험한 것을 갈라 순서를 정하는 일이었습니다.