bluetape4k-dependencies 사용 가이드: 여러 라이브러리 함께 사용하기

애플리케이션은 projects, exposed, aws, image, text, graph, leader, javers의 버전을 개별 관리하지 않아도 됩니다. BOM을 적용한 뒤 필요한 모듈만 선택합니다.

2026-06-28 · bluetape4k dependencies 사용 가이드

bluetape4k 라이브러리 하나만 사용한다면 의존성 구성은 단순합니다. 그러나 실제 서비스는 여러 기능 모듈을 함께 사용하는 경우가 많습니다.

예를 들어 다음과 같이 구성할 수 있습니다.

• 공통 Kotlin/JVM 도우미는 projects에서 가져옵니다.
• 데이터베이스 접근에는 exposed를 사용합니다.
• AWS 연동에는 aws를 사용합니다.
• 배치나 스케줄러는 leader로 한 노드에서만 실행하도록 제어합니다.
• 검색어와 금칙어 처리에는 text를 사용합니다.

이때 개발자의 질문은 훨씬 현실적입니다.

build.gradle.kts에는 무엇을 선언하며, 버전은 어느 범위까지 직접 관리해야 하는가?

bluetape4k-dependencies BOM을 먼저 적용하고, 개별 bluetape4k 모듈에는 버전을 선언하지 않는 것이 기본 원칙입니다.

애플리케이션은 중앙 BOM으로 기본 버전 경계를 관리합니다. 개별 모듈 버전 고정은 사유와 제거 조건을 남긴 임시 예외로 제한합니다.

Gradle에서는 BOM부터 적용한다

Kotlin DSL에서는 platform(...)으로 BOM을 가져옵니다.

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:1.4.0"))

    implementation("io.github.bluetape4k:bluetape4k-core")
    implementation("io.github.bluetape4k:bluetape4k-coroutines")
    implementation("io.github.bluetape4k.exposed:bluetape4k-exposed-jdbc")
    implementation("io.github.bluetape4k.aws:bluetape4k-aws-java")
    implementation("io.github.bluetape4k.leader:bluetape4k-leader-core")
}

여기서 중요한 줄은 첫 줄입니다.

implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:1.4.0"))

이 줄을 추가하면 아래 모듈은 버전 없이 선언합니다. 개별 버전을 다시 지정하면 BOM이 제공하는 버전 정렬 효과가 줄어듭니다.

// 개별 버전이 꼭 필요한 경우가 아니라면 피한다.
implementation("io.github.bluetape4k.exposed:bluetape4k-exposed-jdbc:1.11.0")
implementation("io.github.bluetape4k.aws:bluetape4k-aws-java:0.4.0")

dependencies 1.4.0은 내부적으로 projects 1.12.1, exposed 1.12.1, aws 0.5.0, image 0.4.0, text 0.3.0, graph 0.6.0, leader 0.5.0, javers 0.3.0 조합을 관리합니다. 애플리케이션은 개별 버전 대신 BOM 버전 하나를 선택합니다.

Maven에서는 dependencyManagement로 적용한다

Maven을 쓴다면 dependencyManagement에 BOM을 import합니다.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.bluetape4k</groupId>
            <artifactId>bluetape4k-dependencies</artifactId>
            <version>1.4.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

이후 개별 의존성에는 버전을 선언하지 않습니다.

<dependencies>
    <dependency>
        <groupId>io.github.bluetape4k</groupId>
        <artifactId>bluetape4k-core</artifactId>
    </dependency>
    <dependency>
        <groupId>io.github.bluetape4k.exposed</groupId>
        <artifactId>bluetape4k-exposed-r2dbc</artifactId>
    </dependency>
</dependencies>

Gradle과 Maven의 원칙은 동일합니다.

BOM에는 버전을 적는다.
각 bluetape4k 모듈에는 버전을 적지 않는다.

왜 모듈마다 버전을 적지 않는가

개별 모듈 버전을 직접 적으면 처음에는 더 명확합니다.

dependencies {
    implementation("io.github.bluetape4k:bluetape4k-core:1.11.0")
    implementation("io.github.bluetape4k.exposed:bluetape4k-exposed-r2dbc:1.10.0")
    implementation("io.github.bluetape4k.aws:bluetape4k-aws-spring-boot:0.4.0")
}

