[Build/Compatibility] 0.1.0 Java·Spring Boot·Spring AI 지원 기준 확정

[HuitaePark]

배경

0.1.0의 Spring adapter를 구현하기 전에 실제 지원 조합을 고정해야 한다.

현재 저장소에서 확인된 baseline은 다음과 같다.

• Java toolchain: 25
• Spring Boot plugin/BOM: 4.0.5
• Spring AI BOM: 1.1.4
• Core JAR은 Java 25 bytecode로 생성된다.
• 루트 dependency management가 모든 subproject에 적용되어 Core의 generated POM에도 Spring BOM metadata가 들어갈 수 있다.

Spring AI 공식 compatibility 기준에서 1.1.x는 Spring Boot 3.5.x 계열, Spring AI 2.x는 Spring Boot 4.x 계열이다. 현재 Boot 4.0.5 + Spring AI 1.1.4 조합은 0.1.0 지원 조합으로 검증·합의되지 않았다.

목표

TokenPilot 0.1.0이 지원하는 최소 JDK, target bytecode, Spring Boot와 Spring AI 조합을 하나의 검증 가능한 matrix로 확정하고 CI와 publication metadata에 고정한다.

결정해야 할 기준

30일 MVP에서는 복수 조합을 동시에 지원하지 않는다. compatibility spike에서 아래 중 하나를 선택하고 이슈를 열린 선택지 없이 닫는다.

1. Spring Boot 3.5.x + Spring AI 1.1.x
2. Spring Boot 4.x + Spring AI 2.x

현재 adapter가 Spring AI 1.1.4를 기준으로 구현되어 있으므로 첫 번째 조합을 우선 검증하되, 실제 compile/test 결과로 확정한다.

최소 소비자 JDK는 LTS를 기준으로 결정하고, toolchain JDK와 공개 bytecode target을 분리한다. 권장 baseline은 JDK 21 target이다.

구현 범위

Java 기준

• 최소 지원 JDK와 개발 toolchain JDK를 문서화한다.
• options.release 또는 동등 설정으로 공개 artifact의 target bytecode를 고정한다.
• 최소 JDK에서 Core-only consumer가 load/compile/run되는지 검증한다.
• 더 높은 toolchain에서 빌드해도 최소 target을 초과하지 않는 구조 검사를 추가한다.

Spring Boot / Spring AI 기준

• 정확한 지원 version 또는 허용 patch range를 version catalog/BOM에 고정한다.
• selected matrix에서 전체 module test와 fake ChatModel E2E를 실행한다.
• Spring AI Advisor lifecycle과 usage API capability를 source/bytecode 기반으로 검증한다.
• 0.1.0에서 지원하지 않는 조합은 문서에 명시한다.
• #39는 이 이슈의 확정 matrix만 소비하고 자체적으로 다른 조합을 추정하지 않는다.

Core publication isolation

Core의 runtime graph뿐 아니라 generated POM과 Gradle module metadata도 검사한다.

다음 항목이 token-pilot-core의 dependency 또는 dependencyManagement에 없어야 한다.

• Spring AI
• Spring Boot
• Micrometer
• Reactor
• Spring Boot/Spring AI BOM import

Root 공통 설정이 framework BOM을 모든 subproject에 주입하지 않도록 publication 구성을 분리한다.

CI matrix

최소 다음 소비자 검증을 둔다.

• Core-only + 최소 JDK
• Starter + 선택한 Spring Boot/Spring AI/JDK 조합
• generated Core POM/module metadata 구조 검사
• dependency convergence와 duplicate class 검사

Acceptance criteria

• 0.1.0의 최소 JDK와 target bytecode가 숫자로 확정된다.
• 지원 Spring Boot/Spring AI 조합이 정확히 하나로 확정된다.
• 공식 compatibility 근거와 실제 spike 결과를 함께 기록한다.
• 최소 JDK Core consumer가 compile·run된다.
• Starter fake-provider E2E가 선택한 조합에서 통과한다.
• Core generated POM/module metadata에 Spring 계열 BOM·dependency가 없다.
• 지원하지 않는 조합과 streaming 제한을 README/configuration에 명시한다.
• [Spring AI] Request/Usage Adapter와 Advisor E2E 연결 #39, [Distribution] Core와 token-pilot-starter 0.1.0 동일 버전 배포 구성 #41, #42가 이 이슈를 선행 조건으로 사용한다.

제외 범위

• Spring AI 1.x와 2.x 동시 지원
• 모든 patch/minor 조합 matrix
• 실제 provider별 호환성
• native image와 Android
• Maven Central 실제 배포

검증 명령 예시

./gradlew clean build
./gradlew generatePomFileForMavenJavaPublication
# 최소 JDK로 격리된 Core consumer verify
# 선택한 Boot/AI 조합의 Starter consumer verify

공식 근거

• Spring AI Getting Started
• Spring AI repository compatibility matrix