bluetape4k-dependencies 2.0.0 활용기 Part 1: Java 25와 호환성 경계

중앙 BOM 보드에서 호환성, 데이터, 메시징, 운영 안전성 작업대로 경로가 갈라지는 3D 미니어처 작업실 — 하나의 BOM 변경은 JVM 기준선, 바이너리 패키지, 빌드 도구, 설정, 컨테이너 이미지 계약을 함께 움직입니다.

2026-09-06 · bluetape4k-dependencies 2.0.0 활용기 · Part 1

bluetape4k-dependencies 2.0.0은 여러 라이브러리의 안정판을 하나의 검증된 조합으로 선택합니다. 그렇다고 BOM이 Java 런타임이나 애플리케이션 코드를 대신 마이그레이션해 주는 것은 아닙니다. 버전 한 줄을 올리기 전에 호환성 경계를 먼저 확인해야 합니다.

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:2.0.0"))
    implementation("io.github.bluetape4k:bluetape4k-core")
}

업그레이드 전에 답할 질문

다음 중 하나라도 해당하면 단순한 의존성 갱신으로 끝나지 않습니다.

서비스 런타임이 Java 21–24인가?
bluetape4k-virtualthread-api 타입을 직접 import하거나 바이너리 API에 노출했는가?
QueryDSL Q 타입을 Kotlin 소스에서 생성하는가?
Spring Boot MongoDB 연결을 spring.data.mongodb.uri로 설정했는가?
Testcontainers에서 사용자 지정 Ignite2 이미지의 태그를 생략했는가?

2.0.0은 이런 차이를 대체 동작으로 숨기지 않습니다. 빌드 또는 시작 단계에서 빨리 드러내는 쪽을 선택합니다.

2.0.0이 선택한 릴리스

중앙 2.0.0 릴리스는 다음 주요 안정판을 하나의 카탈로그에 고정합니다.

라이브러리	버전
`bluetape4k-projects`	`2.0.0`
`bluetape4k-exposed`	`2.0.0`
`bluetape4k-aws`	`1.0.0`
`bluetape4k-image`	`1.0.0`
`bluetape4k-text`	`1.0.0`
`bluetape4k-graph`	`1.0.0`
`bluetape4k-javers`	`1.0.0`
`bluetape4k-leader`	`1.0.0`

이 카탈로그는 Kotlin 2.4.10, Spring Boot 4.1.0, Exposed 1.4.0도 선택합니다. 이 숫자를 “새 기능 목록”으로 읽기보다, 함께 빌드하고 검증한 호환성 계열로 읽는 편이 정확합니다. 개별 기능의 근거는 각 라이브러리의 릴리스 소스와 테스트입니다.

Java 25 기준선과 Java 21 호환 영역

bluetape4k-projects 2.0.0은 일반 배포 아티팩트의 런타임 기준선을 Java 25로 올렸습니다. Java 21 호환 영역은 다음 다섯 아티팩트로 제한됩니다.

bluetape4k-assertions
bluetape4k-junit5
bluetape4k-logging
bluetape4k-virtualthread-api
bluetape4k-virtualthread-jdk21

따라서 “일부 아티팩트가 Java 21에서 동작한다”와 “2.0.0 전체가 Java 21을 지원한다”는 같은 말이 아닙니다. Java 21–24를 유지해야 하는 애플리케이션은 사용하는 아티팩트가 이 영역 안에 있는지 확인하고, 그렇지 않다면 Java 25로 이동하거나 1.13.x 계열을 유지해야 합니다. 이 결정은 Java 기준선 이슈에 기록돼 있습니다.

컴파일과 설정에서 드러나는 마이그레이션

virtual-thread API는 import 수정과 재컴파일이 필요하다

Java 21 호환 API 타입은 io.bluetape4k.concurrent.virtualthread.api 패키지로 이동했습니다.

