Connect-Web

개요

Connect-Web은 gRPC 통신을 브라우저 환경에서 쉽게 구현할 수 있도록 지원하는 TypeScript 기반의 gRPC-Web 클라이언트 프레임워크입니다. Buf.build에서 제공되며, protobuf 기반의 서비스에 대해 gRPC, gRPC-Web, Connect, gRPC-JSON 등을 HTTP/1.1 환경에서도 브라우저에서 호출 가능하도록 구현할 수 있게 해줍니다.

---

1. 개념 및 정의

항목	설명
정의	gRPC 서비스와 브라우저 간 통신을 위한 gRPC-Web/Connect/gRPC-JSON 클라이언트 라이브러리
목적	HTTP/1.1 환경에서 gRPC-like 통신 구현
필요성	브라우저와 gRPC 백엔드 간 원활한 타입 안전 통신 구현 필요

Connect-Web은 Connect Protocol과 protobuf를 활용해 웹에서 gRPC-like API를 간단하게 호출할 수 있게 함

---

2. 특징

특징	설명	비교
TypeScript 완전 지원	protobuf → TypeScript 타입 자동 생성	gRPC-Web은 TS 지원 불완전함
HTTP/1.1 호환	Web 환경에서 제약 없이 작동	gRPC는 HTTP/2 필요
Connect Protocol 지원	gRPC + REST-like Hybrid	REST/gRPC 통합 운영 가능

buf CLI와 통합 시 개발자가 protobuf에서 자동 생성 가능

---

3. 구성 요소

구성 요소	설명	예시
Code Generator	protobuf → TypeScript 생성기	buf generate 사용
Transport Layer	gRPC-Web, Connect, JSON 선택 가능	fetch 기반 transport 구현 가능
Interceptor	요청/응답 인터셉터 지원	인증 토큰 삽입 등

프론트엔드에서 API 호출 시 REST와 거의 유사한 방식으로 사용 가능

---

4. 기술 요소

기술	설명	사용 예
Protobuf 기반 타입 정의	서비스 및 메시지 정의	타입 안전한 API 개발
Fetch 기반 구현	표준 fetch API로 transport 구성	axios 미사용, 브라우저 호환성 확보
gRPC-JSON Mapping	JSON 직렬화 기반 통신 지원	REST 백엔드 호환 가능

Next.js, React, Vue 등과 함께 사용 가능

---

5. 장점 및 이점

장점	설명	효과
타입 안정성	자동 생성된 TS 타입 사용	런타임 오류 감소
다양한 통신 프로토콜 지원	gRPC-Web, JSON, Connect	이기종 시스템 간 유연한 연결 가능
최소한의 러닝커브	REST 스타일 유사한 API 사용법	gRPC 미숙자도 빠르게 적응 가능

프론트엔드와 백엔드 간 계약(Contract) 기반 통신이 가능

---

6. 주요 활용 사례 및 고려사항

사례	설명	참고사항
SPA + gRPC 통신	리액트 앱에서 gRPC 호출	connect-query와 조합 활용
백오피스 대시보드	REST처럼 API 호출 + 자동 타입 적용	Swagger 없이 protobuf만으로 개발 가능
인증 연동	Interceptor로 JWT 삽입 등	OAuth2와 통합 쉬움

HTTP/2 환경 미지원 브라우저에서는 gRPC-Web 또는 JSON만 활용해야 함

---

7. 결론

Connect-Web은 gRPC 통신을 웹 환경에서도 안전하고 효율적으로 구현할 수 있도록 지원하는 현대적인 프레임워크입니다. TypeScript와의 높은 호환성, 다양한 전송 방식 지원, 직관적인 사용성 덕분에 빠르게 성장하고 있으며, 프론트엔드와 백엔드 간 견고한 API 계약 기반 통신을 구현하고자 하는 프로젝트에 이상적인 선택지입니다.