요약 :

🛠 육하원칙 기반 오류 보고

1. 누가 (Who / Environment)

• 영향 범위
  • 도서 등록 시 네이버 도서 검색 API를 통해 책 정보를 자동으로 불러오는 기능에서 프론트엔드 이미지 렌더링 오류 발생
• 환경
  • Sprint Boot BE, PE 클라이언트, OpenAPI(Swagger) 명세서 기반 환경

2. 언제 (When / Timeline)

• 발생 시점
  • 백엔드에서 네이버 도서 검색 API 연동(BookService.getBookInfoByIsbn)개발을 마치고, 프론트엔드와 최초 API 연동 테스트를 진행할 때 발견

3. 어디서 (Where / Location)

• 기능 계층
  • 백엔드의 네이버 API 응답 파싱 및 DTO 변환 로직, 그리고 프론트엔드의 도서 썸네일 이미지(<img> 태그) 렌더링 컴포넌트

4. 무엇을 (What / Symptom)

• 현상
  • 사용자가 ISBN으로 도서를 검색했을 때, 제목과 저자 등 텍스트 정보는 정상적으로 출력되지만, 썸네일 이미지는 불러오지 못하는 현상 발생
• 분석
  • 프론트엔드의 네트워크 응답(Payload)과 브라우저 개발자 도구를 확인했을 때, 이미지 src 속성에 data:image/jpeg;base64,[<https://shopping-phinf.pstatic.net/main_>](<https://shopping-phinf.pstatic.net/main_>)... 와 같은 이상한 데이터 구조(Base64 헤더와 일반 URL 문자열)가 주입되고 있는 것을 확인함

5. 왜 (Why / Cause)

• API 명세서 디테일(데이터 타입) 인지 누락

  • API 명세서에는 썸네일 이미지 필드가 format: byte (Base64 인코딩 문자열)형태로 내려가기로 되어 있었고, 해당 명세서를 기반으로 프론트엔드가 Base64 디코딩 처리를 해놓은 상태.

  

  • 백엔드 개발 과정에서 해당 디테일(format: byte)을 빠트리고, 네이버 API가 반환하는 원본 데이터인 ‘이미지 URL 주소 문자열’을 별도 가공이나 인코딩 없이 그대로 프론트엔드에 바이패스(Bypass)해서 전달함.
  • 이로 인해서 명세서 스펙과 실제 반환 데이터 간의 불일치가 발생함

6. 어떻게 (How / Action)

• 디버깅 및 조치 내용
  1. 렌더링 에러 발생 직후 개발자 도구로 실제 네트워크 페이로드와 Swagger 명세를 대조해서 인코딩 로직 누락 파악
  2. API를 준수하기 위해서 백엔드 코드 리팩토링. 네이버 API가 준 URL을 그대로 던지지 않고, RestTemplate.getForObject(imageUrl, byte[].class)를 호출해서 이미지를 바이트 배열로 직접 다운로드함
  3. 다운로드한 데이터를 Base64.getEncoder().encodetoString() 을 통해 명세서에 정의된 규격으로 변환해서 응답 객체에 담음
• 결과 및 느낀점
  • 스펙에 맞춘 데이터가 내려가면서 추가 수정 없이 이미지가 정상적으로 렌더링 됨
  • API 명세를 좀 더 꼼꼼하게 숙지하는 것의 중요성을 배웠음.
  • 외부 API의 데이터를 그대로 전달하는 게 아닌 우리 서비스에 만들어 둔 규격에 맞게 데이터를 가공하는 작업의 중요성을 느낌.