12 KiB
gRPC 튜토리얼 원고 (Manuscript)
본 문서는 grpccanary 프로젝트의 개념적 학습 자료를 모아둔 문서입니다. JSON 데이터 포맷의 이해부터 HTTP, 그리고 마이크로서비스 환경에서 gRPC가 왜 필요한지에 대한 상세한 배경을 설명합니다.
1. JSON이란?
JSON(JavaScript Object Notation)은 데이터를 구조화하여 전송하기 위해 널리 사용되는 가볍고 읽기 쉬운 텍스트 기반의 데이터 포맷입니다. 대부분의 현대 프로그래밍 언어에서 기본적으로 지원하며, 특히 HTTP 기반 REST API의 데이터 교환 규격으로 오랫동안 사랑받아 왔습니다.
2. HTTP란?
HTTP(Hypertext Transfer Protocol)는 웹 브라우저와 웹 서버 간에 데이터를 주고받기 위한 통신 프로토콜입니다.
gin-gonic을 이용한 http 서버 구현하기
Go 언어에서는 전통적인 net/http 표준 라이브러리 외에도, 성능이 뛰어나고 라우팅 기능이 강력한 gin-gonic/gin 프레임워크를 널리 활용하여 RESTful 웹 API 서버를 구축합니다.
3. gRPC란?
Go 언어에서 gRPC를 어떻게 활용하는지 전반적으로 살펴보겠습니다.
gRPC가 필요한 이유: 어느 개발팀의 이야기
어느 날, 성장하는 스타트업의 백엔드 개발자 민우는 골치 아픈 버그를 마주했습니다. 서비스가 마이크로서비스 아키텍처(MSA)로 전환되면서, 회원 서비스(Go)와 주문 서비스(Python)가 서로 HTTP/JSON API로 통신하기 시작했는데, 최근 회원 서비스의 응답 필드 이름이 user_id에서 userId로 변경되면서 주문 서비스가 마비된 것입니다.
"사전 공유가 누락되었네요. 죄송합니다..." 회원 담당 팀원의 사과로 버그는 금방 고쳐졌지만, 민우는 근본적인 질문을 던지게 되었습니다. '왜 서비스 간의 통신 규칙(계약)을 코드 레벨에서 강제할 수 없을까?'
REST와 JSON은 단순하고 사람이 읽기 쉽다는 훌륭한 장점이 있어 인터넷망을 통한 클라이언트-서버 통신에 널리 쓰입니다. 하지만 대규모 마이크로서비스 환경에서 시스템 내부의 서비스 간 통신(Internal RPC)용으로는 다음과 같은 한계를 드러내곤 합니다:
- 느슨한 계약(Loose Contract): API 스펙 문서가 최신화되지 않으면 언제든 타입 오류나 필드 누락으로 인한 런타임 에러가 발생할 수 있습니다.
- 비효율적인 직렬화: 텍스트 기반의 JSON 데이터는 컴퓨터가 처리하기에 너무 무겁고, 네트워크 대역폭도 많이 차지합니다.
- 반복되는 클라이언트 코드 작성: 파트너 서비스가 고유한 API를 제공할 때마다, 이를 호출하기 위한 HTTP 클라이언트 패키지 코드를 다국어별로 매번 새로 작성해야 합니다.
이러한 문제들을 해결하기 위해 구글은 gRPC를 개발했습니다. gRPC는 다음과 같은 차별점을 통해 민우가 겪었던 어려움을 해결해 줍니다:
- 프로토콜 버퍼(Protobuf) 기반의 강력한 스키마 계약:
.proto파일 하나로 서비스 통신 규약을 선언하고, 이를 컴파일하여 여러 프로그래밍 언어의 구체적인 클라이언트/서버 코드를 자동으로 생성합니다. 즉, 컴파일 단계에서 스키마 계약 불일치 오류를 차단합니다. - 바이너리 프로토콜: 텍스트가 아닌 이진 데이터 형식을 사용하여 통신 속도가 JSON 방식에 비해 훨씬 빠르고 가볍습니다.
- HTTP/2 기반: 하나의 커넥션을 다중화(Multiplexing)하여 사용하므로 네트워크 리소스 효율성이 매우 높습니다.
4. gRPC 개요
위와 같이 gRPC가 고안된 배경과 필요성을 바탕으로, 구체적인 특징과 개발 프로세스를 살펴보겠습니다.
gRPC 서버와 클라이언트를 개발하는 과정은 크게 세 단계로 나뉩니다:
- 인터페이스 정의 언어(IDL) 파일 생성: 인터페이스를 계약(Contract)으로 정의합니다.
- gRPC 서버 개발: 이 정의를 기반으로 서비스를 구현합니다.
- gRPC 클라이언트 개발: 해당 서버와 통신하는 코드를 개발합니다.
4.1 장점
gRPC의 주요 장점은 다음과 같습니다:
- 빠른 데이터 교환: 바이너리 데이터 형식을 사용하여 일반 텍스트 기반 서비스보다 훨씬 빠르게 데이터를 교환합니다.
- 간편한 개발 도구: 풍부한 명령줄 도구들을 제공하여 개발 작업을 더욱 간단하고 신속하게 만듭니다.
- 쉬운 서버/클라이언트 생성: gRPC 서비스의 함수와 메시지를 정의한 후에는 RESTful 서비스보다 서버와 클라이언트를 더 쉽게 생성할 수 있습니다.
- 스트리밍 지원: 스트리밍 서비스에 효과적으로 활용될 수 있습니다.
- 세부 사항 자동 처리: 데이터 교환의 복잡한 세부 사항을 gRPC가 자동으로 처리해주므로 개발자가 신경 쓸 필요가 없습니다.
Note
이 장점 목록만 보고 gRPC가 모든 문제의 완벽한 해결책이라고 오해해서는 안 됩니다. 항상 현재 작업에 가장 적합한 도구나 기술을 선택하는 것이 중요합니다.
4.2 프로토콜 버퍼 (Protobuf)
프로토콜 버퍼(Protobuf)는 구조화된 데이터를 효율적으로 직렬화하는 방법입니다. IDL(인터페이스 정의 언어) 역할을 하는 .proto 파일을 사용해 통신 규약을 명확히 정의합니다.
Protobuf의 주요 장단점
-
장점
- 높은 전송 효율성: 데이터 교환 시 텍스트 기반이 아닌 바이너리 형식을 사용하므로 JSON에 비해 데이터 크기가 매우 작고 직렬화/역직렬화 속도가 빠릅니다.
- 강력한 스키마 계약: 하나의 정의 파일(
.proto)로부터 다국어 클라이언트/서버 코드를 자동 생성(Stub 코드)하므로 컴파일 단계에서 타입 불일치 에러를 방지할 수 있습니다. - 하위 호환성 유지: 필드 번호를 기반으로 직렬화하므로 데이터 스키마가 업데이트되더라도 기존 시스템과의 호환성을 유연하게 보존합니다.
-
단점
- 사람이 읽기 어려운 가독성 (Binary Format): 바이너리 형태로 데이터가 전송되므로, JSON처럼 네트워크 패킷을 사람이 직접 눈으로 확인하거나 텍스트 편집기로 디버깅하기 어렵습니다.
- 빌드 복잡성: 스펙이 바뀔 때마다
protoc컴파일러와 관련 플러그인을 활용하여 코드를 재생성(Stub 컴파일)해야 하는 추가적인 개발 파이프라인 단계가 필요합니다.
5. 실습: gRPC 기반 서비스 구현 및 컴파일
이 저장소에 기동되어 실행되는 gRPC 예제(Random 서비스)의 구체적인 IDL 명세와 컴파일, 그리고 구현 코드를 상세히 분석합니다.
5.1 인터페이스 정의 언어(IDL) protoapi.proto 분석
우리가 개발할 gRPC 서비스는 다음 기능을 제공합니다:
- 서버는 클라이언트에게 현재 날짜와 시간을 반환해야 합니다.
- 서버는 클라이언트에게 주어진 길이의 무작위 비밀번호를 반환해야 합니다.
- 서버는 클라이언트에게 무작위 정수를 반환해야 합니다.
이 통신 규약은 루트 디렉토리의 protoapi.proto 파일에 다음과 같이 기술되어 있습니다.
syntax = "proto3";
option go_package = "./protoapi/;protoapi";
service Random {
rpc GetDate (RequestDateTime) returns (DateTime);
rpc GetRandom (RandomParams) returns (RandomInt);
rpc GetRandomPass (RequestPass) returns (RandomPass);
}
message RandomParams {
int64 Seed = 1;
int64 Place = 2;
}
message RandomInt {
int64 Value = 1;
}
message DateTime {
string Value = 1;
}
message RequestDateTime {
string Value = 2;
}
message RequestPass {
int64 Seed = 1;
int64 Length = 8;
}
message RandomPass {
string Password = 1;
}
syntax = "proto3": 프로토콜 버퍼 언어의 proto3 버전을 활용합니다. 명시하지 않으면 구버전인 proto2로 인식되므로 파일 최상단에 반드시 기술해야 합니다.option go_package: 컴파일 시 Go 코드로 출력될 패키지의 이름을protoapi로 지정하며, 출력 디렉토리를./protoapi/로 명시합니다.service Random: 서버와 클라이언트가 사용할 3가지 RPC 메서드명(GetDate,GetRandom,GetRandomPass)과 해당 메서드들이 수용/반환할 메시지 포맷을 상호 정의합니다.message필드 및 태그: 각 메시지 필드마다 데이터 타입(예:int64,string)과 바이너리 인코딩 시 키값 역할을 하는 고유 태그 번호(예:= 1,= 2)를 부여합니다.
5.2 Go에서 IDL 파일 컴파일 및 Stub 생성
.proto 정의를 실제 Go 소스 코드로 컴파일하려면 프로토콜 버퍼 컴파일러(protoc)와 Go용 플러그인(protoc-gen-go, protoc-gen-go-grpc)이 로컬 시스템에 설치되어 있어야 합니다.
도구 설치 방법
- macOS (Homebrew):
brew install protobuf go install google.golang.org/protobuf/cmd/protoc-gen-go@latest go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest - Linux (Ubuntu/Debian):
sudo apt install -y protobuf-compiler go install google.golang.org/protobuf/cmd/protoc-gen-go@latest go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
컴파일 실행 명령어
설치 완료 후 리포지토리 루트에서 다음 컴파일 명령어를 수행합니다:
protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. \
--go-grpc_opt=paths=source_relative protoapi.proto
- 이 실행을 통해
protoapi/디렉토리 밑에 메시지 포맷 정의가 담긴protoapi.pb.go와 gRPC 클라이언트/서버 인터페이스 및 메서드 껍데기가 들어있는protoapi_grpc.pb.go파일이 자동 생성됩니다.
5.3 gRPC 서버 구현 (server.go)
IDL을 통해 생성된 Go 패키지(protoapi)를 가져와 실제 비즈니스 로직을 수행할 gRPC 서버를 구현합니다.
- 구조체 정의:
RandomServer구조체 타입을 선언하고protoapi.UnimplementedRandomServer를 임베딩하여 gRPC 인터페이스 호환을 확보합니다. - 비즈니스 메서드 구현:
GetDate: 현재 시간 문자열을 반환합니다.GetRandom: 시드값을 기반으로 지정된 위치에 있는 의사 난수를 반환합니다.GetRandomPass: 요청된 시드와 길이 매개변수를 활용해 무작위 비밀번호 문자열을 조립해 반환합니다.
- 서버 기동 (
ServerRun):grpc.NewServer()로 서버 인스턴스를 확보하고 서비스를 등록합니다.- 외부 디버깅 도구(예:
grpcurl등)가 인터페이스 사양을 동적으로 검색할 수 있도록reflection.Register(server)를 호출해 리플렉션을 활성화합니다. net.Listen("tcp", port)를 통해 네트워크 채널을 열고 대기 상태(server.Serve)를 개시합니다.
5.4 gRPC 클라이언트 구현 (client.go)
서버에 원격 호출을 요청하고 응답 데이터를 가공해 출력하는 클라이언트 흐름입니다.
- 채널 접속:
grpc.Dial함수를 통해 주소로의 연결 통로를 엽니다. 로컬 테스트 및 통신 단순화를 위해 평문(TLS 미적용) 커넥션(insecure.NewCredentials())을 수립합니다. - 클라이언트 인스턴스 생성:
protoapi.NewRandomClient(conn)를 통해 원격 서비스 호출 인터페이스 객체를 생성합니다. - 호출 래퍼:
AskingDateTime,AskPass,AskRandom등의 헬퍼 함수를 통해 실제 RPC 메서드에 요청 파라미터(시드, 길이 등)를 태워 호출합니다. - 콘솔 출력 (
ClientRun): 최종 수신한 시간, 생성된 무작위 비밀번호, 임의의 난수를 받아 콘솔 표준 출력에 정상 표시해 줍니다.