- Knowledge
gRPC는 서로 다른 서비스를 어떻게 연결할까?
서비스 계약과 Protocol Buffers를 바탕으로 gRPC 호출과 스트리밍, 오류 처리 방식을 살펴봅니다.
시리즈15편 중 10편백엔드 통신의 흐름3부 · 서비스에 맞는 통신 방식 선택하기
1부 · 서버와 클라이언트는 어떻게 대화할까?3편
2부 · HTTP 요청 아래에서는 무슨 일이 일어날까?6편
3부 · 서비스에 맞는 통신 방식 선택하기3편
4부 · 서버는 수많은 연결을 어떻게 감당할까?3편
주문 서비스가 배송 서비스에 배송 상태를 물어본다고 해볼게요. 지금은 두 서버 모두 JavaScript로 작성돼 있어서 HTTP API에 JSON을 주고받고 있습니다. 그런데 배송 서비스를 Go로 바꾸고, 요청 한 번에 배송 경로의 변화를 계속 전달하는 기능까지 추가한다면 어떨까요?
REST 방식의 HTTP API를 계속 사용할 수도 있습니다. 다만 호출할 경로와 JSON 구조, 클라이언트 타입, 스트리밍 처리를 서비스마다 직접 맞춰야 하겠죠. 이때 고려할 수 있는 선택지가 gRPC입니다. gRPC는 서비스가 제공하는 메서드와 메시지 형태를 정의하고, 그 정의를 이용해 여러 언어에서 클라이언트·서버 코드를 만들 수 있는 RPC 프레임워크예요.
REST는 API를 설계하는 아키텍처 스타일이고, gRPC는 RPC 호출 모델과 구현 규약을 제공하는 프레임워크입니다. 따라서 둘을 단순히 속도로만 비교하기는 어렵습니다. 어느 쪽이 좋은지는 메시지 크기보다 기존 API 사용 방식, 팀의 개발 환경, 오류 처리와 운영 도구까지 함께 봐야 해요.
호출할 메서드부터 합의한다
일반적인 JSON API에서는 서버가 GET /shipments/S-42를 제공하고, 클라이언트가 그 주소에 맞춰 요청을 보냅니다. OpenAPI 같은 별도 계약을 작성할 수도 있지만, 계약 없이 코드를 구현하는 경우도 있죠.
gRPC에서는 보통 Protocol Buffers의 .proto 파일로 서비스와 메시지 타입을 먼저 정의합니다. 예를 들어 배송 조회를 아래처럼 표현할 수 있어요.
shipping.proto
syntax = "proto3";
package shipping;
service ShippingService {
rpc GetShipment(GetShipmentRequest) returns (Shipment);
rpc WatchShipment(GetShipmentRequest) returns (stream ShipmentEvent);
}
message GetShipmentRequest {
string shipment_id = 1;
}
message Shipment {
string shipment_id = 1;
string status = 2;
}
message ShipmentEvent {
string shipment_id = 1;
string status = 2;
int64 changed_at_unix_ms = 3;
}GetShipment는 요청 메시지를 하나 받아 응답 메시지를 하나 돌려줍니다. 이런 호출을 Unary RPC라고 해요. WatchShipment는 요청을 하나 받은 뒤 배송 상태가 바뀔 때마다 여러 응답 메시지를 보낼 수 있습니다. 이쪽은 Server Streaming RPC입니다.
이 파일로 각 언어에 맞는 코드를 생성하거나 런타임에 서비스 정의를 로드할 수 있습니다. 클라이언트는 직접 HTTP 경로를 문자열로 조합하는 대신 GetShipment 같은 메서드를 호출해요. 호출이 로컬 함수처럼 보일 수 있지만 실제로는 네트워크 요청입니다. 따라서 지연, 연결 실패, 중복 실행 가능성까지 로컬 함수와 같다고 가정할 수는 없어요.
Protocol Buffers는 무엇을 줄여 줄까?
.proto 파일에 적은 shipment_id = 1에서 1은 배열의 첫 번째 칸이 아닙니다. 메시지를 직렬화할 때 필드를 식별하는 번호예요. 전송 중에는 보통 JSON의 "shipment_id"처럼 필드 이름을 매번 적지 않아도 됩니다.
예를 들어 다음과 같은 개념적 데이터가 있다고 해볼게요.
{"shipment_id":"S-42","status":"IN_TRANSIT"}Protocol Buffers는 이를 필드 번호와 타입 정보를 사용하는 바이너리 형식으로 인코딩합니다. JSON보다 작게 표현할 수 있는 경우가 많지만, 모든 입력에서 반드시 더 작거나 빠른 것은 아닙니다. 메시지가 아주 작거나 압축을 사용하는 경우, 문자열 위주의 데이터인 경우에는 비교 결과가 달라질 수 있어요.
스키마를 바꿀 때도 규칙이 있습니다. 출시된 메시지의 필드 번호를 다른 의미로 재사용하면 구버전 클라이언트가 새 데이터를 잘못 해석할 수 있어요. 필드를 없앤다면 번호를 reserved로 남기고, 새 필드를 추가할 때에는 기존 번호의 의미를 유지하는 편이 안전합니다.
앞의 실행 예제와 별도로, v1에 3번 필드가 있었다가 v2에서 삭제되는 상황을 살펴볼게요.
// v1
message Shipment {
string shipment_id = 1;
string status = 2;
string legacy_code = 3;
}v2에서는 사용을 중단한 3번 필드를 지우고 번호를 예약합니다.
// v2
message Shipment {
string shipment_id = 1;
string status = 2;
reserved 3;
optional string carrier_name = 4;
}v2에서 reserved 3은 위 v1의 legacy_code를 삭제하면서 해당 번호를 재사용하지 못하도록 예약한 것입니다. 이는 앞의 실행 예제와는 별도의 버전 변경 예시예요. optional은 필드가 아예 전달되지 않은 상태와 기본값이 명시된 상태를 구별해야 할 때 도움이 됩니다.
gRPC는 HTTP/2 위에서 어떻게 메시지를 전달할까?
일반적인 gRPC 전송은 HTTP/2를 사용합니다. 하나의 RPC는 HTTP/2 스트림 하나에 대응하고, 스트림 안에서 gRPC 메시지를 주고받아요. 메시지는 길이 정보를 가진 프레이밍으로 구분되므로 하나의 스트림으로 응답 메시지 여러 개를 전달할 수 있습니다.
배송 상태 변경을 두 번 전송했다면 개념적으로 다음과 같은 흐름입니다.
클라이언트 → 서버: GetShipmentRequest { shipment_id: "S-42" }
서버 → 클라이언트: ShipmentEvent { status: "PICKED_UP" }
서버 → 클라이언트: ShipmentEvent { status: "IN_TRANSIT" }
서버 → 클라이언트: 스트림 종료 + gRPC 상태HTTP/2의 멀티플렉싱 덕분에 연결 하나에서 서로 다른 RPC 스트림을 동시에 처리할 수 있습니다. 하지만 이 성질이 서버의 비즈니스 로직까지 병렬로 실행해 준다는 뜻은 아니에요. 서버가 한 스레드에서 오랜 계산을 수행하면 다른 요청도 지연될 수 있습니다.
또 하나 알아둘 부분은 오류입니다. HTTP 상태 코드가 200이더라도 gRPC 호출 결과는 실패일 수 있어요. gRPC는 자신의 상태 코드를 사용하고, 정상적인 gRPC 응답에서는 이 값을 HTTP/2 트레일러의 grpc-status 등으로 전달합니다. 그래서 중간 프록시의 HTTP 접근 로그만 보고 RPC가 성공했다고 판단하면 문제를 놓칠 수 있습니다.
같은 배송 서비스를 Node.js에서 호출해 보기
아래 예제는 Node.js 22 이상과 @grpc/grpc-js, @grpc/proto-loader를 설치한다는 전제의 실행용 예제예요. 실제 배송 시스템을 만들지는 않고 고정된 상태 메시지를 반환합니다. 서버와 클라이언트를 같은 컴퓨터에서 실행하도록 단순화했으며, TLS 없이 로컬 루프백 주소만 사용합니다.
npm init -y
npm install @grpc/grpc-js @grpc/proto-loaderserver.cjs
const grpc = require('@grpc/grpc-js');
const loader = require('@grpc/proto-loader');
const path = require('node:path');
const definition = loader.loadSync(path.join(__dirname, 'shipping.proto'));
const shipping = grpc.loadPackageDefinition(definition).shipping;
const server = new grpc.Server();
server.addService(shipping.ShippingService.service, {
getShipment(call, callback) {
callback(null, {
shipmentId: call.request.shipmentId,
status: 'IN_TRANSIT'
});
},
watchShipment(call) {
const statuses = ['PICKED_UP', 'IN_TRANSIT', 'DELIVERED'];
let index = 0;
const timer = setInterval(() => {
if (call.cancelled) { clearInterval(timer); return; }
call.write({
shipmentId: call.request.shipmentId,
status: statuses[index],
changedAtUnixMs: String(Date.now())
});
index += 1;
if (index === statuses.length) {
clearInterval(timer);
call.end();
}
}, 300);
call.on('cancelled', () => clearInterval(timer));
}
});
server.bindAsync('127.0.0.1:50051',
grpc.ServerCredentials.createInsecure(), (error) => {
if (error) throw error;
console.log('gRPC server: 127.0.0.1:50051');
});client.cjs
const grpc = require('@grpc/grpc-js');
const loader = require('@grpc/proto-loader');
const path = require('node:path');
const definition = loader.loadSync(path.join(__dirname, 'shipping.proto'));
const shipping = grpc.loadPackageDefinition(definition).shipping;
const client = new shipping.ShippingService(
'127.0.0.1:50051', grpc.credentials.createInsecure()
);
client.getShipment({ shipmentId: 'S-42' }, (error, result) => {
if (error) console.error(error);
else console.log('조회:', result.status);
});
const stream = client.watchShipment({ shipmentId: 'S-42' });
stream.on('data', (event) => console.log('변경:', event.status));
stream.on('error', (error) => console.error('스트림 오류:', error));
stream.on('end', () => client.close());node server.cjs를 먼저 실행하고 다른 터미널에서 node client.cjs를 실행하면 조회 응답 한 번과 배송 상태 이벤트 세 개를 받도록 구성했습니다. Node.js 로컬 환경에서 실행해 조회 응답과 세 개의 상태 이벤트를 확인했습니다.
주의할 점이 하나 있어요. @grpc/proto-loader가 필드 이름을 JavaScript의 camelCase 형태로 읽는 기본 설정을 사용했으므로 shipment_id는 코드에서 shipmentId로 접근합니다. 이를 바꾸는 옵션도 있습니다.
네 가지 RPC 유형과 그 비용
gRPC는 Unary, Server Streaming 외에 Client Streaming과 Bidirectional Streaming도 지원합니다. 전자는 클라이언트가 여러 메시지를 보내고 서버가 결과 하나를 돌려주는 방식이에요. 후자는 같은 RPC 안에서 양쪽이 독립적으로 메시지를 계속 주고받습니다.
파일 업로드를 Client Streaming으로 구현한다면 파일 청크를 연속해서 보내고 마지막에 결과를 받을 수 있어요. 양방향 스트리밍에서는 클라이언트가 입력을 보내는 동안 서버가 중간 결과를 전달할 수도 있습니다. 다만 스트리밍이 지원된다고 해서 무한정 빠르게 write()를 호출해도 되는 건 아니에요. 수신자가 처리하는 속도보다 송신 속도가 빠르면 버퍼와 HTTP/2 흐름 제어, 클라이언트 라이브러리의 백프레셔 처리에 신경 써야 합니다.
요청이 실패했을 때는 누가 작업을 멈출까?
네트워크 RPC를 로컬 함수처럼 취급하면 가장 자주 놓치는 부분이 데드라인(deadline)입니다. 클라이언트가 500ms 안에 응답을 받아야 하는데 서버 작업이 몇 초씩 이어지면, 클라이언트는 기다리기를 포기할 수 있습니다.
하지만 데드라인 만료나 클라이언트의 취소가 이미 시작한 서버의 데이터베이스 변경을 자동으로 되돌리는 것은 아닙니다. 서버 코드는 취소 신호를 확인하고 중단 가능한 작업을 멈춰야 합니다. 다른 서비스로 이어지는 호출에도 남은 시간을 전달하거나 적절한 데드라인을 두어야 해요.
재시도 역시 마찬가지예요. 배송 조회는 보통 재시도하기 쉽지만, 배송 접수를 생성하는 호출을 무작정 재시도하면 작업이 두 번 수행될 수 있습니다. 어떤 요청을 재시도할 수 있는지는 비즈니스 로직의 멱등성과 연결됩니다.
브라우저에서 직접 gRPC 서버를 호출할 때에도 제약이 있습니다. 브라우저에서는 일반적인 gRPC HTTP/2 동작을 자유롭게 다룰 수 없기 때문에 보통 gRPC-Web과 이를 처리하는 프록시 또는 호환 서버를 사용합니다. gRPC-Web은 일반적인 gRPC와 기능 지원 범위가 같지 않으며, 특히 클라이언트·양방향 스트리밍은 별도로 확인해야 합니다.
그래서 외부 공개 API나 캐시가 중요한 웹 서비스에서는 JSON/HTTP API가 더 간편할 수 있어요. 반면 여러 언어로 작성된 내부 서비스가 명확한 인터페이스와 스트리밍 호출을 공유해야 한다면 gRPC가 유용합니다.
처음의 배송 서비스로 돌아가면, gRPC를 선택할 이유는 GET /shipments/S-42보다 무조건 빨라서가 아닙니다. 서로 다른 서비스가 같은 메시지 계약으로 통신하고, 한 번의 RPC 안에서 여러 메시지를 주고받을 필요가 있을 때 gRPC의 설계가 잘 맞습니다.
갑자기 추워진 날, 진주에서
진주에서 하루종일 돌아다녔다

내 단점을 커버하는 동료와 함께.
새로운 프로젝트를 함께 준비하는 친구와의 저녁. 미운 점도 고마운 점도 있지만, 결국 같이 잘됐으면 좋겠다는 마음.

순천과 여수 여행3
마지막 하루. 공부랑 런닝으로 끝내기


댓글 0
이 글에 대한 생각을 자유롭게 남겨주세요.
댓글을 불러오는 중…