네이밍 컨벤션의 부재는 장애로 이어진다.

안녕하세요 저는 프롭테크 플랫폼에서 백엔드 개발자로 근무 중인 3년차 백엔드 개발자 정정일입니다.

오늘은 소프트웨어 개발에서 중요한 것은 알지만 중요성에 비해 리소스 투자를 간과하기 쉬운 네이밍 컨벤션의 중요성에 대해 이야기해보려 합니다.

최근 저희 팀에서 실제로 겪었던 문제를 통해, 일관되지 않은 네이밍이 어떻게 시스템 안정성을 위협할 수 있는지 공유드리고자 합니다.

월세 검색 기능 오류

최근 저희 서비스의 특정 기능에서, 월세 키워드로 검색할 때 시스템 예외가 발생하는 문제가 있었습니다. 사용자 입장에서는 정상적인 검색 결과를 기대했지만, 특정 조건에서 시스템이 예외를 던지며 실패했던 것입니다.

이 문제는 겉으로는 드러나지 않았지만, 제가 올해 3월 팀에 합류한 이후 시스템 전반을 점검하는 과정에서 우연히 발견하게 되었습니다.

해당 기능의 동작 구조는 다음과 같습니다:

클라이언트(웹) 요청 -> 서비스 A 클라이언트 반환 → 클라이언트(웹) A의 응답 값으로 요청 → 서비스 B → DB 프로시저를 통한 조회

문제는 이 데이터 흐름에서, 각 컴포넌트가 ‘월세’라는 개념을 다르게 정의하고 있었기 때문에 발생했습니다.

문제의 근본 원인: ‘월세’ 네이밍 불일치

분석 결과, ‘월세’를 지칭하는 네이밍이 시스템 내에서 통일되어 있지 않았던 것이 예외 발생의 핵심 원인이었습니다.

저희는 마이크로서비스 아키텍처(MSA)를 기반으로 서비스가 구성되어 있으며, 각 서비스는 독립적으로 운영되지만 상호 연동은 필수적입니다. 이런 환경에서 공통 개념에 대한 명확한 약속이 없을 경우, 사소한 문자열 하나가 치명적인 오류를 일으킬 수 있습니다.

예를 들어 서비스 A에서는 월세를 다음과 같이 monthly로 반환하고 있었습니다:

1
2
3
4
5
6

val dealType = when { // 실제로는 Enum 클래스입니다. 설명을 위해 간략화 했습니다.
    dto.isDeal -> "deal"
    dto.isLease -> "lease"
    dto.isMonthly -> "monthly"
    else -> "none"
}

반면, 이 값을 수신하는 서비스 B와 연결된 데이터베이스에서는 월세를 rent 로 정의하고 있었습니다. 문제는 단순한 네이밍 불일치에 그치지 않았습니다. 데이터베이스 프로시저의 파라미터 중 ‘거래 유형’ 필드는 문자열 길이가 제한되어 있었고(VARCHAR(5)), monthly(7자)는 대상에서 초과되어 예외가 발생한 것이었습니다.

즉, 서비스 A → 서비스 B → DB로 전달되는 과정에서, DB는 monthly라는 값을 받아들이지 못해 유효성 예외를 던진 것입니다.

이를 임시로 해결하기 위해 서비스 A의 코드를 다음과 같이 수정했습니다

1
2
3
4
5
6

val dealType = when {
    dto.isDeal -> "deal"
    dto.isLease -> "lease"
    dto.isMonthly -> "rent" // 일시적 대응
    else -> "none"
}

하지만 이는 근본적인 해결책이 아니며, 네이밍 불일치가 또 다른 기능이나 서비스에서 문제를 일으킬 수 있는 잠재적 위험을 그대로 안고 있는 상태였습니다.

왜 지금까지 문제가 드러나지 않았을까?

이번 문제는 단순한 코드 오류처럼 보이지만, 그동안 왜 이 오류가 운영 중인 서비스에서 전혀 감지되지 않았는지는 중요한 포인트입니다.

이유는 다음과 같습니다:

1. 월세 키워드로 요청이 오는 경우 자체가 드문 기능이었기 때문입니다. 이 기능은 특정 조건에서만 활성화되며, 사용자도 특정 상황에서만 접근하는 구조여서 발생 빈도가 낮았습니다.

