Controller 세 개 삭제로 기술 부채 해소하고 유지보수성 향상

오래된 Controller 세 개를 지운 날이었다. 기능 변경 없음, 사용자가 체감하는 차이 없음. 그럼에도 이 작업이 의미 있는 이유는 분명하다.

코드 리뷰를 하다 보면 "이건 나중에 꼭 정리해야지"라는 생각이 드는 지점들이 있다. 처음엔 하나둘이지만 쌓이면 무시하기 어려운 수준이 된다. 어느 순간부터 새 기능을 추가할 때 "이 파일 건드려도 되는 건지" 확인하는 시간이 생기기 시작하고, 팀원 누군가는 잘못 이해한 채로 비슷한 로직을 또 짜기도 한다. 이번에 정리한 Controller 세 개가 딱 그런 케이스였다.

역할이 불명확하게 쪼개져 있었고, 공통으로 쓰이는 데이터 처리 로직이 파일마다 중복돼 있었고, 네이밍이 제각각이라 어떤 Controller가 어떤 요청을 담당하는지 직관적으로 파악이 안 됐다.

어떤 구조 문제였나

크게 세 군데로 나눠서 봤다.

비즈니스 로직 레이어: Controller 안에 비즈니스 판단이 들어가 있었다. 이건 고전적인 fat controller 패턴이다. Controller는 요청을 받아서 적절한 서비스로 위임하는 역할만 해야 하는데, 조건 분기와 데이터 가공이 섞여 있으니 테스트 짜기도 번거롭고 재사용도 안 됐다.

데이터 처리 레이어: 세 Controller가 거의 동일한 데이터 전처리를 각자 구현하고 있었다. 처음엔 "이건 이 Controller만 쓰니까 여기 있어도 되겠지"라고 생각해서 그렇게 됐을 거다. 근데 비슷한 맥락의 기능이 늘어나면서 복붙이 반복됐다.

뷰 레이어 네이밍: get_data, fetch_info, retrieve_result 같은 식으로 의미가 겹치는 이름들이 공존했다. 이름이 일관성 없으면 탐색 비용이 올라간다. IDE에서 심볼 검색할 때도, 코드 리뷰할 때도.

정리 방향은 아래처럼 잡았다.

// 제거: dead code + 명백히 사용 안 되는 Controller 통째로
// 이동: 비즈니스 로직 → Service 레이어, 공통 처리 → 유틸리티
// 이름 변경: 동사+명사 패턴 통일, 의도가 드러나게
// 분리: 하나의 Controller가 너무 많은 역할을 맡은 경우 책임 분배

수정 파일은 총 6개. 숫자만 보면 작은 변경 같지만, 각 파일 안에서 이동한 로직 덩어리가 꽤 있었다.

리팩토링할 때 지키는 원칙

한 번에 많이 건드리지 않는다. 이게 제일 중요하다.

범위가 커지면 검증이 어렵다. "6개 파일 바꿨는데 뭔가 이상한 것 같음" 상황에서 원인 찾는 건 고역이다. 이번엔 논리적으로 묶이는 것들만 같은 커밋에 담고, 기능 확인 후 다음 단계로 넘어갔다.

기준으로 삼는 체크리스트는 대략 이렇다.

• 삭제하는 코드가 실제로 불리는 곳이 없는지 전수 확인
• 이동하는 로직의 입출력이 동일한지 단위 테스트로 확인
• 리네이밍 후 참조 누락 없는지 빌드/린트로 확인
• 변경 전후 동작 비교 (기능 테스트 or 스모크 테스트)

이 순서를 지키면 "분명히 로직은 맞는데 왜 안 되지" 상황을 거의 막을 수 있다.

변경 후 기존 기능 동작 확인했고, 코드 탐색 시간이 눈에 띄게 줄었다. 같은 기능 수정 요청이 들어왔을 때 이전엔 "어떤 파일이지?" 찾는 시간이 있었는데, 이제는 바로 찾아서 고칠 수 있다.

기술 부채를 미루면 생기는 일

"기술 부채는 이자가 붙는다"는 말이 있는데, 직접 겪어보면 비유가 아니라 사실이다.

불명확한 코드가 쌓이면 온보딩 비용이 올라간다. 새로 합류한 팀원이 코드 파악하는 데 시간이 더 걸리고, 잘못 이해한 채로 구현하면 또 다른 부채가 생긴다. 기존 팀원들도 "이쪽 건드리면 어디 터질지 모른다"는 불안감이 생기면 변경을 꺼리게 되고, 그게 또 부채를 키운다.

리팩토링을 자주 하면서 확신하는 것 하나는, 코드는 처음부터 완벽할 수 없다는 거다. 요구사항이 바뀌고, 시스템에 대한 이해도가 달라지고, 팀 규모도 변한다. 그 과정에서 코드가 달라지는 건 당연하다. "완성된 코드"같은 개념은 없다. 주기적으로 다듬는 게 자연스러운 개발 흐름이고, 그게 쌓여서 유지보수하기 쉬운 시스템이 된다.

이번 작업은 외부에서 보면 아무것도 바뀐 게 없는 배포다. 근데 내부 구조가 바뀐 건 이후 작업 전부에 영향을 준다. 그래서 이런 작업이 "나중에 하면 되지"로 계속 밀리는 게 아쉽다. 지금 하는 게 제일 싸다.