gRPC 완전 가이드 — Protocol Buffers 설계부터 Node.js 서버·클라이언트 구현, REST와 성능 비교까지

proto/user.proto
syntax = "proto3";

package user;

// 서비스 정의 — RPC 메서드 목록
service UserService {
  // Unary RPC: 요청 1개 → 응답 1개
  rpc GetUser (GetUserRequest) returns (User);
  rpc CreateUser (CreateUserRequest) returns (User);
  rpc UpdateUser (UpdateUserRequest) returns (User);
  rpc DeleteUser (DeleteUserRequest) returns (DeleteUserResponse);
  // 서버 스트리밍: 요청 1개 → 응답 스트림
  rpc ListUsers (ListUsersRequest) returns (stream User);
}

// 메시지 타입 정의
message User {
  string id = 1;
  string email = 2;
  string name = 3;
  string role = 4;
  int64 created_at = 5;  // Unix timestamp (밀리초)
}

message GetUserRequest {
  string id = 1;
}

message CreateUserRequest {
  string email = 1;
  string name = 2;
  string role = 3;
}

message ListUsersRequest {
  int32 page = 1;
  int32 page_size = 2;
  string role_filter = 3;  // 비어있으면 전체 조회
}

message UpdateUserRequest {
  string id = 1;
  optional string email = 2;  // proto3 optional: 필드 존재 여부 구분
  optional string name = 3;
}

message DeleteUserRequest {
  string id = 1;
}

message DeleteUserResponse {
  bool success = 1;
  string message = 2;
}

bash — 의존성 설치
npm install @grpc/grpc-js @grpc/proto-loader
# TypeScript 사용 시
npm install -D typescript @types/node ts-node

server.js — gRPC 서버 전체 구현
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const path = require('path');

// .proto 파일 로드
const PROTO_PATH = path.join(__dirname, 'proto/user.proto');
const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
});
const userProto = grpc.loadPackageDefinition(packageDefinition).user;

// 인메모리 저장소 (실제 서비스에서는 DB로 교체)
const users = new Map();

const userServiceHandlers = {
  // Unary RPC: 사용자 단건 조회
  GetUser: (call, callback) => {
    const user = users.get(call.request.id);
    if (!user) {
      return callback({
        code: grpc.status.NOT_FOUND,
        message: `사용자 ${call.request.id}를 찾을 수 없습니다`
      });
    }
    callback(null, user);
  },

  // Unary RPC: 사용자 생성
  CreateUser: (call, callback) => {
    const { email, name, role } = call.request;
    if (!email || !name) {
      return callback({
        code: grpc.status.INVALID_ARGUMENT,
        message: 'email과 name은 필수입니다'
      });
    }
    const id = `user_${Date.now()}`;
    const user = { id, email, name, role: role || 'user', created_at: Date.now() };
    users.set(id, user);
    callback(null, user);
  },

  // 서버 스트리밍: 조건에 맞는 사용자를 하나씩 전송
  ListUsers: (call) => {
    const { role_filter } = call.request;
    for (const user of users.values()) {
      if (!role_filter || user.role === role_filter) {
        call.write(user);  // 스트림으로 순차 전송
      }
    }
    call.end();  // 스트림 종료 신호
  },

  UpdateUser: (call, callback) => {
    const { id, email, name } = call.request;
    const user = users.get(id);
    if (!user) {
      return callback({ code: grpc.status.NOT_FOUND, message: '사용자 없음' });
    }
    if (email) user.email = email;
    if (name) user.name = name;
    users.set(id, user);
    callback(null, user);
  },

  DeleteUser: (call, callback) => {
    const deleted = users.delete(call.request.id);
    callback(null, { success: deleted, message: deleted ? '삭제됨' : '존재하지 않는 ID' });
  }
};

function main() {
  const server = new grpc.Server();
  server.addService(userProto.UserService.service, userServiceHandlers);

  // 프로덕션에서는 createSsl()로 TLS 적용
  server.bindAsync('0.0.0.0:50051', grpc.ServerCredentials.createInsecure(), (err, port) => {
    if (err) {
      console.error('서버 시작 실패:', err);
      return;
    }
    console.log(`gRPC 서버가 포트 ${port}에서 시작됨`);
  });
}
main();

client.js — gRPC 클라이언트 전체 구현
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const path = require('path');

const PROTO_PATH = path.join(__dirname, 'proto/user.proto');
const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
  keepCase: true, longs: String, enums: String, defaults: true, oneofs: true
});
const userProto = grpc.loadPackageDefinition(packageDefinition).user;

// 클라이언트 생성
const client = new userProto.UserService(
  'localhost:50051',
  grpc.credentials.createInsecure()
);

// Unary RPC: Promise 래퍼
function createUser(email, name) {
  return new Promise((resolve, reject) => {
    // deadline 지정 — 미지정 시 영구 대기
    const deadline = new Date(Date.now() + 5000);  // 5초
    client.CreateUser({ email, name, role: 'user' }, { deadline }, (err, response) => {
      if (err) return reject(err);
      resolve(response);
    });
  });
}

// 서버 스트리밍: 이벤트 기반 소비
function listAllUsers() {
  const stream = client.ListUsers({ page: 1, page_size: 100 });
  const users = [];

  stream.on('data', (user) => {
    users.push(user);
    console.log('수신:', user.name, user.email);
  });

  stream.on('error', (err) => {
    console.error('스트림 에러:', err.message);
  });

  stream.on('end', () => {
    console.log(`총 ${users.length}명 수신 완료`);
  });
}

