🔌
gRPC & Protobuf 치트시트

Protocol Buffers proto3 문법, 4가지 RPC 통신 패턴(Unary/Streaming), protoc 컴파일, Spring Boot/Go/Node.js 연동, 인터셉터, 에러 모델 및 grpcurl 디버깅 가이드
#grpc#protobuf#proto3#rpc#http2#microservices#spring-boot#golang#backend#api최종 업데이트: 2026-10-03
gRPC & Protobuf 치트시트 핵심 명령어 및 실전 가이드

Protocol Buffers proto3 문법, 4가지 RPC 통신 패턴(Unary/Streaming), protoc 컴파일, Spring Boot/Go/Node.js 연동, 인터셉터, 에러 모델 및 grpcurl 디버깅 가이드
## 1. gRPC vs REST 아키텍처 비교 & 핵심 특징
Google이 개발한 오픈소스 고성능 원격 프로시저 호출(RPC) 프레임워크로, 마이크로서비스 간 통신과 실시간 스트리밍에 최적화되어 있습니다.
```text
[gRPC vs REST API 핵심 비교]
• 프로토콜     : HTTP/2 전용 (바이너리 프레이밍, 멀티플렉싱, 양방향 스트리밍) vs HTTP/1.1 or 2
• 페이로드 포맷: Protocol Buffers (바이너리 직렬화, JSON 대비 3~10배 빠르고 용량 70% 절감) vs JSON / XML
• 계약 방식     : 엄격한 타입의 .proto 스키마 기반 IDL vs OpenAPI / Swagger (선택 사항)
• 통신 패턴     : Unary, Server Stream, Client Stream, Bi-directional Stream vs 단방향 Request-Response
• 브라우저 연동: gRPC-Web 및 Envoy 프록시 필요 vs 브라우저 네이티브 직접 지원 (fetch, XHR)
• 주 사용처     : MSA 내부 고속 통신, 대용량 실시간 IoT/스트리밍, 모바일 백엔드 vs 공개 Public API
```

## 2. Protocol Buffers v3 (`proto3`) 문법 완벽 가이드
스키마 파일(`.proto`)에 메시지 구조와 데이터 타입을 엄격하게 정의합니다.
```protobuf
syntax = "proto3"; // proto3 문법 명시 (필수)

package user.service.v1; // 패키지 네임스페이스

// ☕ 언어별 생성 옵션
option java_multiple_files = true;
option java_package = "com.lucky.grpc.user.v1";
option go_package = "github.com/lucky/service/user/v1;userv1";

// 📦 Google 내장 공용 타입 임포트
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";

// 👤 [1] 기본 메시지 정의
message User {
  // 필드 번호(1~15)는 1바이트로 인코딩되므로 자주 사용하는 핵심 필드에 할당
  int64 id = 1;
  string username = 2;
  string email = 3;
  bool is_active = 4;
  Role role = 5;

  // 📋 배열/리스트 (repeated)
  repeated string tags = 6;

  // 🗺️ Key-Value 맵 (map<KeyType, ValueType>)
  map<string, string> metadata = 7;

  // ⏰ 타임스탬프
  google.protobuf.Timestamp created_at = 8;

  // 🔀 oneof: 여러 필드 중 단 하나만 값 설정 가능 (메모리 절약)
  oneof auth_method {
    string password_hash = 9;
    string oauth_token = 10;
  }

  // 🚫 reserved: 삭제된 필드 번호나 이름을 재사용하지 못하도록 영구 고정 (하위 호환성)
  reserved 11, 12, 20 to 30;
  reserved "temp_token", "legacy_id";
}

// 🏷️ [2] 열거형(Enum) 정의
enum Role {
  // proto3의 Enum 0번 인덱스는 반드시 기본값(UNSPECIFIED)이어야 합니다.
  ROLE_UNSPECIFIED = 0;
  ROLE_USER = 1;
  ROLE_ADMIN = 2;
  ROLE_MANAGER = 3;
}
```

