Spring Boot에서 공식 Java SDK로 Claude API를 호출하는 최소 구현

이 기사에 대하여

대상 독자: Spring Boot / Java 기초가 있으며, 앱에 AI (Claude)를 통합해 보고 싶은 사람 -
얻을 수 있는 것: Anthropic 공식 Java SDK를 사용하여, Spring Boot에서 Claude API를 호출하는 최소 구성 (의존성·설정·서비스)을 만들 수 있음 -
전제·환경: Java 21 / Spring Boot 3.5 / com.anthropic:anthropic-java 2.34.0 / Lombok / Anthropic API 키

샘플은 "프롬프트를 전달하면 텍스트를 얻을 수 있는" 최소한의 형태에 집중하고 있습니다. 채팅이나 요약 등 용도에 맞춰 확장해 보세요.

버전 (SDK·Spring Boot) 및 모델명은 집필 시점 (2026년 6월) 기준입니다. 대응 모델이나 SDK는 업데이트되므로, 최신 정보는 공식 정보를 통해 확인해 주세요.

결론 (먼저 전체상 파악)

공식 Java SDK를 하나 추가하고, AnthropicClient를 Bean으로 등록하면, 나머지는 client.messages().create(...)를 호출하기만 하면 됩니다.

var params = MessageCreateParams.builder()
.model("claude-opus-4-8")
.maxTokens(1024)
...

여기서부터 설정의 외부화, 키 처리, 응답 추출까지 순차적으로 만들어 가겠습니다.

단계 1: 의존성 추가하기

프로젝트에 의존성을 추가합니다. 공식 Java SDK 본체에 더해, 설정값 검증용으로 spring-boot-starter-validation을 넣습니다. 또한 보일러플레이트 (Boilerplate) 코드를 줄이기 위해 Lombok (@RequiredArgsConstructor / @Slf4j)도 사용합니다.

dependencies {
implementation("org.springframework.boot:spring-boot-starter-web")
implementation("org.springframework.boot:spring-boot-starter-validation")
...

Maven의 경우:

<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
...

단계 2: API 키 처리와 클라이언트의 Bean화

SDK에는 AnthropicOkHttpClient.fromEnv()라는 편리한 메서드가 있습니다. 하지만 이것은 System.getenv()를 직접 읽기 때문에, Spring의 Environment를 참조하지 않습니다. spring.config.import로 읽어온 .env도 대상에서 제외됩니다. 따라서 @Value를 사용하여 Spring을 통해 키를 해결하면, 운영 환경의 OS 환경 변수와 개발 시의 .env 모두에서 동일한 코드로 읽을 수 있습니다.

@Configuration
public class AnthropicClientConfig {
@Bean
...

개발 시 .env에서 읽는다면, application.yaml에 다음과 같이 작성해 둡니다 (운영 환경에서는 OS 환경 변수가 직접 사용되므로 optional 처리).

spring:
  config:
    import: optional:file:.env[.properties]

.env나 API 키는 커밋하지 마세요. .gitignore에 .env를 넣어 둡니다.

단계 3: 모델과 max_tokens를 설정으로 외부화하기

모델명이나 max_tokens는 코드에 직접 쓰지 않고 설정으로 빼두면 전환이 쉽습니다. record + @ConfigurationProperties 조합이 간결합니다.

@ConfigurationProperties(prefix = "anthropic")
@Validated
public record AnthropicProperties(
...

이 record를 Bean으로 만들려면 등록이 필요합니다. 단계 2의 AnthropicClientConfig

에 @EnableConfigurationProperties를 추가하여 활성화합니다. 실행 클래스(Startup class)에 @ConfigurationPropertiesScan을 붙이는 방법도 가능합니다.

@Configuration
@EnableConfigurationProperties(AnthropicProperties.class) // ← 이 한 줄을 추가
public class AnthropicClientConfig {
...

anthropic:
  model: claude-opus-4-8
  max-tokens: 1024

max-tokens (케밥 케이스(kebab-case))가 maxTokens에 대응합니다 (Spring의 릴랙스드 바인딩 (Relaxed Binding)). 용도에 따라 모델은 교체 가능하며, 고빈도·저지연 (low latency)을 중시한다면 claude-haiku-4-5와 같은 경량 모델이 적합합니다.

단계 4: 호출하여 응답에서 텍스트 추출하기

응답의 content()는 여러 블록의 배열입니다. 텍스트 블록만 추출하여 연결합니다.

@Service
@RequiredArgsConstructor
@Slf4j
...

response.usage() (입출력 토큰 수)나 response.stopReason()도 가져올 수 있으므로, 로그에 남겨두면 운영 시 유용합니다.

주의 사항 및 해결 방법

구현 시 막히기 쉬운 부분은 API 키 해결과 응답 추출 관련 부분입니다. 대표적인 3가지 포인트와 회피 방법을 나열합니다.

• fromEnv()로 키를 읽을 수 없음: fromEnv()는 System.getenv()를 직접 읽습니다. .env 파일을 spring.config.import로 읽더라도 인식하지 못합니다. @Value("${ANTHROPIC_API_KEY}")를 사용하여 Spring을 통해 해결할 수 있습니다 (단계 2).
• 빈 응답이 반환됨: content()에 텍스트 블록이 없거나, stopReason이 예상과 다른 경우가 있습니다. 빈 값 체크를 넣고, stopReason을 로그에 출력하여 원인을 파악합니다.
• 예외 타입: API 호출 실패는 com.anthropic.errors.AnthropicException으로 잡을 수 있습니다. 애플리케이션 측의 예외로 감싸서 처리하면 레이어(layer)를 정리할 수 있습니다.

요약

• 공식 Java SDK (com.anthropic:anthropic-java)를 추가하고 AnthropicClient를 Bean으로 만들면 Spring Boot에서 Claude API를 호출할 수 있습니다.
• 키는 @Value를 통해 Spring을 거쳐 해결하면, 운영 환경의 OS 환경 변수와 개발 시의 .env 모두에서 동작합니다.
• 모델 및 max_tokens는 설정으로 분리하고, 응답은 텍스트 블록을 연결하여 추출합니다.

여기서는 '호출'하는 최소한의 형태에 집중했지만, 사양 정의부터 구현·테스트·배포까지를 Claude Code와 일관되게 진행하는 흐름은 제 저서에 정리해 두었습니다. Spring Security / JPA / Flyway 및 운영 배포 (Railway)까지, AI와 대화하며 하나의 웹 애플리케이션을 완성하는 구성입니다.

📘 『Claude Code와 함께 만드는 Spring Boot 실전 개발 AI 일기 앱을 사양 정의부터 배포까지』

• BOOTH (전자·PDF): https://propagandist.booth.pm/items/8536937

Discussion