SQL 쿼리 정리로 코드 일관성과 가독성 개선

이번 커밋은 파일 한 개 건드린 거라 커밋 로그만 보면 별거 아닌 것처럼 보이는데, 실제로는 신경 쓸 게 꽤 있었던 작업이었음.

변경 범위는 XML 쿼리 파일 1개. 백엔드 자바 코드도, JSP도, CSS도 건드리지 않았음. 그런데 작업 시간은 생각보다 길었다. SQL 한 줄 고치면 되는 게 아니라, 기존 쿼리가 어떤 맥락에서 왜 그렇게 짜였는지 파악하는 데 시간을 꽤 썼기 때문임.

왜 SQL 쿼리 파일을 손봤나

MyBatis XML mapper 파일은 프로젝트가 길어지다 보면 자연스럽게 복잡해진다. 처음에 급하게 붙인 동적 쿼리 조각이 그대로 남고, 어느 시점부터 아무도 쓰지 않는 <if> 블록이 살아남기도 하고, 네이밍이 제각각인 resultMap이 2~3개씩 비슷하게 공존하기도 함.

이번에 건드린 부분도 비슷한 맥락이었음. 불필요하게 붙어있던 조건 분기를 걷어내고, 동일한 결과를 내는 쿼리가 미묘하게 다른 형태로 중복되어 있던 것을 정리했음. 기능상 차이는 없지만, 읽는 사람 입장에서 "이 두 쿼리가 왜 따로 있지?"라는 의문이 생기면 그게 이미 유지보수 비용임.

쿼리가 복잡하거나 중복되어 있으면 문제는 실제 장애가 났을 때 터진다. 비슷하게 생긴 쿼리 두 개 중 어느 쪽에서 슬로우 쿼리가 발생하는지 로그 보면서 헷갈린 경험이 한 번이라도 있으면, 이런 정리 작업이 왜 필요한지 바로 납득이 됨.

변경 원칙과 실제 적용

이번 작업에서 지킨 원칙 몇 가지를 정리하면:

코드 변경 자체보다 리뷰 가능성을 높이는 게 우선이었음. 변경 단위가 작으면 리뷰어가 "이 조건 왜 삭제했어?"를 추적하기 쉽고, 문제가 생겼을 때 롤백 단위도 작아짐.

실제로 이번 정리 결과 XML 파일에서 지운 부분은 이런 식이었다:

<!-- before: 동일한 파라미터를 다른 경로로 처리하는 중복 쿼리 존재 -->
<select id="selectFooList" parameterType="map" resultMap="FooResult">
    SELECT ...
    FROM foo
    <where>
        <if test="status != null and status != ''">
            AND status = #{status}
        </if>
        <!-- 아래는 위와 동일한 조건인데 다른 쿼리 ID로 분리돼 있던 것 -->
    </where>
</select>

<!-- after: 단일 쿼리로 통합, 불필요 분기 제거 -->
<select id="selectFooList" parameterType="map" resultMap="FooResult">
    SELECT ...
    FROM foo
    <where>
        <if test="status != null">
            AND status = #{status}
        </if>
    </where>
</select>

status != '' 조건은 파라미터 바인딩 레이어에서 이미 처리되고 있어서 쿼리 레벨에서 중복 체크할 필요가 없었음. 이런 것들이 쌓이면 쿼리가 실제보다 복잡해 보이고, 조건 수정할 때 어디 건드려야 하는지 헷갈리게 된다.

당장 티 안 나는 작업의 가치

이런 작업은 기능 티켓이 아니라서 배포하고 나서 뭔가 달라 보이지 않음. QA에서 잡아내는 버그도 아니고, 사용자가 체감하는 속도 개선도 아님. 그래서 팀 입장에서 우선순위가 밀리기 쉽다.

근데 내가 이걸 계속 챙기는 이유는 두 가지임.

첫째, 6개월 뒤의 나. 기능 개발에 치여 있다가 이 파일 다시 열었을 때 "이 조건이 왜 두 군데 있지?"라고 멍청하게 시간 보내는 게 싫어서임. 지금 정리해두면 미래의 내가 다른 곳에 시간을 쓸 수 있음.

둘째, 옆에서 같이 개발하는 사람들. 쿼리 파일을 누군가 새로 처음 보는 상황을 상상해보면, 비슷하게 생긴 쿼리가 이유 없이 두 개 있으면 "뭔가 다른 이유가 있나?" 하고 괜히 시간을 쓰게 됨. 코드는 혼자 읽는 게 아니니까.

• 미래의 나: 6개월 후 이 파일 다시 봐도 왜 이렇게 짰는지 바로 보여야 함
• 다음 개발자: 맥락 없이 처음 보는 사람도 흐름이 따라와야 함
• 새벽 3시 장애 상황: 로그 보면서 원인 추적할 때 쿼리 구조가 발목 잡으면 안 됨

코드 일관성은 팀 전체 속도에 영향을 주고, 그게 쌓이면 시스템 신뢰도가 달라짐. 당장 수치로 안 나와도.

배포 후에 특별히 이상 없었고, 예상대로 동작 변화 없이 조용히 올라갔음. 이게 이 작업의 성공 기준이기도 함.