그러나 이 방식에서는 애플리케이션이 버전 조합을 직접 책임져야 합니다. core는 새 버전이지만 exposed는 이전 버전일 수 있고, aws가 다른 Spring Boot/Ktor 호환선을 요구할 수도 있습니다. 불일치는 컴파일 단계에서 드러나기도 하지만, 실행 중 클래스패스 오류로 나타날 수도 있습니다.

실제로 이런 종류의 문제는 겉으로는 단순합니다.

NoSuchMethodError
ClassNotFoundException
BeanCreationException
dependency resolution failed

원인을 분석하려면 애플리케이션 코드, Exposed 버전, Spring Boot 호환선, 전이 의존성 선택 결과를 차례로 확인해야 합니다.

BOM을 사용하면 최소한 bluetape4k 모듈 간 조합은 BOM이 관리합니다. 애플리케이션은 자체 코드와 서비스 고유 의존성에 집중할 수 있습니다.

기능 조합을 기준으로 모듈을 선택한다

실제 서비스에서는 필요한 기능을 기준으로 모듈을 고르는 편이 좋습니다.

필요한 기능	예시 의존성
공통 Kotlin/JVM 기반	io.github.bluetape4k:bluetape4k-core, bluetape4k-coroutines, bluetape4k-logging
Exposed JDBC/R2DBC 사용	io.github.bluetape4k.exposed:bluetape4k-exposed-jdbc, bluetape4k-exposed-r2dbc
Spring Boot에서 Exposed 사용	io.github.bluetape4k.exposed:bluetape4k-exposed-spring-boot-jdbc, bluetape4k-exposed-spring-boot-r2dbc
AWS SDK helper 사용	io.github.bluetape4k.aws:bluetape4k-aws-java, bluetape4k-aws-kotlin
Ktor/Spring Boot에서 AWS 연결	io.github.bluetape4k.aws:bluetape4k-aws-ktor, bluetape4k-aws-spring-boot
이미지 처리	io.github.bluetape4k.image:bluetape4k-images, bluetape4k-images-ocr, bluetape4k-images-vips-api
한국어/일본어 텍스트 처리	io.github.bluetape4k.text:tokenizer-korean, tokenizer-japanese, text-search, lingua
리더 선출	io.github.bluetape4k.leader:bluetape4k-leader-core, bluetape4k-leader-redis-lettuce, bluetape4k-leader-spring-boot
GraphDB 연동	io.github.bluetape4k.graph:bluetape4k-graph-core, bluetape4k-graph-neo4j, bluetape4k-graph-memgraph
audit/diff 저장	io.github.bluetape4k.javers:javers-core, javers-exposed, javers-persistence-redis

이 표에서 버전을 찾지 않아도 됩니다. 먼저 BOM을 가져왔기 때문입니다.

예를 들어 Spring Boot 서비스에서 Exposed, AWS, 리더 선출을 함께 사용한다면 다음과 같이 구성합니다.

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:1.4.0"))

    implementation("io.github.bluetape4k:bluetape4k-spring-boot-core")
    implementation("io.github.bluetape4k.exposed:bluetape4k-exposed-spring-boot-jdbc")
    implementation("io.github.bluetape4k.aws:bluetape4k-aws-spring-boot")
    implementation("io.github.bluetape4k.leader:bluetape4k-leader-spring-boot")
}

Ktor 서비스에서 AWS와 text processing을 붙인다면 이렇게 시작할 수 있습니다.

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:1.4.0"))

    implementation("io.github.bluetape4k.aws:bluetape4k-aws-ktor")
    implementation("io.github.bluetape4k.text:tokenizer-korean")
    implementation("io.github.bluetape4k.text:text-search")
}

업그레이드는 BOM 버전부터 바꾼다

기존 애플리케이션이 1.2.0을 쓰고 있다면, 먼저 BOM 버전만 올려 봅니다.

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:1.2.0"))
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:1.4.0"))

    implementation("io.github.bluetape4k:bluetape4k-core")
    implementation("io.github.bluetape4k.exposed:bluetape4k-exposed-jdbc")
}

그다음에는 사용하는 경계 중심으로 확인합니다.

