🐛 API-Football 응답 오류 검증 및 로깅 보완

[son0307]

변경 사항

API-Football 응답 파싱 및 검증 보완

• Spring 7에서 사용하는 Jackson 3 타입에 맞춰 API-Football 응답 envelope의 JsonNode 타입을 변경했습니다.
• 실제 운영 환경과 동일한 Jackson 버전으로 /leagues 응답을 역직렬화하는 테스트를 추가했습니다.
• API-Football의 errors 필드가 빈 배열 또는 빈 객체인 정상 응답을 모두 허용합니다.
• errors가 배열이나 객체가 아니면 잘못된 응답으로 분류하고, 값이 존재하면 HTTP 200이어도 논리적 실패로 처리합니다.

외부 API 오류 기록 구체화

• ExternalApiException에 외부 provider가 반환한 오류 상세 정보를 별도 필드로 전달할 수 있도록 확장했습니다.
• API-Football의 errors 응답을 최대 2,000자로 제한하고 개행 문자를 제거한 뒤 안전한 오류 상세 정보로 보관합니다.
• 최종 외부 API 호출 실패 시 provider, operation, 오류 category, HTTP 상태, 재시도 여부, attempt 수와 API-Football 오류 상세 정보를 구조화된 ERROR 로그로 기록합니다.
• API 키, 인증 헤더, 요청 query와 전체 응답 본문은 로그에 포함하지 않습니다.

변경 이유

Spring 7 전환 이후 API-Football 응답 envelope가 Jackson 2의 JsonNode를 사용하고 있어, DTO 형식과 실제 응답이 정상이어도 시즌 동기화 요청이 External API response was invalid로 실패할 수 있었습니다.

또한 API-Football은 요청 자체가 정상 처리된 경우 HTTP 200을 반환하면서 실제 오류 원인을 errors 필드에 담을 수 있습니다. 기존 로그에는 HTTP 상태와 일반화된 메시지만 남아 어떤 요청이 왜 실패했는지 빠르게 확인하기 어려웠습니다. 응답 파싱 타입을 일치시키고 안전하게 정제한 provider 오류를 최종 실패 로그에 포함하도록 보완했습니다.

API 및 영향 범위

• 외부 REST API와 DB 스키마는 변경하지 않습니다.
• 기존 timeout, 빠른 재시도, 느린 재시도 및 서킷 브레이커 정책은 변경하지 않습니다.
• API-Football의 HTTP 200 논리 오류는 HTTP 통신 결과와 별개로 INVALID_RESPONSE category의 실패로 기록됩니다.

검증

• API-Football /leagues 정상 응답의 Jackson 3 역직렬화 테스트 통과
• 빈 배열·빈 객체 errors 정상 응답 검증 테스트 통과
• HTTP 200 오류 응답의 category, HTTP 상태 및 provider 오류 상세 정보 검증 테스트 통과
• ./gradlew.bat test --tests "com.son.soccerStreaming.apifootball.client.ApiFootballResponseValidatorTest" 통과
• git diff --cached --check 통과

프론트엔드 변경은 없어 별도 빌드를 수행하지 않았습니다.

[github-actions]

Codex PR Review

PR 요약

요약

API-Football 응답 검증 로직을 보완해, 정상 응답과 오류 응답을 더 정확하게 구분하고 실패 원인을 구조화된 로그로 남기도록 개선했습니다. Spring 7/Jackson 3 환경에 맞춘 응답 타입 정합성도 함께 정리했습니다.

주요 변경사항

• API-Football 응답 envelope의 JsonNode 타입을 Spring 7/Jackson 3 호환 타입으로 변경
• /leagues 정상 응답을 실제 운영과 유사한 Jackson 버전으로 역직렬화하는 테스트 추가
• errors 필드가 빈 배열/빈 객체인 정상 응답은 허용하고, 배열/객체가 아니면 invalid response로 처리
• HTTP 200이어도 errors가 있으면 논리적 실패로 분류하고 provider 오류 상세 정보를 함께 전달
• ExternalApiException에 provider 오류 상세 필드를 추가
• 외부 API 실패 시 provider, operation, category, HTTP 상태, 재시도 여부, attempts, provider error를 구조화된 ERROR 로그로 기록
• API 키, 인증 헤더, 전체 응답 본문은 로그에 포함하지 않도록 유지

영향 범위

• 외부 API 응답 검증
• 시즌/리그 등 API-Football 동기화 흐름
• 외부 API 실패 로깅
• 공통 외부 API 예외 처리

검증