## 3. gRPC 서비스 정의 & 4가지 RPC 통신 패턴
하나의 서비스 내에서 단항 및 3가지 형태의 스트리밍 통신 방식을 선언합니다.
```protobuf
service UserService {
  // 1️⃣ [단항 RPC (Unary RPC)]
  // 1개의 요청을 보내고 1개의 응답을 받는 가장 일반적인 통신 방식 (REST 대체)
  rpc GetUser (UserRequest) returns (UserResponse);

  // 2️⃣ [서버 스트리밍 RPC (Server Streaming)]
  // 클라이언트의 1개 요청에 대해 서버가 여러 개의 응답 메시지를 지속적으로 스트리밍 (다운로드/피드)
  rpc StreamUserLogs (LogRequest) returns (stream LogEntry);

  // 3️⃣ [클라이언트 스트리밍 RPC (Client Streaming)]
  // 클라이언트가 대용량 데이터 조각들을 연속 전송하고, 서버가 처리를 마친 뒤 최종 1회 응답 (파일 업로드)
  rpc UploadAuditLogs (stream AuditLog) returns (UploadSummary);

  // 4️⃣ [양방향 스트리밍 RPC (Bidirectional Streaming)]
  // 클라이언트와 서버가 독립적인 스트림을 열어 언제든 비동기로 메시지를 주고받음 (실시간 채팅/IoT)
  rpc ChatRoom (stream ChatMessage) returns (stream ChatMessage);
}

message UserRequest { int64 id = 1; }
message UserResponse { User user = 1; }
message LogRequest { int64 user_id = 1; }
message LogEntry { string text = 1; int64 timestamp = 2; }
message AuditLog { string action = 1; }
message UploadSummary { int32 count = 1; bool success = 2; }
message ChatMessage { string sender = 1; string message = 2; }
```

## 4. 코드 생성 (protoc 컴파일러 & 플러그인)
`.proto` 파일로부터 타겟 프로그래밍 언어의 모델 클래스와 gRPC 클라이언트/서버 스켈레톤 코드를 자동 생성합니다.
```bash
# 🛠️ [1] protoc CLI 기본 컴파일 명령어
# Go 코드 생성 (protoc-gen-go, protoc-gen-go-grpc 플러그인 필요)
protoc --proto_path=. \
       --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       user.proto

# Python 코드 생성
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. user.proto

# 📦 [2] Go 플러그인 설치 (사전 준비)
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
```

### Gradle 빌드 설정 (`build.gradle.kts` - Java/Kotlin)
```kotlin
plugins {
    id("com.google.protobuf") version "0.9.4"
}

protobuf {
    protoc { artifact = "com.google.protobuf:protoc:3.25.1" }
    plugins {
        create("grpc") { artifact = "io.grpc:protoc-gen-grpc-java:1.60.0" }
    }
    generateProtoTasks {
        all().forEach { task ->
            task.plugins { create("grpc") }
        }
    }
}
```

## 5. Spring Boot & Java 연동 (`@GrpcService` & `@GrpcClient`)
Spring Boot 3 환경에서 `net.devh:grpc-spring-boot-starter`를 이용한 서버 및 클라이언트 구현입니다.
```java
// 🚀 [1] gRPC 서버 구현체 (Spring Boot)
package com.lucky.grpc.server;

import com.lucky.grpc.user.v1.*;
import io.grpc.stub.StreamObserver;
import net.devh.boot.grpc.server.service.GrpcService;

@GrpcService // Spring Bean 등록 및 gRPC 서버에 서비스 자동 노출
public class UserGrpcServiceImpl extends UserServiceGrpc.UserServiceImplBase {

    @Override
    public void getUser(UserRequest request, StreamObserver<UserResponse> responseObserver) {
        long userId = request.getId();
        
        User user = User.newBuilder()
                .setId(userId)
                .setUsername("lucky")
                .setEmail("lucky@example.com")
                .setIsActive(true)
                .build();

        UserResponse response = UserResponse.newBuilder().setUser(user).build();

        // 결과 전송 및 완료 알림
        responseObserver.onNext(response);
        responseObserver.onCompleted();
    }

    // 서버 스트리밍 예제
    @Override
    public void streamUserLogs(LogRequest request, StreamObserver<LogEntry> responseObserver) {
        for (int i = 1; i <= 5; i++) {
            LogEntry entry = LogEntry.newBuilder()
                    .setText("로그 이벤트 #" + i + " for User " + request.getUserId())
                    .setTimestamp(System.currentTimeMillis())
                    .build();
            responseObserver.onNext(entry); // 여러 번 호출
        }
        responseObserver.onCompleted(); // 스트림 종료 알림
    }
}
```

