gRPC Reference

gRPC Reference 소개

gRPC 레퍼런스는 Protocol Buffers(proto3)와 Go gRPC 라이브러리를 사용하여 gRPC 서비스를 구축하기 위한 종합적이고 검색 가능한 가이드입니다. 여섯 가지 주요 영역을 다룹니다: Proto정의(syntax 선언, 메시지 타입, enum, oneof, map 필드), 서비스(service/rpc 정의, protoc 컴파일 명령어, grpc.NewServer()를 이용한 Go 서버 설정, grpc.Dial()을 이용한 클라이언트 연결), 메시지(google.protobuf.Timestamp를 포함한 필드 타입, repeated 필드, 중첩 메시지, google.protobuf.Any), 스트리밍(서버 스트리밍, 클라이언트 스트리밍, 양방향 스트리밍, stream.Send()/Recv() 연산), 인터셉터(UnaryServerInterceptor, StreamServerInterceptor, 인증 헤더를 위한 메타데이터 처리), 에러처리(status.Error(), 전체 gRPC 상태 코드 표, status.FromError(), 구조화된 에러를 위한 errdetails, deadline/timeout 패턴).

Go로 마이크로서비스를 구축하는 백엔드 엔지니어, 내부 RPC API를 설계하는 플랫폼 엔지니어, REST에서 gRPC로 마이그레이션하는 개발자가 주요 대상입니다. 레퍼런스는 Go 생태계를 기반으로 합니다: 모든 서버와 클라이언트 코드 예제는 google.golang.org/grpc 패키지, protoc-gen-go 및 protoc-gen-go-grpc 플러그인, context 기반 deadline, 로컬 개발을 위한 grpc.WithTransportCredentials(insecure.NewCredentials()) 같은 표준 패턴을 사용합니다. 로깅 및 인증을 위한 인터셉터 체인 같은 프로덕션 수준 패턴도 완전한 함수 시그니처와 함께 설명됩니다.

이 레퍼런스의 핵심 차별점은 네 가지 gRPC 통신 패턴을 한 곳에서 모두 다룬다는 점입니다: 단항 RPC(요청-응답), 서버 스트리밍(단일 요청, 스트림 응답), 클라이언트 스트리밍(스트림 요청, 단일 응답), 양방향 스트리밍(동시 요청/응답 스트림). 에러 처리 섹션에서는 숫자 값을 포함한 전체 gRPC 상태 코드(codes.OK부터 codes.Unauthenticated까지)와 에러 응답에 구조화된 필드 위반 정보를 첨부하기 위한 고급 errdetails 패키지도 다룹니다.

주요 기능

• Proto3 문법: package 및 go_package 옵션을 포함한 syntax 선언, 필드 번호를 포함한 message 타입 정의, UNSPECIFIED 0값을 가진 enum, 상호 배타적 필드를 위한 oneof, map<key, value> 필드 타입
• .proto SDL에서의 서비스 및 RPC 정의: 단항, 서버 스트리밍, 클라이언트 스트리밍, 양방향 스트리밍 RPC 시그니처
• --go_out 및 --go-grpc_out 플래그, paths=source_relative 옵션을 포함한 protoc 컴파일 명령어
• Go 서버 설정: net.Listen(), grpc.NewServer(), pb.RegisterXxxServer(), s.Serve(lis) — 완전한 서버 부트스트랩 패턴
• Go 클라이언트 설정: 로컬 개발을 위한 insecure.NewCredentials()를 사용한 grpc.Dial(), 생성된 스텁에서 pb.NewXxxClient()
• Go 구현과 함께 제공되는 네 가지 스트리밍 패턴: stream.Send(), stream.Recv(), 클라이언트 스트리밍을 위한 io.EOF 감지, 동시 양방향 Chat 예제
• 인터셉터 패턴: 로깅/인증 미들웨어를 위한 (ctx, req, info, handler) 시그니처를 가진 UnaryServerInterceptor, StreamServerInterceptor, 헤더 추출을 위한 metadata.FromIncomingContext()
• 숫자 코드를 포함한 완전한 gRPC 상태 코드 레퍼런스(OK, Cancelled, InvalidArgument, NotFound, AlreadyExists, PermissionDenied, Unauthenticated, Internal)와 필드 수준 유효성 검사 에러를 위한 errdetails.BadRequest

자주 묻는 질문