주소정제 서비스 내재화 - 4화 ( 슬픈예감 )

Context

주소정제 1.0이 행정안전부 주소 조회 API에 의존하면서 정확도와 성능 문제를 야기했다. 단독건물과 복합건물의 특성이 상이하지만 모두 외부 API를 호출하는 비효율이 발생했다.

Technical Solution

• 전국 1,080만 개 건물을 자체 DB로 구축: 도로명 기본주소, 지번주소, 건물 타입 등 메타데이터 포함
• AddressSearchParam 객체 설계: 도로명(시/도 → 시/군/구 → 법정동 → 도로명 → 건물본번 → 건물부번) 및 지번주소(시/도 → 시/군/구 → 법정동 → 면/리 → 번 → 지) 순서로 순차 추출
• 단독건물 정제 로직 도입: 도로명 기본주소로만 건물 DB 조회해 정확히 1개 결과 반환 시 정제 완료, 나머지는 기존 흐름 유지
• 주소 파싱 알고리즘 구현: 시/도 정보는 replaceSidoName() 함수로 '서울', '서울시', '서울특별시' 등 표기 통일, 시/군/구는 '수원시 영통구' 같은 복합 음절 케이스를 우선 처리하고 '시'글자 누락 케이스(수원 장안구) 대응
• 행정구역 변경 대응: 부천시 원미구·소사구·오정구 통합(2024.01.01) 및 전라북도특별자치도 변경(1월 18일) 시 동적 쿼리 변환 로직 추가
• Exception 안전성 강화: AddressSearchParam 생성 과정에서 특정 주소 아이템 추출 실패 시에도 예외 발생 안 함(부분 정보만으로도 정제 가능하기 때문), 모든 단계에서 외부 업체 호출 폴백 옵션 구현

Impact

• 외부 API 호출량 60% 감소 (초기 예상 90%에서 실제 60%로 수정됨. 단일건물 98% 비율이 건물당 주문 빈도 차이로 인해 트래픽 감소율과 불일치)
• 전라북도특별자치도 행정구역 변경 시 약 80만 건 건물 대량 변경에도 긴장 없이 대응

Key Takeaway

도메인 데이터(건물 정보)를 자체 DB화하면 외부 API 의존성을 줄일 수 있지만, 통계적 비율(건물 타입별)과 실제 트래픽 패턴(건물당 주문 빈도)은 일치하지 않을 수 있으므로 예상 효과와 실제 결과를 분리해서 분석해야 한다. 부분 정보로도 작동 가능하도록 설계하고 Exception 안전성을 우선시하면 행정구역 변경 같은 외부 변수에 대응력이 높아진다.