2. E2E 테스트의 미비. 사실 ISTQB와 같은 테스팅 관련 자격증에서도 완벽한 테스트란 존재하지 않고 결함이 없는 서비스는 존재하지 않는다고 말하고 있습니다.

   그렇기 때문에 꼭 테스트를 탓할 수 는 없지만 저희 팀이 단위 테스트에 좀더 집중한 면이 있었고 이때문에 E2E 테스트 케이스가 미비한 부분들이 있었습니다. E2E 테스트의 케이스가 좀 더 체계적이고 세밀했다면 사전에 결함을 탐지할 수 있었을 거라 생각합니다

3. 회사에 실시간 예외 감지 시스템이 없었습니다. 시스템 내부에서 예외가 발생해도 이를 자동으로 탐지하거나 알림으로 받아볼 수 없었기 때문에, 대부분의 오류는 사용자가 직접 고객센터에 제보해야만 파악이 가능했습니다. 이 부분이 저로써는 굉장히 빠르게 개선해야하는 부분이라는 생각이 들었습니다

유저분들은 장애가 있으면 그냥 떠나버린다.

여러분은 흔히 앱을 사용하시다 이상한 문구가 뜨며 내가 원하는 기능이 동작하지 않을때 어떻게 하시나요? 고객센터로 연락해서 설명하는 경우가 많으신가요? 아니면 “에잇!!” 하며 앱을 꺼버리는 경우가 많으신가요?

정말 필요한 기능이거나 많이 화나시지 않는 경우 대부분 유저분들은 앱을 그냥 꺼버리거나 하는 경우가 많으실 겁니다. 이처럼 사용자가 예기치 못한 상황을 맞닥드리더라도 회사 내부적으로 파악하기는 모니터링 시스템 없이는 어려울겁니다.

이는 사용자 이탈이라는 비지니스적으로 치명적인 결과를 야기할 수 있기 때문에 아주 큰 문제가 될 수 있습니다.

유저분들의 대략적인 CS 유입 확률입니다. 이 수치들은 직접적인 통계 자료라기보다는 광범위한 고객 행동 연구를 바탕으로 한 경험적 추정치임을 참고해 주세요.

이처럼 사용자분들이 CS를 통해 유입해주시는 경우는 사용자 경험에 비해 굉장히 드물기 때문에 저희는 사용자 분들이 맞이한 장애를 CS유입 없이 탐지할 필요가 있다고 저는 생각합니다.

제가 3월에 합류한 이후, 운영 안정성을 높이기 위한 작업의 일환으로 Loki, Grafana, Tempo 기반의 관측 및 모니터링 시스템을 구축 하는 티켓을 발행하여 작업을 진행했고, 그 과정에서 예외 알림 시스템도 함께 도입했습니다.

이 과정은 따로 글로 한번 다루도록 하겠습니다.

이 시스템 덕분에, 비정상 요청에 대한 예외가 실시간 알림으로 도착했고, 그제서야 이 문제가 있다는 것을 팀에서 명확히 인지하게 된 것입니다.

결국 이 문제는 낮은 사용 빈도와 관측 도구의 부재라는 두 가지 이유로 그동안 수면 위로 드러나지 않았던 것입니다.

드러나지 않았던 기술 부채

이 문제를 계기로 시스템 전체를 살펴보면서, ‘월세’라는 개념을 지칭하는 방식이 서비스별로 얼마나 다르게 사용되고 있었는지 확인할 수 있었습니다.

예시로는 다음과 같습니다:

• 어떤 DB 필드는 monthly를 사용
• 어떤 DB 필드는 rent를 사용
• 다른 API에서는 MONTHLY_LEASE
• 특정 enum 구조에서는 MONTHLY_LEASE와 SHORT_TERM_LEASE가 같은 값으로 설정되어 있음:

1
2
3
4
5
6

enum class OfficeDealType(...) {
    SALE("매매", "DEAL"),
    LEASE("전세", "LEASE"),
    MONTHLY_LEASE("월세", "MONTHLY_LEASE"),
    SHORT_TERM_LEASE("단기임대", "MONTHLY_LEASE"), // 단기임대도 동일한 값 사용
}

