gRPC 프로젝트에 Reflection API 적용하기

문제 상황

마이크로서비스 아키텍처로 전환하면서 REST API 대신 gRPC를 도입했다. 성능은 만족스러웠지만, 개발 중 특정 서비스의 API를 확인하고 테스트하는 과정이 번거로웠다.

REST에서는 Postman이나 curl로 간단히 테스트했지만, gRPC는 proto 파일이 필요했다. 다른 팀의 서비스를 호출할 때마다 proto 파일을 받아서 컴파일하는 과정이 반복되었다.

gRPC Reflection

gRPC는 서버가 자신의 서비스 정의를 동적으로 노출할 수 있는 Reflection API를 제공한다. 이를 활성화하면 클라이언트가 proto 파일 없이도 서비스 스펙을 조회할 수 있다.

Node.js 서버에 적용한 코드:

const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');

const server = new grpc.Server();

// 기존 서비스 등록
server.addService(userService, implementation);

// Reflection 활성화
const reflection = require('grpc-reflection-js');
reflection.register(server);

server.bind('0.0.0.0:50051', grpc.ServerCredentials.createInsecure());
server.start();

활용

Reflection이 활성화되면 grpcurl 같은 도구로 서비스를 탐색할 수 있다.

# 서비스 목록 조회
grpcurl -plaintext localhost:50051 list

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

# API 호출
grpcurl -plaintext -d '{"id": "123"}' localhost:50051 user.UserService/GetUser

주의사항

Reflection은 개발/스테이징 환경에서만 활성화하는 것이 좋다. 프로덕션에서는 보안상 서비스 구조가 노출되는 것을 막기 위해 환경변수로 제어했다.

if (process.env.NODE_ENV !== 'production') {
  reflection.register(server);
}

팀 내 gRPC 디버깅 효율이 크게 개선되었다. proto 파일 공유 없이도 API 스펙을 확인하고 테스트할 수 있게 되었다.