[트러블 슈팅] TMAP API 다중 경로 조회 : Mono.zip으로 동시 요청 처리하기

개요

개인 지도 API 기반 토이 프로젝트인 "안심 맵(Ansim Map)" 을 개발하던 중, TMAP API 사용 과정에서 단일 경로만 반환되는 파라미터 제약 이슈를 발견했습니다.

 

사용자에게 "최적 경로"와 "안전한 대로 우선 경로"를 모두 제공하여 선택권을 주려는 프로젝트의 핵심 기능이 구현 불가능한 상황이었고, 이를 Spring WebFlux의 Mono.zip을 활용한 병렬 요청 처리로 해결했습니다.

 

본 글에서는 문제 상황 분석부터 해결 과정, 그리고 실제 코드 적용까지의 트러블 슈팅 전 과정을 정리하고자 합니다.

🚨 문제 상황

개인 토이 프로젝트에서 TMAP 자동차 경로 API를 사용하던 중, 사용자에게 여러 경로 옵션을 제공할 수 없다는 문제에 직면했습니다.

발생한 이슈

• TMAP API는 한 번의 요청당 하나의 경로만 반환
• 사용자가 "최적 경로 A"와 "최적 경로 B"를 비교할 수 없음

---

기존 코드

 

🔍 원인 분석

TMAP API 공식 문서를 확인한 결과 searchOption 파라미터는 다음과 같습니다.

searchOption 파라미터 명세

• 타입: Number (단일 숫자 값)
• 설명: 경로 탐색 옵션
• `0`: 교통최적+추천(기본값)
• `1`: 교통최적+무료우선
• `4`: 교통최적+고속도로우선
• `10`: 최단거리+유/무료
• `19`: 교통최적+어린이보호구역 회피
• 기타 옵션...

발견한 제약 사항

• searchOption 파라미터는 하나의 숫자 값(단일 값)만 받는 구조
• 배열이나 여러 값을 동시에 전달할 수 있는 방법이 없음
• 결론: 다중 경로를 얻으려면 여러 번 요청해야 함

💡 해결 방법

Spring WebFlux의 Mono.zip을 활용하여 두 개의 API 요청을 동시에 실행하고, 결과를 리스트로 묶어 반환하도록 구조를 변경했습니다.

핵심 아이디어

1. 단일 경로가 아닌 다중경로 최적 경로(searchOption=0)와 대로 우선 경로(searchOption=4) 요청을 동시에 생성
2. Mono.zip으로 두 비동기 작업을 병렬 실행
3. 두 결과를 List로 묶어서 프론트엔드에 전달

---

코드 수정

 

✅ 해결 결과

Before (단일 경로)

 

After (다중 경로 배열)

 

위 예시에서는 2개의 경로 옵션(최적, 대로 우선)였지만, 실제 프로젝트에서는 사용자에게 더 다양한 선택지를 제공하기 위해 7개의 경로 옵션을 동시에 조회하도록 확장했습니다.

 

Mono.zip의 장점은 요청 개수가 늘어나도 동일한 패턴으로 확장이 가능하다는 점입니다. 2개든 7개든 모든 요청이 병렬로 처리되어 응답 시간은 가장 느린 단일 요청과 비슷한 수준으로 유지됩니다.

 

📚 참고 자료

• TMAP API 경로 안내 공식 문서
• Spring WebFlux Mono.zip Documentation

🎯 핵심 포인트

1. TMAP API는 단건 요청만 지원 - 다중 경로는 여러 번 호출 필요
2. Mono.zip 활용으로 동시 요청 처리하여 성능 최적화
3. searchOption 0(최적) + 4(대로 우선) 조합으로 사용자 선택권 확보
4. 반환 타입을 List로 변경하여 프론트엔드 통합 용이