• 또 어떤 DB에서는 아예 한글로 월세, 전세 등 한글 명칭을 그대로 사용하고 있음

이처럼 하나의 개념(월세)을 두고 네이밍이 제각각 사용되고 있는 상황은, 단순한 코드 스타일의 문제를 넘어 시스템의 일관성과 안정성을 해치는 기술 부채로 이어집니다.

마치 끊어지기 직전의 줄을 타고 있는 듯한 위험한 상태였던 셈이죠.

특히 이번 조사를 통해 확인한 바에 따르면, deal_type 관련 네이밍 불일치를 수정해야 할 테이블만 약 30개에 달하며, 서비스 전체에 대해서도 전수조사가 필요한 상황입니다.

결국, 초기 단계에서의 작은 귀찮음과 컨벤션 부재가 시간이 지날수록 더 큰 개발 및 유지보수 리소스를 소모하게 만든다는 사실을 명확히 보여주는 사례이기도 합니다.

이 작업을 해야하는 저는 많이 힘들겠죠? 🤣

네이밍 컨벤션은 시스템 견고성을 위한 최소한의 약속

이번 사례를 통해 저희 팀은 네이밍 컨벤션의 중요성을 다시 한 번 실감했습니다. 특히 마이크로서비스 기반 환경에서는 서비스 간 데이터를 주고받는 일이 빈번하기 때문에, 명확한 명세와 일관된 네이밍이 없다면 다음과 같은 문제들이 쉽게 발생합니다

1. 예측 불가능한 시스템 오류 네이밍 불일치와 필드 제약이 맞물리면, 사용자 경험과 직결되는 예외가 언제든 발생할 수 있습니다.

2. 개발 및 유지보수 비용 증가 개발자는 올바른 값이 무엇인지 유추하기 위해 코드를 계속 추적해야 하며, 잘못된 네이밍으로 인해 발생한 버그를 해결하는 데 불필요한 리소스가 낭비됩니다.

3. 가독성과 시스템 이해도 저하 하나의 개념이 여러 방식으로 표현되면, 전체 시스템의 맥락을 이해하기 어려워집니다. 이는 신규 개발자 온보딩에도 큰 장애물이 됩니다.

4. 협업 비효율 개발자 간 커뮤니케이션에서 용어의 불일치는 오해를 유발하고, 리뷰 및 문서화 과정에서도 혼선을 초래합니다.

앞으로의 계획: 네이밍 일관성 확보를 위한 전사적 표준화

저희 팀은 이번 문제를 단순한 버그 수정으로 끝내지 않고, 시스템 전반의 네이밍 컨벤션을 통일하기 위한 정비 작업에 착수했습니다.

단기적으로는 ‘월세’와 같은 주요 개념에 대한 명확한 명세를 마련하고, 중장기적으로는 전 서비스에서 일관되게 적용될 수 있도록 구조화된 표준안을 마련할 예정입니다.

이는 단순히 코드 품질을 높이는 차원을 넘어, 시스템 안정성, 운영 효율성, 개발 생산성을 모두 높이는 아주 중요한 작업이라고 판단하고 있습니다.

마치며

사소해 보이는 네이밍 하나가 시스템 전체에 얼마나 큰 영향을 줄 수 있는지, 이번 일은 제게 아주 큰 교훈을 줬습니다.

네이밍 컨벤션을 위해 팀 전체가 협의하는 과정들을 거쳐야 한다는 이유때문에, 혹은 귀찮음, 또는 당연히 이렇게 쓰고있겠지 하는 추측 등으로 팀 전체가 하나의 네이밍 컨벤션을 가지지 못하는 경우들이 있었는데 저 또한 이런점을 간과하거나 미루는 경우들이 있었습니다.

다시 한번 반성하게 됐고 저부터가 이런 일이 없도록 팀 전체가 네이밍을 공유할 수 있는 환경을 구성하려 합니다.

혹시 비슷한 일이 있으셨다면 이 글이 조금이라도 도움이 됐으면 하며 이만 글을 마치겠습니다. 읽어주셔서 감사합니다.