API 중계 서비스 신뢰성 점검

이 글은 재사용할 수 있는 운영 템플릿이며, 특정 중계 서비스에 대한 Folkbench의 실측 결과가 아닙니다. Folkbench의 평가 사실이 되려면 실행(run), 시각, 샘플, 한계가 담긴 게시 스냅샷이 있어야 합니다.

목표

새 API 중계 서비스를 프로덕션 연동에 추가하기 전에 가장 작은 요청 경로가 동작하는지 확인하고, 실패를 클라이언트, 프로토콜, 업스트림, 서버 측의 네 가지로 분류합니다. 다른 엔지니어가 같은 요청으로 이 점검을 다시 수행할 수 있어야 합니다.

사전 준비

실제 사용자 데이터가 들어 있지 않은 고정 요청 샘플을 준비합니다. 모델 ID, 요청 본문, 스트리밍 여부, 타임아웃, 재시도 횟수, 테스트 시각을 기록합니다. 테스트용 자격 증명은 로컬 시크릿 매니저나 임시 환경 변수에만 두고, 로그, 스크린샷, 저장소, 공개 페이지에는 절대 남기지 않습니다.

1단계: 요청과 관찰 범위 고정하기

먼저 최소한의 요청으로 HTTP 상태 코드, 응답 헤더, 응답 본문이 제공업체 문서와 일치하는지 확인합니다. 요청 ID, 모델 ID, 상태 코드, 총 소요 시간을 테스트 시트에 기록합니다. 전체 Authorization 헤더나 원본 응답을 티켓에 그대로 붙여 넣지 마세요.

엔드포인트가 스트리밍을 지원한다면 스트리밍 요청을 따로 한 번 더 실행합니다. 첫 번째 유효 데이터 청크가 도착하기까지의 시간, 청크가 끊기지 않고 계속 도착하는지, 완료 이벤트가 나타나는지, 연결이 닫힐 때 클라이언트가 명확한 결과를 받는지를 기록합니다. SSE는 이벤트 스트림이므로 네트워크 패킷 경계로 토큰을 짐작하지 말고 이벤트 경계에 따라 파싱해야 합니다.

2단계: 실패 분류하기

고정된 입력으로 다음 각 경우를 확인합니다.

1. 클라이언트 오류: 잘못된 모델, 누락된 파라미터, 요청 한도 초과에는 원인을 짚을 수 있는 4xx 결과가 반환되어야 합니다.
2. 인증 오류: 만료되었거나 권한이 부족한 자격 증명은 명확히 거부되어야 하며, 응답에 다른 자격 증명이나 내부 주소가 노출되어서는 안 됩니다.
3. 업스트림 오류: 업스트림의 타임아웃, 속도 제한, 일시적 장애는 재시도할 수 있는 경우와 없는 경우로 구분되어야 합니다.
4. 스트리밍 오류: 연결 중단, 완료 이벤트 누락, 불완전한 JSON 이벤트는 정상 완료된 텍스트로 취급되지 않고 실패 경로로 들어가야 합니다.

실패마다 적어도 상태 코드, 오류 분류, 클라이언트 관측 시간, 민감 정보를 가린 짧은 요약을 남깁니다. 원본 응답, 트레이스, 스크린샷은 과정 증거이므로 비공개 객체 스토리지 절차에 따라 보관하고, 공개 글이나 순위에는 넣지 않습니다.

3단계: 재시도 범위 정하기

명확한 멱등성 의미가 있거나 안전하게 반복할 수 있는 요청만 자동으로 재시도합니다. 재시도 전체에 예산을 정하고, 첫 요청과 마지막 요청의 ID를 서로 연결해 둡니다. 인증 실패, 잘못된 파라미터, 콘텐츠 정책에 따른 거부는 무작정 재시도하지 마세요.

알아보기 쉬운 검수표에는 다음과 같은 항목을 넣을 수 있습니다.

통과 기준과 정리

통과 기준은 테스트 전에 미리 적어 둡니다. 예를 들면 “고정 요청이 독립된 세 번의 시도에서 모두 완전한 결과를 반환하고, 스트리밍 요청에는 명확한 완료 이벤트가 있으며, 인증 실패는 재시도하지 않는다”와 같은 식입니다. 결과를 본 뒤에 기준을 바꾸지 마세요.

테스트가 끝나면 임시 자격 증명을 폐기하고, 로컬에 남은 원본 응답을 삭제하고, 요약, 타임스탬프, 버전만 담은 검수 기록을 남깁니다. 결과를 Folkbench에 게시하려면 먼저 실제 run/attempt, 증거 매니페스트, 게시 스냅샷을 연결해야 합니다. 이 글 자체가 그런 사실을 대신하지는 않습니다.