```java
// 💻 [2] Spring Boot 클라이언트 호출 (Stub 주입)
package com.lucky.grpc.client;

import com.lucky.grpc.user.v1.*;
import net.devh.boot.grpc.client.inject.GrpcClient;
import org.springframework.stereotype.Service;

@Service
public class UserClientService {

    // 동기 블로킹 Stub (가장 흔하게 사용)
    @GrpcClient("user-service")
    private UserServiceGrpc.UserServiceBlockingStub userBlockingStub;

    public User fetchUser(long id) {
        UserRequest request = UserRequest.newBuilder().setId(id).build();
        UserResponse response = userBlockingStub.getUser(request);
        return response.getUser();
    }
}
```

### `application.yml` 설정
```yaml
grpc:
  server:
    port: 9090 # gRPC 서버 리스닝 포트
  client:
    user-service:
      address: 'static://localhost:9090'
      negotiation-type: plaintext # 로컬 개발 시 TLS 미적용
```

## 6. Go (Golang) 서버 & 클라이언트 구현
Go는 gRPC의 네이티브 1등 시민 언어로 초경량 고성능 통신에 주로 사용됩니다.
```go
// 🚀 [1] Go gRPC 서버 구현 (main.go)
package main

import (
	"context"
	"log"
	"net"

	pb "myproject/user/v1"
	"google.golang.org/grpc"
)

type server struct {
	pb.UnimplementedUserServiceServer
}

func (s *server) GetUser(ctx context.Context, in *pb.UserRequest) (*pb.UserResponse, error) {
	log.Printf("요청 수신 User ID: %d", in.GetId())
	return &pb.UserResponse{
		User: &pb.User{
			Id:       in.GetId(),
			Username: "lucky_go",
			Email:    "go@example.com",
			IsActive: true,
		},
	}, nil
}

func main() {
	lis, err := net.Listen("tcp", ":50051")
	if err != nil {
		log.Fatalf("포트 바인딩 실패: %v", err)
	}

	s := grpc.NewServer()
	pb.RegisterUserServiceServer(s, &server{})
	log.Println("gRPC Go Server 리스닝 시작 :50051")
	if err := s.Serve(lis); err != nil {
		log.Fatalf("서버 실행 실패: %v", err)
	}
}
```

```go
// 💻 [2] Go gRPC 클라이언트 호출
package main

import (
	"context"
	"log"
	"time"

	pb "myproject/user/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
)

func main() {
	// gRPC 채널 연결 생성
	conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
	if err != nil {
		log.Fatalf("연결 실패: %v", err)
	}
	defer conn.Close()

	client := pb.NewUserServiceClient(conn)

	// 컨텍스트에 2초 타임아웃 지정 (필수 권장!)
	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
	defer cancel()

	resp, err := client.GetUser(ctx, &pb.UserRequest{Id: 42})
	if err != nil {
		log.Fatalf("RPC 호출 실패: %v", err)
	}
	log.Printf("조회된 유저 이름: %s", resp.GetUser().GetUsername())
}
```

