정산·등급·포인트 마이그레이션 스크립트 정리로 유지보수성 개선

마이그레이션 스크립트는 묘하게 방치되기 쉬운 코드다. 기능 개발할 때는 "일단 돌아가게"가 우선이고, 나중에 정리하자고 마음먹은 게 반년, 일년씩 묵는다. 정산, 등급, 포인트 - 서비스에서 가장 민감하고 핵심적인 도메인들인데, 이 세 영역에 걸친 마이그레이션 스크립트들이 그런 식으로 쌓여 있었다.

이번 작업은 기능 변경 없이 이 스크립트들을 정리한 것. 수정 파일 6개, 변경 내용은 중복 제거, 이름 변경, 파일 삭제 위주다.

왜 마이그레이션 스크립트가 지저분해지는가

DB 마이그레이션 스크립트는 특성상 "한 번 실행하면 끝"이라는 인식이 강하다. 그래서 작성 당시엔 일단 돌아가는 것 위주로 짜고, 구조나 네이밍에 신경을 덜 쓰게 된다. 초반에 설계한 스키마가 요구사항 변화로 달라지면, 이걸 보정하는 스크립트가 또 붙고, 그 위에 또 붙고 - 이런 식으로 레이어가 쌓인다.

문제는 이게 나중에 코드 리뷰나 기능 추가할 때 발목을 잡는다는 것. 어떤 시점에 어떤 스키마 변경이 있었는지 추적하려면 여러 파일을 뒤져야 하고, DDL 정의가 어디 있는지 명확하지 않으면 뭔가 바꿔야 할 때 자신감이 떨어진다. 정산이나 포인트처럼 돈과 직결된 도메인은 특히 그렇다. 손대기 전에 "이거 다른 데 영향 없나?" 확인하는 데 드는 시간이 길수록 전체 작업 속도가 느려진다.

이번 정리 대상으로 잡은 세 축은 이랬다.

• DDL 스키마: 역할이 불명확한 부분 분리. 하나의 스크립트가 너무 많은 테이블을 건드리거나, 도메인 경계가 섞인 경우가 있었음
• 데이터 처리: 비슷한 변환 로직이 여러 스크립트에 흩어져 있던 걸 통합. 등급 계산과 포인트 적립 처리에서 중복이 특히 많았음
• 뷰 레이어: 네이밍 규칙이 스크립트마다 달라서 통일. v_, view_, 접두사 없음이 혼재해 있으면 자동완성 검색도 불편하고 의도 파악도 느려짐

리팩토링 범위를 어떻게 잡았나

리팩토링에서 가장 중요하게 생각하는 원칙은 한 번에 너무 많이 바꾸지 않는 것이다. 변경 범위가 넓으면 검증이 어렵고, 롤백이 필요할 때 어디서 잘라야 할지 모호해진다. 이번에도 논리적으로 연관된 것끼리 묶어서 단계적으로 진행했다.

실제 변경은 네 패턴으로 분류된다.

-- 제거: 이미 실행 완료된 후 dead code로 남아 있던 스크립트
-- 이동: 공통 로직을 해당 도메인의 책임 위치로
-- 이름 변경: 약어나 모호한 식별자 -> 의도가 드러나는 이름으로
-- 분리: 너무 큰 스크립트를 도메인 단위로 쪼개기

여기서 "제거"가 생각보다 까다로웠다. 마이그레이션 스크립트는 이미 운영 DB에 적용된 것들이라, "이거 지워도 돼?"를 판단하려면 실행 이력과 현재 스키마 상태를 대조해야 한다. 검증 방법은 단순했다. 스크립트가 만드는 테이블/컬럼이 현재 스키마에 실제로 존재하는지, 해당 스크립트를 참조하는 코드가 남아 있는지 훑는 것. 참조가 없고 스키마에 반영이 완료된 게 확인되면 제거 대상으로 분류했음.

변경 후 기존 기능 동작 확인했고, 가독성도 체감상 확연히 나아졌다.

트레이드오프를 굳이 얘기하자면, 이런 정리 작업은 기능 개발보다 우선순위를 받기가 어렵다는 거다. 눈에 보이는 변화가 없으니까. 설득이 필요하다면 "나중에 이 도메인 건드릴 때 드는 시간 vs. 지금 정리에 드는 시간"으로 따지는 게 현실적이다. 정산, 등급, 포인트는 앞으로도 분명히 건드릴 일이 생기는 도메인이라, 지금 정리해두는 게 확실히 이득이라는 판단이었음.

구조가 바뀌면 뭐가 달라지나

기능은 그대로인데 구조가 바뀌면 어떤 효과가 있는지, 이게 생각보다 크다. 같은 기능을 수정해야 할 때 이전에는 어느 파일을 봐야 할지 찾는 데 시간이 들었는데, 정리 후에는 수정 포인트가 명확해져서 작업 시작까지의 시간이 줄었다. 코드 탐색에 드는 시간이 줄면 실제 작업에 집중하는 시간이 그만큼 는다는 걸 이번에도 확인했음.

리팩토링을 반복하다 보면 드는 생각이 있다. 코드는 처음부터 완벽할 수 없다는 거. 처음 설계할 때의 도메인 이해도와 6개월 후의 이해도가 다르고, 요구사항도 달라지기 때문이다. 지금 보기엔 어색한 코드도, 그 당시엔 최선이었을 수 있다. 중요한 건 어색해진 걸 방치하지 않고 주기적으로 다듬는 것. '완성된 코드'는 없고 '지금 시점에서 최선인 코드'만 있다고 생각함.

기술 부채는 이자가 붙는다는 표현이 마이그레이션 스크립트 같은 인프라 코드에서 특히 잘 맞는 것 같다. 당장 눈에 안 띄어서 미루게 되지만, 그 사이 위에 코드가 계속 쌓이면 나중에 건드릴 엄두가 안 나게 된다. 결국 "지금 손대기 불편한 것"이 "나중엔 아무도 손 못 대는 것"으로 굳어버린다. 쌓이기 전에 미리 정리하는 게 답이라는 걸, 이번 작업으로 다시 확인했다.