./gradlew compileTestKotlin
./gradlew test
./gradlew dependencyInsight --dependency exposed --configuration runtimeClasspath
./gradlew dependencyInsight --dependency spring-boot --configuration runtimeClasspath

모든 프로젝트에서 dependencyInsight를 매번 볼 필요는 없습니다. 다만 Exposed, Spring Boot, Ktor, Jackson, AWS SDK처럼 서비스 경계에 가까운 의존성이 함께 변경되었다면 확인해야 합니다. 문제가 발생했을 때 “BOM을 올린 뒤 어떤 의존성 그래프가 되었는지”를 즉시 확인할 수 있습니다.

개별 버전 override는 예외로 관리한다

특정 모듈 버전을 임시로 고정해야 하는 경우도 있습니다. 보안 패치, 업스트림 회귀 회피, 아직 BOM에 반영되지 않은 긴급 수정이 대표적입니다.

그럴 때도 override는 예외로 두는 편이 좋습니다.

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:1.4.0"))

    implementation("io.github.bluetape4k:bluetape4k-core")

    // Temporary override: remove after the fix is included in the BOM.
    implementation("io.github.bluetape4k.text:text-search:0.3.0")
}

주석 없는 override는 실수인지 의도된 예외인지 판단하기 어렵습니다. override를 추가한다면 이유와 제거 조건을 함께 기록해야 합니다.

일반 사용자는 버전 카탈로그를 알 필요가 없다

Gradle Version Catalog는 bluetape4k 내부 저장소나 워크숍을 관리할 때 유용합니다. 별칭을 정렬하고 여러 저장소의 빌드 스크립트를 비슷한 형태로 유지하는 데 도움이 됩니다.

그러나 일반 애플리케이션 개발자가 bluetape4k-dependencies를 사용할 때 버전 카탈로그 구조를 알 필요는 없습니다. 먼저 알아야 할 것은 이 네 가지입니다.

1. io.github.bluetape4k:bluetape4k-dependencies BOM을 적용한다.
2. bluetape4k 모듈 의존성에는 버전을 선언하지 않는다.
3. 여러 bluetape4k 라이브러리를 함께 사용할수록 BOM의 이점이 커진다.
4. 예외적으로 개별 버전을 override하면 이유와 제거 조건을 남긴다.

버전 카탈로그는 bluetape4k를 개발하는 측에서 버전과 별칭을 관리하기 위한 도구입니다. 사용하는 측에서는 BOM을 적용하고 필요한 모듈을 선택하는 일이 먼저입니다.

Maven Central에 공개한 버전은 덮어쓸 수 없다

Maven Central에 공개한 릴리스 아티팩트는 같은 버전으로 다시 덮어쓸 수 없습니다.

따라서 특정 BOM 버전에 문제가 있으면 같은 번호를 수정해 다시 게시하지 않습니다. 1.3.0에 문제가 있다면 1.3.1과 같은 새 패치 버전으로 수정합니다.

이미 공개된 BOM 버전이 이상하다
  -> 같은 버전을 다시 기다리지 말고
  -> 패치 BOM 버전이 나오는지 확인한다

전체 배포 절차를 알 필요는 없지만, 같은 버전을 다시 게시하지 못한다는 불변식은 업그레이드 판단에 필요합니다.

다음에 읽을 글

여기까지가 bluetape4k-dependencies를 사용하는 개발자 관점의 기본 사용법입니다. 1.2.0에서 1.3.x로 올렸을 때 각 라이브러리에서 보강된 기능과 수정된 결함은 다음 글에서 확인할 수 있습니다.

• bluetape4k-dependencies 1.3.0 활용기 Part 1: 기능 보강과 경계 정리
• bluetape4k-dependencies 1.3.0 활용기 Part 2: 서비스 경계에 맞는 모듈 조합
• bluetape4k-dependencies 1.3.0 활용기 Part 3: 운영에서 드러나는 신호
• bluetape4k-dependencies 1.3.0 활용기 Part 4: 입력 경계와 자원 안전성

자료

• bluetape4k-dependencies README.ko.md
• bluetape4k-dependencies CHANGELOG.md
• bluetape4k-dependencies libs.versions.toml