## 7. Node.js / TypeScript 구현 (`@grpc/grpc-js`)
Node.js에서 proto 파일을 동적으로 로드하거나 컴파일된 코드로 통신합니다.
```typescript
import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';

// 📂 [1] .proto 파일 동적 로드
const packageDefinition = protoLoader.loadSync('user.proto', {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
});
const userProto: any = grpc.loadPackageDefinition(packageDefinition).user.service.v1;

// 🚀 [2] 서버 구동
const server = new grpc.Server();
server.addService(userProto.UserService.service, {
  GetUser: (call: any, callback: any) => {
    const userId = call.request.id;
    callback(null, {
      user: { id: userId, username: 'lucky_node', email: 'node@test.com' },
    });
  },
});

server.bindAsync('0.0.0.0:50051', grpc.ServerCredentials.createInsecure(), () => {
  console.log('Node.js gRPC Server Running on port 50051');
  server.start();
});

// 💻 [3] 클라이언트 호출
const client = new userProto.UserService('localhost:50051', grpc.credentials.createInsecure());
client.GetUser({ id: 10 }, (err: any, response: any) => {
  if (err) console.error(err);
  else console.log('응답:', response.user);
});
```

## 8. 메타데이터(Metadata) & 인터셉터(Interceptor)
인증 토큰(JWT) 전달, 분산 추적(Tracing), 공통 로깅을 HTTP/2 헤더 메타데이터와 인터셉터로 처리합니다.
```go
// 🔒 [1] 클라이언트: 아웃바운드 헤더에 Bearer 토큰 주입 (Go)
import "google.golang.org/grpc/metadata"

// 메타데이터 생성
md := metadata.Pairs("authorization", "Bearer my-jwt-token", "x-request-id", "uuid-1234")
ctx := metadata.NewOutgoingContext(context.Background(), md)

// 요청 시 메타데이터 컨텍스트 전달
resp, err := client.GetUser(ctx, &pb.UserRequest{Id: 1})
```

```java
// 🛡️ [2] 서버: 인터셉터로 인증 토큰 검증 (Java)
package com.lucky.grpc.interceptor;

import io.grpc.*;
import net.devh.boot.grpc.server.interceptor.GrpcGlobalServerInterceptor;

@GrpcGlobalServerInterceptor
public class AuthServerInterceptor implements ServerInterceptor {
    private static final Metadata.Key<String> AUTH_KEY =
            Metadata.Key.of("authorization", Metadata.ASCII_STRING_MARSHALLER);

    @Override
    public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
            ServerCall<ReqT, RespT> call, Metadata headers, ServerCallHandler<ReqT, RespT> next) {
        
        String authHeader = headers.get(AUTH_KEY);
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            // 인증 실패 시 즉시 UNAUTHENTICATED 에러 리턴
            call.close(Status.UNAUTHENTICATED.withDescription("인증 토큰이 누락되었습니다."), headers);
            return new ServerCall.Listener<ReqT>() {};
        }

        // 정상 요청 계속 진행
        return next.startCall(call, headers);
    }
}
```

## 9. 에러 핸들링 & gRPC 표준 상태 코드
REST HTTP 상태 코드(404, 500 등)와 1:1로 대응되는 gRPC 표준 상태 코드 체계입니다.
```text
[gRPC 표준 상태 코드 (Status Codes)]
• OK (0)                  : 성공 (HTTP 200)
• CANCELLED (1)           : 클라이언트가 작업 취소 (HTTP 499)
• UNKNOWN (2)             : 알 수 없는 서버 내부 오류
• INVALID_ARGUMENT (3)    : 파라미터/입력값 유효성 검증 실패 (HTTP 400)
• DEADLINE_EXCEEDED (4)   : 타임아웃 초과 (HTTP 504)
• NOT_FOUND (5)           : 대상 리소스를 찾을 수 없음 (HTTP 404)
• ALREADY_EXISTS (6)      : 이미 존재하는 리소스 생성 시도 (HTTP 409)
• PERMISSION_DENIED (7)   : 권한 부족 (HTTP 403)
• RESOURCE_EXHAUSTED (8)  : Rate Limit / 쿼터 초과 (HTTP 429)
• UNAUTHENTICATED (16)    : 인증되지 않은 사용자/토큰 만료 (HTTP 401)
```

