웹에서 사용하기(connect-web)

웹 브라우저에서 바른 사용하기 (connect-web)

웹 브라우저에서 바른을 호출할 때는 connect-web을 사용합니다. connect-web은 Connect-RPC의 웹(브라우저) 클라이언트로, 표준 fetch 위에서 동작하며 별도의 프록시 없이 바른 서버를 직접 호출합니다. 바른 서버가 connect-go로 구현되어 브라우저 요청을 그대로 받고, CORS도 서버가 직접 처리합니다.

grpc-web은 더 이상 사용하지 않습니다

예전에는 브라우저에서 gRPC를 쓰려고 grpc-web을 사용했고, 이때는 Envoy 같은 프록시를 꼭 거쳐야 했습니다. 지금은 connect-web으로 일원화되어 프록시 없이 서버를 직접 호출합니다. JavaScript 클라이언트를 옮기는 방법은 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 인터셉터로 처리하는 방법을 권장합니다.

도움이 되었나요?

의견 보내기