개발 slecs

공급자 포털에서 상품 목록 썸네일 누락 버그 수정

목차

supplier-portal에서 상품 목록 썸네일이 표시되지 않는 버그를 수정했다. my-products 화면에서 UUID 기반으로 썸네일을 조회하는 경로에 문제가 있었고, 변경한 파일은 내부 클래스 하나, SQL 매퍼 하나다.

증상 자체는 단순했다. 썸네일이 없음. 그런데 로그에 아무것도 남지 않았다. 에러가 터졌다면 스택 트레이스라도 보일 텐데, 아무것도 없으니 처음엔 렌더링 문제인지 API 문제인지조차 불분명했다.

원인 파악이 먼저다

로그가 없다는 건 예외가 소리 없이 삼켜졌거나, 분기 처리 자체가 누락됐다는 뜻 중 하나다. 두 경우 모두 "처리는 됐는데 아무 일도 안 일어남" 상태를 만든다. 이런 버그가 가장 찾기 어렵다. 시스템이 "나 죽었어요"라고 말을 안 하니까.

파고들어 보니 특정 케이스에서 분기 처리가 빠져 있었다. UUID로 이미지를 매핑하는 로직에서, 특정 조건에 해당하는 상품은 그냥 통과해버리는 경로가 있었다. 결과적으로 썸네일 데이터가 세팅되지 않고 빈 값이 내려왔다.

이런 패턴은 코드베이스 어디서나 나올 수 있다:

// 조건 처리가 누락된 전형적인 패턴
for (Product p : products) {
    if (p.getType() == ProductType.BASIC) {
        p.setThumbnailUrl(imageMapper.findByUuid(p.getUuid()));
    }
    // PREMIUM 타입은 여기서 아무것도 안 함 → 썸네일 null
}

SQL 매퍼 쪽에도 문제가 있었다. 집계 쿼리에서 조건이 의도한 범위보다 좁게 걸려 있어서, 일부 상품 UUID에 대해 조회 결과가 0건으로 나왔다. SQL이 에러를 던지지 않고 그냥 빈 결과를 돌려주니 로그가 남을 이유가 없었던 것.

버그를 찾고 나면 "아, 이거였어?" 싶은데, 찾기 전까지는 아무 단서가 없어서 코드를 한 단계씩 직접 따라가야 했다. 로그가 아예 없는 상황에서 이걸 하는 게 얼마나 시간이 걸리는지는 겪어봐야 안다.

수정과 검증

SQL 매퍼는 쿼리 조건과 집계 범위를 바로잡았다. 내부 클래스는 타입별 분기 처리를 명시적으로 추가했다.

수정 방향을 결정할 때 한 가지 고민이 있었다. 누락된 타입을 else로 묶어서 처리할지, 각 타입을 명시적으로 나열할지. 코드 줄 수는 전자가 짧지만, 나중에 새 타입이 추가됐을 때 또 같은 버그가 생길 가능성이 있다. 그래서 명시적으로 나열하는 쪽을 택했다.

// 수정 후: 타입을 명시적으로 처리, 예외는 로그로 남김
for (Product p : products) {
    String uuid = p.getUuid();
    if (uuid == null) continue;

    switch (p.getType()) {
        case BASIC:
        case PREMIUM:
            p.setThumbnailUrl(imageMapper.findByUuid(uuid));
            break;
        default:
            log.warn("Unhandled product type for thumbnail: {}", p.getType());
    }
}

예외를 조용히 삼키는 패턴도 이번에 같이 잡았다. catch 블록에서 아무것도 안 하거나 흔적만 찍고 넘어가는 코드가 해당 파일 안에 있었는데, 운영 환경에서 이런 코드는 디버깅 시간을 몇 배로 늘린다. 최소한 로그는 남겨야 한다.

수정 후엔 단순히 "되는 것 같다"로 끝내지 않고, 버그를 직접 재현해서 정상 동작을 확인했다. 수정 전 화면에서 썸네일이 비어 있음을 확인하고, 수정 후 같은 케이스로 다시 확인. 숫자 정합성은 관련 화면과 비교해서 cross-check했다.

버그 수정 시 체크 항목:

  • 같은 로직이 다른 경로에도 있는지 (중복 코드 체크)
  • 수정이 기존 정상 케이스를 망가뜨리지 않는지 (회귀 방지)
  • 해당 화면 또는 API에서 실제 동작 확인
  • 관련 숫자를 다른 화면과 cross-check

비슷한 패턴이 다른 곳에도 있는지까지 확인했고, 위험해 보이는 케이스는 함께 수정했다. 단순히 증상만 픽스하고 끝내는 게 아니라 왜 발생했는지 원인을 파악하는 게 먼저라는 얘기다.

작업 후기

사내 서비스를 만들다 보면 기능 하나가 화면에 버튼 하나 추가하는 것으로 끝나지 않는다는 걸 계속 체감한다. SQL 집계, 상태 머신, 예외 처리, 화면 렌더링, 권한 체크가 모두 엮여 있어서 어느 하나만 빠뜨려도 숫자가 맞지 않거나 특정 사용자에게 이상한 화면이 나타난다.

공급자 포털처럼 상품 정보가 직접 노출되는 도메인은 "대충 맞는 것 같다"로 넘어가면 반드시 다시 돌아온다. 썸네일 누락 하나가 공급자 입장에선 "내 상품 정보가 제대로 관리되고 있는 건가?" 하는 의구심으로 이어질 수 있다. 숫자 하나, 이미지 하나가 신뢰 문제로 번지는 도메인이다.

개발 습관 쪽에서 이번 작업에서 다시 확인한 것들:

  • 변경 전 현재 동작을 스크린샷이나 수치로 메모해두기
  • 커밋 메시지는 "무엇을" 보다 "왜"를 담으려고 노력
  • 논리적으로 독립된 단위로 커밋을 쪼개는 습관 유지

작은 커밋을 자주 하면 문제가 생겼을 때 어느 변경에서 깨졌는지 찾기 훨씬 쉽다. git bisect를 쓸 수 있는 상황이라면 이 가치는 더 커진다. 커밋 메시지도 fix bug 대신, 왜 이 분기 처리가 필요했는지 한 줄이라도 남겨두면 몇 달 뒤에 같은 코드를 다시 볼 때 본인한테 도움이 된다.

엣지 케이스를 꼼꼼히 따지는 게 귀찮아 보여도, 나중에 같은 버그로 다시 오는 시간 비용이 훨씬 크다.

이어보기

댓글 0

첫 댓글 달아줘.