import io.bluetape4k.concurrent.virtualthread.api.StructuredTaskScopes
import io.bluetape4k.concurrent.virtualthread.api.VirtualThreads

val executor = VirtualThreads.executorService()
val value = StructuredTaskScopes.failFast { scope ->
    val task = scope.fork { loadValue() }
    scope.join().throwIfFailed()
    task.get()
}

이전 패키지의 타입을 소스나 공개 시그니처에서 사용했다면 BOM만 바꿔서는 해결되지 않습니다. import를 고치고 사용 코드를 재컴파일해야 합니다. core와 virtualthread-api JAR가 같은 패키지를 나누어 소유하지 않도록 정리한 바이너리 소유권 변경이기 때문입니다.

QueryDSL Kotlin codegen은 기본 경로에서 빠졌다

Kotlin 2.4와 JDK 25 조합에서 QueryDSL Kotlin annotation processing이 upstream NullPointerException을 내므로 Kotlin codegen은 기본 지원 경로에서 제외됐습니다. Java APT로 생성한 Q 타입과 연관 관계 쿼리는 유지됩니다. Kotlin Q 타입 생성에 의존한다면 클린 빌드에서 생성 소스와 컴파일러 태스크를 먼저 확인해야 합니다. 자세한 결정은 QueryDSL issue에 있습니다.

MongoDB 설정 키가 바뀌었다

Spring Boot 4.1에서는 다음처럼 옮깁니다.

spring:
  mongodb:
    uri: mongodb://localhost:27017/app

레거시 spring.data.mongodb.uri만 남기면 localhost 기본값으로 조용히 연결하지 않고 다음 오류와 함께 시작이 중단됩니다.

Unsupported legacy MongoDB property 'spring.data.mongodb.uri'; use 'spring.mongodb.uri' on Spring Boot 4.1+

두 키가 함께 있으면 새 키가 우선합니다. 즉시 바꿀 수 없다면 레거시 네임스페이스를 지원하는 이전 아티팩트를 임시로 고정해야 합니다. MongoDB 마이그레이션 이슈가 이 경계를 고정합니다.

실패를 앞당기는 시작 경계

사용자 지정 Ignite2 이미지에는 명시적인 태그가 필요합니다.

val ignite = Ignite2Server(
    image = "custom/ignite",
    tag = "2.18.0-company.3",
)

Ignite2Server(image = "custom/ignite")처럼 태그를 생략하면 Custom Ignite2 image requires an explicit tag로 실패합니다. DockerImageName 경로도 사용자 지정 이미지에 latest를 암묵적으로 적용하지 않습니다. 지원하지 않는 CPU 아키텍처에서 canonical 태그를 생략한 경우도 즉시 실패합니다. 운영자가 검증하지 않은 이미지가 우연히 선택되는 것보다 시작 단계에서 실패하는 편이 안전하다는 판단입니다. 세부 계약은 Ignite2 마이그레이션 이슈에서 확인할 수 있습니다.

적용 체크리스트

java -version과 배포 이미지의 JRE를 Java 25 기준으로 확인합니다.
Java 21 호환 영역만 사용한다면 실제 런타임 classpath가 다섯 아티팩트로만 구성되는지 검사합니다.
io.bluetape4k.concurrent.virtualthread의 이전 API import를 검색하고 재컴파일합니다.
QueryDSL 생성 소스가 Java APT 경로에서 만들어지는지 클린 빌드로 확인합니다.
MongoDB 키를 옮기고 레거시 설정만 남은 경우 시작 단계에서 실패하는지 환경별로 점검합니다.
모든 사용자 지정 컨테이너 이미지에 digest 또는 명시적 태그를 둡니다.

BOM은 호환 가능한 출발점을 제공합니다. 실제 마이그레이션의 완료 조건은 애플리케이션의 컴파일, 시작, 런타임 검증입니다.

자료

시리즈 글

GitHub 계정으로 의견을 남기거나 reaction을 남길 수 있습니다.