Web을 위한 gRPC Stub과 Runtime 생성하기 - Feat. Buf & kubernetes

뱅크샐러드 웹 프론트엔드 팀은 마이크로서비스 아키텍처 전환 과정에서 gRPC 통신의 유지보수 부담을 줄이기 위해 Buf와 @bufbuild/protoplugin을 활용한 클라이언트 코드 자동 생성 시스템을 구축했다. 기존에는 프론트엔드에서 grpc-gateway를 통해 HTTP로 gRPC 메시지를 소비했으나, 서비스 증가에 따라 중복된 HTTP 클라이언트 코드 작성과 외부 도메인 호출로 인한 IPS 부하가 주요 문제로 대두되었다.

Buf 기반 코드 자동 생성 및 내부/외부 분리

개발팀은 .proto 파일의 google.api.http 옵션을 파싱하여 TypeScript 클라이언트 코드를 자동 생성하는 커스텀 플러그인을 개발했다. 이 과정에서 internal(k8s 내부망)과 external(사용자 기기) 엔드포인트를 명확히 구분하여 별도의 클래스(EchoServiceInternalClient, EchoServiceExternalClient)로 분리 생성했다. 이는 Webpack 전처리 대신 런타임 시 내부망 주소 노출을 원천 차단하여 보안을 강화하고, 불필요한 코드 번들링을 방지하기 위한 전략이다.

성능 최적화 및 개발 생산성 향상

자동 생성된 코드는 Nx 모노레포의 공용 라이브러리로 병합되며, copybara를 통해 사내 레포지토리의 .proto 변경 사항이 CI 워크플로우를 통해 실시간 반영된다. SSR(Server-Side Rendering) 환경에서는 k8s 서비스 DNS를 직접 사용하는 InternalClient를 적용해 방화벽 통과 과정을 생략했다. 그 결과 동일 RPC 호출 시 기존 외부망 호출 대비 응답 속도가 200ms에서 20ms 수준으로 90% 감소했다.

향후 계획 및 제한 사항

현재는 react-query의 QueryOption을 수동으로 작성해야 하는 번거로움이 남아있으나, 팀은 connect-query에서 영감을 받아 쿼리 옵션 객체와 Hook을 자동 생성하는 기능을 개발 중이다. 이 접근법은 gRPC-web 대비 일부 제약이 있을 수 있으나, gRPC-gateway 환경에서 추가 인프라 비용 없이 타입 안전성과 개발 효율성을 크게 높인 사례로 평가된다.