```java
// ⚠️ 서버에서 비즈니스 예외 던지기 예시 (Java)
if (user == null) {
    responseObserver.onError(
        Status.NOT_FOUND
            .withDescription("ID " + userId + "에 해당하는 사용자를 찾을 수 없습니다.")
            .asRuntimeException()
    );
    return;
}
```

## 10. CLI 디버깅 & 테스트 도구 (`grpcurl`)
Postman GUI 또는 터미널의 `cURL`처럼 gRPC 서버를 손쉽게 호출하고 테스트하는 필수 CLI 도구입니다.
```bash
# 🛠️ [1] grpcurl 설치 (macOS: brew install grpcurl / Go: go install ... / Windows: winget)
winget install fullstorydev.grpcurl

# 🔍 [2] 서버에서 제공하는 서비스 목록 조회 (서버 리플렉션 활성화 필요)
grpcurl -plaintext localhost:9090 list

# 📋 [3] 특정 서비스의 상세 메서드 및 스키마 구조 확인
grpcurl -plaintext localhost:9090 describe user.service.v1.UserService

# ⚡ [4] 단항 RPC 호출 (JSON 문자열 페이로드 전달)
grpcurl -plaintext \
        -d '{"id": 42}' \
        localhost:9090 \
        user.service.v1.UserService/GetUser

# 🔒 [5] 메타데이터(헤더) 포함 호출
grpcurl -plaintext \
        -H 'authorization: Bearer my-secret-token' \
        -d '{"id": 100}' \
        localhost:9090 \
        user.service.v1.UserService/GetUser
```

## 11. 브라우저 연동: gRPC-Web & Envoy Proxy
웹 브라우저는 HTTP/2 바이너리 프레임을 직접 조작할 수 없으므로 중간에 **Envoy Proxy**를 두어 gRPC-Web 프로토콜을 네이티브 gRPC로 변환합니다.
```yaml
# 🌐 Envoy Proxy 라우팅 설정 파일 (envoy.yaml)
static_resources:
  listeners:
  - name: grpc_web_listener
    address:
      socket_address: { address: 0.0.0.0, port_value: 8080 } # 브라우저가 접속할 포트
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: grpc_web
          http_filters:
          - name: envoy.filters.http.grpc_web # ★ gRPC-Web 변환 필터
          - name: envoy.filters.http.cors     # ★ 브라우저 CORS 허용 필터
          - name: envoy.filters.http.router
          route_config:
            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["*"]
              cors:
                allow_origin_string_match: [{ prefix: "*" }]
                allow_methods: GET, PUT, DELETE, POST, OPTIONS
                allow_headers: keep-alive,user-agent,cache-control,content-type,content-transfer-encoding,x-accept-content-transfer-encoding,x-accept-response-streaming,x-user-agent,x-grpc-web,grpc-timeout
              routes:
              - match: { prefix: "/" }
                route:
                  cluster: backend_grpc_service
                  timeout: 0s

  clusters:
  - name: backend_grpc_service
    connect_timeout: 0.25s
    type: logical_dns
    http2_protocol_options: {} # 백엔드와 HTTP/2 통신
    load_assignment:
      cluster_name: backend_grpc_service
      endpoints:
      - lb_endpoints:
        - endpoint:
            socket_address: { address: 127.0.0.1, port_value: 9090 } # 실제 백엔드 gRPC 포트
```
💬
gRPC & Protobuf 치트시트

의견 및 질문

댓글 수정

댓글 삭제