• API-Football /leagues 정상 응답 역직렬화 테스트 추가/통과
• 빈 배열·빈 객체 errors 허용 테스트 통과
• HTTP 200 오류 응답의 category 및 provider 오류 상세 정보 검증 테스트 통과
• ./gradlew.bat test --tests "com.son.soccerStreaming.apifootball.client.ApiFootballResponseValidatorTest" 통과
• git diff --cached --check 통과

시니어 개발자 리뷰

• [P1] src/main/java/com/son/soccerStreaming/apifootball/client/ApiFootballResponseValidator.java:33-39 - errors 필드가 배열/객체여도 내용이 있으면 무조건 실패 처리됨

  • 문제: errors가 배열 또는 객체인 경우에만 정상 형식으로 인정하고, 곧바로 !errors.isEmpty()면 실패로 처리하고 있습니다. API-Football이 errors: {} 또는 errors: [] 외에, 의미 있는 오류를 담는 형태로 중첩 객체/배열 구조를 반환할 가능성이 있으면 현재 로직은 의도대로 동작합니다. 다만 이 구현은 “빈 배열/빈 객체만 성공”으로 고정되어 있어, 실제로 provider가 errors에 경고성 정보나 비치명적 메타를 포함해도 전부 실패로 분류됩니다. PR 설명상 HTTP 200 논리 오류를 잡는 것이 목적이지만, 응답 스키마 변경에 매우 취약합니다.
  • 영향: 외부 API가 사소한 형태 변경을 하거나 errors에 비어 있지 않은 보조 정보를 넣는 순간, 정상 조회까지 전부 INVALID_RESPONSE로 실패할 수 있습니다. 시즌/리그 동기화 같은 핵심 기능이 불필요하게 막힐 수 있습니다.
  • 수정 방향: API-Football의 실제 errors 규칙을 기준으로, “성공으로 간주할 수 있는 값”과 “실패로 간주해야 하는 값”을 더 명확히 분리하세요. 최소한 배열/객체의 비어 있음만 보는 대신, payload 안의 메시지/코드가 실제 오류인지 판단하는 조건을 함께 두는 것이 안전합니다.

• [P2] src/main/java/com/son/soccerStreaming/global/externalapi/ExternalApiExecutor.java:265-283 - provider 오류 상세가 구조화 로그에 그대로 들어가며 길이/문자 정제 외의 제어가 부족함

  • 문제: safeErrors()에서 개행/탭 제거와 2,000자 제한은 하고 있지만, external_api.provider_errors로 최종 로그에 그대로 넣고 있습니다. API 응답 JSON을 통째로 싣는 방식이라, 오류 메시지에 PII나 예상치 못한 대량 문자열이 포함되면 로그 가독성과 저장 비용이 나빠질 수 있습니다. 또한 replaceAll은 정규식 기반이라 빈번한 실패 경로에서 불필요한 비용이 생깁니다.
  • 영향: 외부 API가 긴 에러 payload를 반환할 때 로그 폭증, 분석 어려움, 운영비 증가가 발생할 수 있습니다. 실패 빈도가 높아지면 장애 대응 시 오히려 로그 탐색이 어려워질 수 있습니다.
  • 수정 방향: provider error는 가능하면 특정 필드만 추출해 기록하고, 전체 JSON을 남겨야 한다면 문자열 치환 대신 단순 문자 순회/replace로 비용을 줄이세요. 또한 로그 길이 상한을 두는 현재 방식은 유지하되, 길이 초과 시 잘렸음을 명시하는 접두/플래그를 추가하면 운영 시 더 유용합니다.

• [P3] src/test/java/com/son/soccerStreaming/apifootball/client/ApiFootballResponseValidatorTest.java:29-53 - 테스트가 실제 런타임 매퍼 설정과 완전히 동일하다는 보장이 약함

  • 문제: 새 테스트는 production Jackson 3 타입을 사용하려는 의도는 좋지만, 이 테스트가 애플리케이션에서 실제로 사용하는 ObjectMapper 설정/모듈 등록과 동일한지는 코드만으로 확인되지 않습니다. 즉, 테스트는 통과해도 실제 런타임에서는 커스텀 설정 차이로 다른 결과가 나올 수 있습니다.
  • 영향: 회귀 방지 효과가 기대보다 낮아질 수 있습니다.
  • 수정 방향: 가능하면 실제 애플리케이션 컨텍스트의 ObjectMapper를 주입받아 검증하거나, 최소한 실제 API 클라이언트가 사용하는 매퍼 설정을 테스트에 재사용하세요.

보안 리뷰

중대한 보안 문제 없음
Model: gpt-5.4-mini