웹 브라우저에서 바른 사용하기 (connect-web)
웹 브라우저에서 바른을 호출할 때는 connect-web을 사용합니다.
connect-web은 Connect-RPC의 웹(브라우저) 클라이언트로, 표준 fetch 위에서 동작하며
별도의 프록시 없이 바른 서버를 직접 호출합니다. 바른 서버가 connect-go로 구현되어
브라우저 요청을 그대로 받고, CORS도 서버가 직접 처리합니다.
grpc-web은 더 이상 사용하지 않습니다
예전에는 브라우저에서 gRPC를 쓰려고 grpc-web을 사용했고, 이때는 Envoy 같은 프록시를
꼭 거쳐야 했습니다. 지금은 connect-web으로 일원화되어 프록시 없이 서버를 직접 호출합니다.
자바스크립트 클라이언트를 옮기는 방법은 connect-web 마이그레이션을 참고하세요.
무엇을 쓰나요
| 항목 | 패키지 |
|---|---|
| RPC 클라이언트 | @connectrpc/connect |
| 브라우저 전송 계층 | @connectrpc/connect-web |
| 메시지 직렬화 | @bufbuild/protobuf |
npm install @connectrpc/connect @connectrpc/connect-web @bufbuild/protobuf
클라이언트 코드는 어떻게 얻나요
복잡한 빌드 과정을 직접 거칠 필요가 없습니다. 두 가지 방법이 있습니다.
- 배포본에 포함된 코드 사용(권장): 바른 배포본에는 connect-web에서 바로 가져다 쓸 수 있는
TypeScript 클라이언트 코드(메시지 + Connect 서비스 스텁)가 함께 들어 있습니다.
프로젝트로 복사해
import하면 별도 생성 없이 바로 호출할 수 있습니다. (LanguageService,CustomDictionaryService,RevisionService와 각 메시지 타입이 들어 있습니다.) - 공개된 proto로 직접 생성: 바른의
.proto정의는 공개되어 있어, 원하는 환경에 맞춰 직접 생성해서 쓸 수도 있습니다. 배포본의shared/proto/아래에.proto파일이 들어 있으며,buf와@bufbuild/protoc-gen-es로 스텁을 만들 수 있습니다.
# connect-web 코드 생성 도구 설치
npm install -D @bufbuild/buf @bufbuild/protoc-gen-es
# 공개된 .proto 로부터 TypeScript(메시지 + Connect 서비스) 생성
npx buf generate
grpc-web은 더 이상 필요 없습니다
예전 grpc-web 방식과 달리, connect-web 코드는 @bufbuild/protoc-gen-es 하나로
메시지와 Connect 서비스가 함께 만들어집니다. 별도의 grpc-web 산출물이나 프록시가 필요 없습니다.
코드 샘플
API 키는 요청 헤더 api-key로 전달합니다. connect-web에서는 인터셉터로 모든 요청에
헤더를 붙이는 방식이 깔끔합니다.
import { createConnectTransport } from "@connectrpc/connect-web";
import { createClient } from "@connectrpc/connect";
import { LanguageService } from "./gen/bareun/language_service_pb";
import { EncodingType } from "./gen/bareun/language_service_pb";
// 모든 요청에 api-key 헤더를 붙이는 인터셉터
const withApiKey = (next) => async (req) => {
req.header.set("api-key", "koba-XXXX-..."); // 본인 API 키
return await next(req);
};
// 바른 서버로의 전송 계층(브라우저는 fetch 기반).
// 클라우드는 https://api.bareun.ai, 설치본은 http://localhost:5656
const transport = createConnectTransport({
baseUrl: "https://api.bareun.ai",
interceptors: [withApiKey],
});
const client = createClient(LanguageService, transport);
// AnalyzeSyntax 호출
const res = await client.analyzeSyntax({
document: { content: "오늘 날씨가 참 좋네요.", language: "ko_KR" },
encodingType: EncodingType.UTF16, // 브라우저(JS)는 UTF-16 권장
autoSpacing: true,
});
for (const sent of res.sentences) {
console.log(sent.refined); // 띄어쓰기 등 보정된 문장
for (const tok of sent.tokens) {
console.log(tok.tagged); // 형태소/품사 (예: 오늘/NNG+...)
}
}
인코딩 타입은 클라이언트 언어에 맞추세요
자바스크립트 문자열은 UTF-16 기반이라 위치 값(begin_offset)을 그대로 쓰려면
EncodingType.UTF16이 자연스럽습니다. 자세한 내용은 형태소 분석 API의
encoding_type 설명을 참고하세요.
어디로 연결하나요
| 환경 | baseUrl |
|---|---|
| 클라우드 | https://api.bareun.ai (TLS, API 키 필요) |
| 설치본(네이티브) | http://localhost:5656 |
| 도커 배포본 | http://localhost:5656 |
자주 묻는 질문
Q. 브라우저에서 바른을 쓰려면 Envoy 같은 프록시가 필요한가요?
아닙니다. connect-web은 바른 서버(connect-go)를 직접 호출합니다. 서버가 connect-web 요청과 CORS를 직접 처리하므로 별도의 프런트 프록시가 필요 없습니다.
Q. 스텁은 어디서 가져오나요?
protos/protoc.sh가 buf generate로 web/utility/src/gen/에 TypeScript 스텁을 생성합니다.
@bufbuild/protoc-gen-es가 메시지와 Connect 서비스를 함께 만들어 줍니다.
Q. API 키는 어떻게 전달하나요?
요청 헤더 api-key에 koba-로 시작하는 키를 넣습니다. 모든 호출에 일관되게 붙이려면
connect 인터셉터로 처리하는 방법을 권장합니다.