Connect-RPC vs gRPC vs REST — 언제 무엇을 쓸까
바른은 하나의 서버에서 Connect-RPC, gRPC, REST(HTTP/1.1) 세 가지 방식으로
형태소 분석 API를 제공합니다. 같은 LanguageService를 같은 포트로 노출하므로,
프로토콜은 클라이언트 환경에 맞춰 자유롭게 고르시면 됩니다.
이 문서는 세 프로토콜의 차이와 선택 기준을 정리합니다. "어떤 환경에서 무엇을 쓰는 게 가장 편한가"를 빠르게 판단하시는 데 목적이 있습니다.
세 프로토콜 한눈에 비교
바른 서버는 Go 기반의 connect-go로 구현되어 있어, 동일한 엔드포인트가 세 프로토콜을 동시에 받아줍니다. 브라우저에서는 connect-web을 권장합니다.
| 항목 | Connect-RPC | gRPC | REST(HTTP/1.1) |
|---|---|---|---|
| 전송 | HTTP/1.1·HTTP/2 | HTTP/2 | HTTP/1.1 |
| 메시지 | Protobuf / JSON | Protobuf | JSON |
| 브라우저 직접 호출 | 가능(connect-web) | 어려움(프록시 필요) | 가능 |
| 스트리밍 | 지원 | 지원 | 미지원 |
| 대표 클라이언트 | JS(connect-web) | 파이썬·자바·R | 모든 HTTP 클라이언트 |
| 권장 용도 | 웹 프런트엔드 | 서버 간 대량 처리 | 간단한 연동·테스트 |
어떤 기준으로 고르나요
graph TD
Q{호출 주체는?} --> B[브라우저/웹앱]
Q --> S[서버/배치]
Q --> T[빠른 테스트]
B --> CW[Connect-RPC<br/>connect-web]
S --> G[gRPC<br/>bareunpy·Java·R]
T --> R[REST<br/>curl·HTTP 클라이언트]
- 웹 프런트엔드라면
Connect-RPC(connect-web)를 권장합니다. 별도 프록시 없이 브라우저에서 바로 호출할 수 있습니다. - 서버 간 통신·대량 배치라면
gRPC가 효율적입니다. Protobuf 이진 인코딩과 HTTP/2 멀티플렉싱으로 처리량이 좋습니다. Python(bareunpy)·Java·R 클라이언트가 이 방식을 씁니다. - 빠른 확인·간단한 연동에는
REST가 편합니다.curl이나 익숙한 HTTP 라이브러리로 바로 호출해볼 수 있습니다.
어디로 연결하나요
클라우드와 설치본 모두 같은 LanguageService를 제공합니다. 주소만 다릅니다.
| 환경 | 주소 | 비고 |
|---|---|---|
| 클라우드 | api.bareun.ai:443 | TLS, API 키 필요 |
| 설치본(네이티브) | localhost:5656 | 기본 포트 |
| 도커 배포본 | localhost:5656 | 서버가 직접 서비스 |
한 서버, 세 가지 입구
바른 서버는 같은 서비스 정의(LanguageService)를 세 프로토콜로 동시에 받습니다.
프로토콜을 바꿔도 요청·응답 메시지 구조(AnalyzeSyntaxRequest, Sentence, Token,
Morpheme)는 동일하므로, 나중에 다른 방식으로 옮기더라도 코드 변경이 작습니다.
자주 묻는 질문
Q. 브라우저에서 gRPC를 직접 호출할 수 없나요?
브라우저는 표준 gRPC(HTTP/2 트레일러 기반)를 직접 호출하지 못합니다.
그래서 브라우저에서는 Connect-RPC(connect-web)로 바른 서버(포트 5656)를 직접 호출합니다.
Q. 프로토콜마다 응답 결과가 다른가요?
아닙니다. 같은 LanguageService를 노출하므로 분석 결과(문장·어절·형태소 구조)는 동일합니다.
인코딩 타입에 따른 위치(offset) 계산만 클라이언트 언어 관례에 맞춰 지정하시면 됩니다.
Q. 가장 처리량이 좋은 방식은 무엇인가요?
대량 처리에는 일반적으로 gRPC가 유리합니다. Protobuf 이진 인코딩과 HTTP/2 멀티플렉싱 덕분입니다.
다만 단건 호출·간단 연동에서는 REST와 체감 차이가 크지 않습니다.
Q. 바른 REST API 경로는 어떻게 되나요?
바른 서버는 connect-go로 한 포트에서 gRPC·connect-web·HTTP+JSON을 모두 처리하므로,
REST 호출도 Connect 경로 POST /bareun.<Service>/<Method>를 씁니다.
예를 들어 형태소 분석은 POST /bareun.LanguageService/AnalyzeSyntax입니다.
옛 게이트웨이 경로(/bareun/api/v1/...)나 별도 Envoy 프런트는 쓰지 않습니다.