🛠 육하원칙 기반 오류 보고 (Troubleshooting Guide)

1. 누가 (Who / Environment)

• 영향 범위
  • 외부 API (네이버 도서 검색 API) 연동 로직을 검증하는 백엔드 단위 테스트 환경
• 환경
  • Spring Boot, RestTemplate, MockRestServiceServer, JUnit5

2. 언제 (When / Timeline)

• 발생 시점
  • 네이버 도서 검색 API 조회 기능 구현 후, 외부 서버에 실제로 요청을 보내지 않고 응답을 모킹해서 격리된 테스트 코드 작성 및 실행 중 발생

3. 어디서 (Where / Location)

• 기능 계층

  • 백엔드 테스트 코드 MockRestServiceServer.expect(requestTo(expectedUrl))검증 단

    

    

4. 무엇을 (What / Symptom)

• 현상
  • 도서 제목 검색 기능 테스트 중, 영어 키워드로 검색할 때는 테스트가 성공하지만 한글 키워드(ex: “에러나는책”)를 파라미터로 넘겨 테스트를 실행하면 AssertionError가 발생하며 테스트 실패
• 에러 로그
  • java.lang.AssertionError: Request URI expected:https://openapi.naver.com/...query=에러나는책 but was:https://openapi.naver.com/...query=에러나는책

5. 왜 (Why / Cause)

• RestTemplate의 내부 자동 URL 인코딩 동작 방식에 대한 이해 부족
  • 테스트 코드에서 가짜 서버가 기대해야 할 URL(expectedUrl)을 "?query=에러나는책 과 같이 사람이 읽을 수 있는 평문 한글로 하드코딩해서 설정함
  • 실제 비즈니스 로직에서 HTTP 요청을 수행하는 RestTemplate은 내부적으로 UriTemplateHandler를 통해서 Non-ASCII 문자(한글 등)가 포함된 URI를 안전하게 전송하기 위해 자동으로 UTF-8 기반의 퍼센트 인코딩(Percent-encoding)을 수행함.
  • 결과적으로 가짜 서버(Mock)는 평문 한글을 기다리고 있는데, RestTemplate은 인코딩된 문자열(%EC%97… )을 던졌기 때문에 두 URL이 일치하지 않는다고 판단해서 테스트가 실패하게 됨

6. 어떻게 (How / Action)

• 디버깅 및 조치 내용

  • 테스트 코드 내에서 expectedUrl을 정의할 때, 한글 파라미터 부분을 RestTemplate의 내부 동작과 동일하게 명시적으로 인코딩하도록 수정

  // AS-IS (실패)
  String expectedUrl = naverBookSearchUrl + "?query=에러나는책";
  
  // TO-BE (성공)
  String encodedQuery = URLEncoder.encode("에러나는책", StandardCharsets.UTF_8);
  String expectedUrl = naverBookSearchUrl + "?query=" + encodedQuery;
  

• 결과 및 느낀점

  • 한글 파라미터가 포함된 테스트가 통과하게 되어서 테스트 커버리지 확보
  • Spring 프레임워크가 제공하는 RestTemplate이나 WebClient 등의 컴포넌트가 내부적으로 데이터를 어떻게 직렬화/인코딩 하는지 이해하는 계기가 되었음