gRPC 통신의 상태 코드와 에러 핸들링

궁금하면 500원·2024년 7월 6일

API통신 grpc protobuf 마이크로서비스 백엔드개발 상태코드 서버통신 에러핸들링

MSA&아키텍처

목록 보기

11/42

gRPC 상태 코드 및 에러 핸들링

1. gRPC 상태 코드란?

gRPC 상태 코드는 클라이언트와 서버 간의 통신 결과를 나타내는 코드로, 요청의 성공 여부 및 다양한 오류 상황을 명확하게 전달하기 위해 사용됩니다.
이는 HTTP 상태 코드와 유사하지만, gRPC는 보다 구체적인 오류를 표현할 수 있도록 설계되었습니다.

대표적인 gRPC 상태 코드

OK: 요청이 성공적으로 처리됨
CANCELLED: 요청이 취소되었거나 클라이언트 측에서 중단됨
UNKNOWN: 예상치 못한 오류 발생
INVALID_ARGUMENT: 잘못된 인수가 포함됨
DEADLINE_EXCEEDED: 요청 시간이 초과됨
NOT_FOUND: 리소스를 찾을 수 없음
ALREADY_EXISTS: 리소스가 이미 존재함
PERMISSION_DENIED: 권한 부족으로 요청이 거부됨
RESOURCE_EXHAUSTED: 리소스 할당량 초과
FAILED_PRECONDITION: 현재 시스템 상태에서 요청이 처리될 수 없음
ABORTED: 동시성 충돌로 인해 요청이 중단됨
OUT_OF_RANGE: 요청 값이 허용된 범위를 벗어남
UNIMPLEMENTED: 요청된 메서드가 서버에서 구현되지 않음
INTERNAL: 서버 내부 오류 발생
UNAVAILABLE: 서버가 일시적으로 요청을 처리할 수 없음
DATA_LOSS: 데이터 손실 발생
UNAUTHENTICATED: 인증되지 않은 요청

2. gRPC 상태 코드 vs HTTP 상태 코드

차이점

항목	gRPC 상태 코드	HTTP 상태 코드
기반 프로토콜	HTTP/2	HTTP 1.1 및 2
코드 개수	17개 (카테고리화됨)	5개 범주 (1xx~5xx)
오류 설명	보다 상세한 오류 메시지 포함 가능	범용적인 상태 코드 사용
확장성	Protobuf 기반 확장 가능	새로운 상태 코드 추가 어려움

3. gRPC Metadata란?

gRPC Metadata는 클라이언트와 서버 간의 통신에서 메시지와는 별도로 전달되는 부가 정보입니다. 이는 HTTP/2 헤더 프레임을 기반으로 하며, 요청 및 응답 시 다양한 추가 정보를 제공할 수 있습니다.

Header Metadata

요청을 보낼 때 포함되는 메타데이터
인증 토큰, 요청 언어, 클라이언트 정보 등을 포함

예제

:method: POST
:scheme: http
:path: /greet.Greeter/SayHello
:authority: localhost:50051
content-type: application/grpc
user-agent: grpc-go/1.43.0
te: trailers
grpc-timeout: 9933133n

Trailer Metadata

응답 메시지의 끝에 추가되는 메타데이터
주로 상태 코드와 에러 메시지 포함

예제

:status: 200
content-type: application/grpc
grpc-status: 0
grpc-message: ""

4. gRPC 에러 처리 및 핸들링

4.1 서버에서의 에러 핸들링

서버는 StatusRuntimeException을 활용하여 클라이언트에 적절한 상태 코드와 메시지를 전달할 수 있습니다.

import io.grpc.Status;
import io.grpc.stub.StreamObserver;

public void someRpcMethod(Request request, StreamObserver<Response> responseObserver) {
    if (!hasPermission(request)) {
        StatusRuntimeException exception = Status.PERMISSION_DENIED
            .withDescription("Access to this resource is denied.")
            .asRuntimeException();
        responseObserver.onError(exception);
        return;
    }
    // 정상적인 처리 로직
}

4.2 클라이언트에서의 에러 핸들링

클라이언트는 Status 클래스를 이용하여 응답 상태를 확인하고 적절한 처리를 수행해야 합니다.

import io.grpc.StatusRuntimeException;

try {
    Response response = blockingStub.someRpcMethod(request);
} catch (StatusRuntimeException e) {
    if (e.getStatus().getCode() == Status.Code.PERMISSION_DENIED) {
        System.out.println("접근 권한이 없습니다.");
    }
}

5. gRPC 스트리밍에서의 예외 처리

스트리밍 RPC의 경우, 서버에서 onError()를 호출하여 클라이언트에 에러를 전송할 수 있습니다.

import io.grpc.StatusRuntimeException;

try {
    Response response = blockingStub.someRpcMethod(request);
} catch (StatusRuntimeException e) {
    if (e.getStatus().getCode() == Status.Code.PERMISSION_DENIED) {
        System.out.println("접근 권한이 없습니다.");
    }
}