Swagger가 정상인데 SDK가 실패한다면, SDK는 거짓말을 하고 있다

Source: Dev.to

설정

저는 기능‑플래그 / 런타임‑구성 서비스(휴일에 재미로 만든 것)를 만들고 있었습니다.
아이디어는 간단했습니다:

• 백엔드가 환경별로 구성 값을 노출한다.
• SDK가 런타임에 이를 가져온다.
• 같은 토큰, 같은 환경, 같은 키.

Swagger UI는 완벽히 작동했지만 SDK는 다음과 같은 오류를 던졌습니다:

ConfigNotFoundError: config not found in environment 'development'

Swagger가 거짓말을 한 것은 아니었습니다—요청, 헤더, 해석된 환경, 그리고 올바른 응답을 모두 보여주었습니다.

문제는 라우트 불일치였습니다:

• 백엔드가 노출한 라우트:

  GET /api/v1/sdk/configs/{key}

• 내 SDK가 URL을 구성한 방식:

  /api/v1/config/{key}

SDK는 조용히 404를 반환했으며 예외나 경고가 없었고, 그 결과 몇 시간 동안 디버깅에 허비되었습니다.

교훈

• SDK는 백엔드 라우트를 문자 그대로 일치시켜야 합니다.
• 기억할 필요가 있다면 알림을 설정하세요—그렇지 않으면 유령 버그를 잡느라 며칠을 보낼 수 있습니다.

추가 함정

구성은 다음과 같이 저장되었습니다:

FEATURE_CHECKOUT_ENABLED

하지만 SDK 사용자는 다음과 같이 전달할 수 있었습니다:

"feature_checkout_enabled"

이로 인해 발생한 문제:

• 캐시 미스
• 잘못된 “찾을 수 없음” 오류
• 일관성 없는 결과

해결: 입력을 한 번 정규화하고 모든 곳에서 강제 적용합니다(API 호출 전, 캐시 전, 비교 전).

이 경험이 가르쳐 준 것

• Swagger는 당신의 계약입니다.
• SDK는 누락으로 거짓말을 할 수 있습니다.
• 라우트 불일치는 조용한 살인자입니다.
• 정규화는 유령 버그를 방지합니다.
• Swagger가 작동한다면, 백엔드는 무죄입니다.
• Swagger 먼저. SDK 다음. 데이터베이스 마지막.