Java API 사용 가이드

이 문서는 바른(Bareun) Java 클라이언트 라이브러리(공개 저장소: https://github.com/bareun-nlp/bareun-java)를 이용해 바른 서버에 요청을 보내는 방법을 설명합니다. 예제는 형태소(구문) 분석을 중심으로 구성되어 있으며, gRPC 기반 클라이언트 사용법과 REST를 통한 간단 호출 예시를 포함합니다.

목표(요약)

Java 애플리케이션에서 바른 서버에 안전하게 요청을 보내고 응답을 파싱하는 방법을 설명합니다.
구성: 의존성 추가(Maven/Gradle), 클라이언트 초기화, 요청 빌드, 응답 처리, 예외 처리, 배포 팁.

요구사항

Java 11+ 권장
Maven 또는 Gradle 빌드 도구
바른 서버(로컬/도커 또는 클라우드)가 실행 중이어야 합니다. 기본 로컬 포트: 5656

1. 라이브러리 의존성 추가

Maven (pom.xml)

<dependency>
  <groupId>ai.bareun.tagger</groupId>
  <artifactId>bareun</artifactId>
  <version>1.3.0</version>
</dependency>

Gradle (Groovy DSL)

implementation 'ai.bareun.tagger:bareun:1.3.0'

참고: 위 좌표 및 버전은 예시입니다. 실제 최신 버전과 그룹/아티팩트는 저장소(https://github.com/bareun-nlp/bareun-java)의 README 또는 Maven Central(GitHub Packages)을 확인하세요.

2. 인증과 서버 설정

로컬 테스트: 서버가 로컬에서 실행 중이면 기본 포트는 5757입니다.
클라우드: api.bareun.ai (HTTPS, 포트 443) 같은 엔드포인트를 사용합니다.
API 키: 바른 서버(또는 대시보드)에 API 키를 등록하고 클라이언트에서 전송해야 합니다. API 키 형식은 보통 koba-... 형식입니다.

환경 변수 또는 설정 파일 예시

BAREUN_HOST=localhost
BAREUN_PORT=5656
BAREUN_API_KEY=koba-xxxxxxxxxxxx

3. gRPC 기반 Java 클라이언트 예제 (권장)

아래 예제는 gRPC 클라이언트를 사용해 형태소(구문) 분석을 요청하는 기본 흐름입니다. 실제 클래스 이름은 라이브러리 버전에 따라 다를 수 있으므로, 프로젝트의 패키지 구조를 확인하세요.

import ai.bareun.tagger.LanguageServiceClient;
import ai.bareun.protos.Document;
import ai.bareun.protos.AnalyzeSyntaxRequest;
import ai.bareun.protos.AnalyzeSyntaxResponse;

public class BareunGrpcExample {
    public static void main(String[] args) throws Exception {
        String host = System.getenv().getOrDefault("BAREUN_HOST", "localhost");
        int port = Integer.parseInt(System.getenv().getOrDefault("BAREUN_PORT", "5656"));
        String apiKey = System.getenv().getOrDefault("BAREUN_API_KEY", "");

        // 클라이언트 생성 (라이브러리 제공 API 사용)
        LanguageServiceClient client = new LanguageServiceClient(host, port, apiKey);

        Document doc = Document.newBuilder()
                .setText("바른을 이용한 형태소 분석 예제입니다.")
                .build();

        AnalyzeSyntaxRequest req = AnalyzeSyntaxRequest.newBuilder()
                .setDocument(doc)
                .build();

        AnalyzeSyntaxResponse resp = client.analyzeSyntax(req);

        // 예: 토큰과 품사 출력
        resp.getSentencesList().forEach(s -> System.out.println("Sentence: " + s.getText()));
        resp.getTokensList().forEach(t -> System.out.println(t.getText() + "\t" + t.getPartOfSpeech()));

        client.close();
    }
}

3.1 연결 보안

클라우드(HTTPS)나 인증이 필요한 환경에서는 TLS와 API 키(혹은 메타데이터)를 적절히 설정해야 합니다. 라이브러리는 보통 API 키를 gRPC 메타데이터로 전송하거나, 생성자에서 키를 받아 자동으로 인증 헤더를 추가합니다.

4. REST(HTTP) 호출 예제 (간단)

라이브러리 대신 직접 REST로 호출해야 하거나 간단히 테스트할 때는 OkHttp 같은 HTTP 클라이언트를 사용할 수 있습니다.

import okhttp3.*;
import com.google.gson.Gson;

public class BareunRestExample {
    public static void main(String[] args) throws Exception {
        OkHttpClient client = new OkHttpClient();
        String apiKey = System.getenv("BAREUN_API_KEY");
        String url = "http://localhost:5757/v1/analyze/syntax"; // 서버의 REST 엔드포인트 예시

        String jsonBody = new Gson().toJson(Map.of("text", "바른을 이용한 REST 예제입니다."));

        Request request = new Request.Builder()
                .url(url)
                .addHeader("api-key", apiKey)
                .post(RequestBody.create(jsonBody, MediaType.get("application/json; charset=utf-8")))
                .build();

        try (Response response = client.newCall(request).execute()) {
            if (!response.isSuccessful()) throw new RuntimeException("Unexpected code " + response);
            System.out.println(response.body().string());
        }
    }
}

REST 경로와 요청/응답 스펙은 서버 설정에 따라 달라질 수 있으므로 REST API 문서를 함께 참고하세요.

5. 응답 파싱과 데이터 모델

바른 서버는 Protobuf 기반 응답을 제공합니다. Java에서는 생성된 Protobuf 클래스를 사용해 응답을 파싱합니다.
주요 데이터: 문장(문장 경계), 토큰(형태소), 표준화된 품사, 교정 제안(있을 경우)

예시: 토큰에서 형태소 텍스트와 품사 추출

resp.getTokensList().forEach(token -> {
    String text = token.getText();
    String pos = token.getPartOfSpeech();
    System.out.printf("%s\t%s\n", text, pos);
});

6. 예외 처리 및 재시도 전략

네트워크 타임아웃과 서버 오류(5xx)에 대해 재시도 로직을 마련하세요.
인증 오류(401/403)는 API 키 확인이나 만료 여부를 점검하도록 합니다.
잘못된 입력(빈 텍스트 등)은 호출 전에 검증합니다.

7. 개발·배포 팁

로컬에서 도커로 서버를 띄워 개발하세요. 도커 관련 문서는 설치/도커 문서를 참고합니다.
대량 호출 시에는 연결(채널) 재사용과 커넥션 풀을 고려하세요.
성능 측정: 샘플 문장을 준비해 latency와 throughput을 측정하고, 필요시 서버 리소스(GPU/CPU)와 설정을 조정하세요.

8. 문제 해결(FAQ)

“API key authentication failed” 메시지가 나오면: API 키 형식 및 서버 등록 상태를 확인하세요.
Protobuf 클래스가 없거나 빌드 오류가 나면: 의존성/버전을 확인하고, 필요시 프로토콜 버퍼를 재생성하세요.

9. 참고 자료

GitHub: https://github.com/bareun-nlp/bareun-java
REST / gRPC API: 문서의 REST 및 gRPC 관련 페이지
설치 및 도커 가이드: 설치/도커.md 등

문서 피드백이나 예제 코드 요청이 있으면 알려 주세요. 더 구체적인 예제(토큰화, 맞춤법 검사 API, 사용자 사전 적용 등)도 추가해 드립니다.

도움이 되었나요?