본문으로 건너뛰기
· backend · 2분 읽기

gRPC status와 GraphQL 오류 코드를 연결하는 방법

클라이언트가 오류 메시지에 “재고”라는 단어가 있는지 검사해 화면을 분기하면 문구 수정도 API 변경이 된다. 모든 오류를 Internal로 보내면 사용자가 입력을 고쳐야 하는지 잠시 뒤 재시도해야 하는지 알 수 없다.

도메인 오류, gRPC 상태, GraphQL 확장 코드를 서로 다른 계층으로 둔다. 사용자 문구는 바뀔 수 있지만 분기용 코드는 안정적으로 유지한다.

도메인에서 전송 타입을 제거한다

go
type DomainError struct {
    Code   string
    Field  string
    Reason string
}

func (e *DomainError) Error() string {
    return e.Reason
}

이 타입은 설명용이다. 도메인 패키지가 gRPC나 GraphQL 패키지를 import하지 않게 하면 같은 업무 로직을 HTTP, 배치, RPC에서 재사용하기 쉽다. 오류를 감쌀 때도 원인 타입을 보존하고 errors.As 등으로 분류한다.

오류 코드 매핑

도메인 의미gRPC 상태GraphQL code 예시
입력 형식 오류InvalidArgumentBAD_USER_INPUT
인증 정보 없음UnauthenticatedUNAUTHENTICATED
권한 부족PermissionDeniedFORBIDDEN
대상 없음NotFoundNOT_FOUND
잔량 부족 등 상태 조건 불충족FailedPreconditionPRECONDITION_FAILED
낙관적 동시성 충돌AbortedCONFLICT
예상하지 못한 내부 오류InternalINTERNAL_SERVER_ERROR

오른쪽 코드는 이 API가 정한 계약이지 GraphQL 표준 enum이 아니다. gRPC 상태의 의미는 공식 상태 코드 설명을 기준으로 고르고, 구체적인 업무 사유는 별도 필드로 보낸다.

Unavailable이나 deadline 오류라고 쓰기 요청을 무조건 재시도하지는 않는다. 이미 처리됐지만 응답만 유실됐을 수 있다. 재시도 가능 여부는 상태 코드와 업무 멱등성을 함께 봐야 한다.

상세 오류는 구조화한다

gRPC에서는 google.rpc.BadRequest로 필드별 입력 오류, ErrorInfo로 안정적인 reason과 domain을 표현할 수 있다. rich error model의 지원 범위는 사용 언어와 클라이언트에 따라 확인한다. gRPC 상세 오류 모델

status: FAILED_PRECONDITION
ErrorInfo:
  domain: inventory.example.com
  reason: INSUFFICIENT_STOCK
  metadata:
    item_id: sample-item-1

metadata는 허용 목록으로 구성한다. 내부 SQL, 스택, 접근 토큰, 다른 tenant의 자원 정보가 들어가지 않게 한다. 상세 정보가 너무 크면 전송 제한에 걸릴 수 있으므로 필드 오류 수와 문자열 길이도 제한한다.

GraphQL 경계에서 한 번 변환한다

resolver마다 문자열을 조립하기보다 공통 오류 변환기를 둔다. gRPC status를 읽고 알려진 상세 정보만 GraphQL extensions로 옮긴다.

json
{
  "data": { "receiveItems": null },
  "errors": [{
    "message": "처리 가능한 수량이 부족합니다.",
    "path": ["receiveItems"],
    "extensions": {
      "code": "PRECONDITION_FAILED",
      "reason": "INSUFFICIENT_STOCK",
      "requestId": "sample-request-1"
    }
  }]
}

예제는 receiveItems가 nullable인 경우다. non-null 오류가 루트까지 전파되면 data 전체가 null이 된다. 실행 전 검증 실패 응답에는 data를 넣지 않는다.

GraphQL의 오류 응답에는 message, 필요에 따른 path, 확장용 extensions 등이 사용된다. GraphQL 오류 형식을 유지하고, framework가 만든 필드 경로를 임의로 잃어버리지 않도록 한다.

부분 데이터와 오류가 함께 반환될 수 있으므로 HTTP 상태만 보고 업무 성공을 판단하지 않는다. non-null 필드의 실패 전파도 응답 스키마와 함께 테스트한다.

알 수 없는 오류와 클라이언트 분기

모르는 도메인 코드나 상세 타입은 내부 오류 또는 보수적인 공통 오류로 처리한다. 원문 메시지를 그대로 사용자에게 전달하지 않고 요청 ID로 서버 진단 정보와 연결한다.

클라이언트는 우선 code, 필요한 화면에서만 reason으로 분기한다. 새 reason이 추가돼도 기본 메시지를 보여 줄 수 있어야 한다. 모든 reason을 강제 enum으로 닫아 두면 서버 확장이 구버전 클라이언트를 깨뜨릴 수 있다.

검증할 조합

다음은 미실행 테스트 항목이다. 매핑 함수 단위 테스트와 서버·클라이언트 간 전송 테스트로 나눠 확인한다.

  • 감싼 도메인 오류도 원래 분류를 유지한다.
  • 상세 정보 없는 gRPC 오류도 일관된 GraphQL code로 변환된다.
  • 모르는 상세 타입이 들어와도 파싱 전체가 실패하지 않는다.
  • 오류 메시지에 내부 SQL이나 토큰이 포함되지 않는다.
  • 부분 성공 응답의 data와 errors, non-null 전파가 예상과 일치한다.
공유하기 X LinkedIn

관련 글