// 메타데이터로 인증 토큰 전달
function getUserWithAuth(userId, token) {
  const metadata = new grpc.Metadata();
  metadata.add('authorization', `Bearer ${token}`);

  return new Promise((resolve, reject) => {
    client.GetUser({ id: userId }, metadata, (err, response) => {
      if (err) return reject(err);
      resolve(response);
    });
  });
}

(async () => {
  try {
    const user = await createUser('dev@example.com', '개발자');
    console.log('생성됨:', user);
    listAllUsers();
  } catch (err) {
    // gRPC 에러 코드 확인
    if (err.code === grpc.status.DEADLINE_EXCEEDED) {
      console.error('타임아웃 — 서버 응답 없음');
    } else {
      console.error('에러:', err.message);
    }
  }
})();

proto/chat.proto — 양방향 스트리밍 RPC 정의
syntax = "proto3";
package chat;

service ChatService {
  // 양방향 스트리밍 RPC
  rpc Chat (stream ChatMessage) returns (stream ChatMessage);
}

message ChatMessage {
  string user_id = 1;
  string content = 2;
  int64 timestamp = 3;
  string room_id = 4;
}

양방향 스트리밍 서버 핸들러 구현
const chatHandlers = {
  Chat: (call) => {
    // call은 읽기+쓰기 동시 가능한 양방향 스트림
    call.on('data', (message) => {
      console.log(`[${message.room_id}] ${message.user_id}: ${message.content}`);

      // 수신 즉시 응답 전송 (실제에서는 같은 룸 사용자들에게 브로드캐스트)
      const reply = {
        user_id: 'server',
        content: `[에코] ${message.content}`,
        timestamp: Date.now(),
        room_id: message.room_id
      };
      call.write(reply);
    });

    call.on('end', () => {
      call.end();  // 클라이언트가 스트림을 닫으면 서버도 닫기
    });

    call.on('error', (err) => {
      console.error('스트림 에러:', err);
    });
  }
};

// 클라이언트 쪽 양방향 스트리밍 사용법
// const stream = client.Chat();
// stream.write({ user_id: 'user1', content: '안녕하세요', room_id: 'room1' });
// stream.on('data', (msg) => console.log('수신:', msg.content));
// stream.end();  // 전송 완료

interceptors.js — 클라이언트 재시도 인터셉터
const grpc = require('@grpc/grpc-js');

// 클라이언트 재시도 인터셉터 — UNAVAILABLE, DEADLINE_EXCEEDED 시 자동 재시도
function retryInterceptor(options, nextCall) {
  const MAX_RETRIES = 3;
  let retries = 0;
  let savedMessage;
  let savedMetadata;

  return new grpc.InterceptingCall(nextCall(options), {
    start: function(metadata, listener, next) {
      savedMetadata = metadata;
      const newListener = {
        onReceiveStatus: (status, next) => {
          const retryable = [
            grpc.status.UNAVAILABLE,
            grpc.status.DEADLINE_EXCEEDED
          ];
          if (retryable.includes(status.code) && retries < MAX_RETRIES) {
            retries++;
            const delay = 1000 * Math.pow(2, retries - 1);  // 지수 백오프
            console.log(`재시도 ${retries}/${MAX_RETRIES} — ${delay}ms 후`);
            setTimeout(() => {
              const newCall = nextCall(options);
              newCall.start(savedMetadata, newListener);
              if (savedMessage) newCall.sendMessage(savedMessage);
              newCall.halfClose();
            }, delay);
            return;
          }
          next(status);
        },
        onReceiveMessage: (message, next) => next(message),
        onReceiveMetadata: (metadata, next) => next(metadata)
      };
      next(metadata, newListener);
    },
    sendMessage: (message, next) => {
      savedMessage = message;
      next(message);
    },
    halfClose: (next) => next()
  });
}

// 클라이언트 생성 시 인터셉터 등록
const client = new userProto.UserService(
  'localhost:50051',
  grpc.credentials.createInsecure(),
  { interceptors: [retryInterceptor] }
);

package.json — 코드 생성 스크립트
{
  "scripts": {
    "proto:gen": "protoc --plugin=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=./generated --ts_proto_opt=outputServices=grpc-js,esModuleInterop=true -I ./proto ./proto/*.proto",
    "proto:check": "buf breaking --against .git#branch=main"
  },
  "devDependencies": {
    "ts-proto": "^1.180.0",
    "grpc-tools": "^1.12.4",
    "@bufbuild/buf": "^1.30.0"
  }
}

grpcurl 사용 예시
# 서비스 목록 확인 (서버에 reflection 활성화 필요)
grpcurl -plaintext localhost:50051 list

# 특정 서비스 메서드 확인
grpcurl -plaintext localhost:50051 list user.UserService

# Unary RPC 호출 (-d로 JSON 형식 요청 전달)
grpcurl -plaintext \
  -d '{"email":"dev@example.com","name":"개발자","role":"user"}' \
  localhost:50051 user.UserService/CreateUser

# 메타데이터(인증 토큰) 포함 호출
grpcurl -plaintext \
  -H 'authorization: Bearer eyJhbGciOiJIUzI1NiIs...' \
  -d '{"id":"user_123"}' \
  localhost:50051 user.UserService/GetUser

# gRPC-UI 브라우저 UI 실행
grpcui -plaintext localhost:50051