Skip to content
TungDaDev's Blog

Multi-module Spring Boot với Gradle: bỏ subprojects, sửa lỗi bootJar

Multi modules gradle.webp
Published on
12 mins read

Vừa tách module common ra cho gọn, chạy ./gradlew build thì nhận ngay Main class name has not been configured. Sửa xong lỗi đó, lại thấy đổi một dòng trong common là cả cây module compile lại từ đầu.

Hệ thống backend lớn thì gần như chắc chắn phải tách code thành nhiều module (Multi-Project Builds), để đóng gói cho gọn, ranh giới domain rõ ràng và chia việc cho nhiều team. Có điều tách sai cách thì Gradle phạt khá nặng.

Giữa Maven và Gradle, mình thấy Gradle hợp hơn với dự án phức tạp nhờ build nhanh (Incremental Build, Compile Avoidance, Build Cache) và tùy biến linh hoạt bằng Kotlin DSL / Groovy.

Vấn đề là nhiều hướng dẫn hiện giờ vẫn chỉ cách dùng Gradle kiểu cũ từ 10 năm trước:

  • Lạm dụng khối allprojects {} và subprojects {}, khiến các project dính chặt vào nhau và chặn đường tới các tối ưu mới của Gradle (configuration on demand, Isolated Projects).
  • Dùng compile (đã bị gỡ) thay vì phân biệt api và implementation.
  • Module thư viện con lỡ apply plugin Spring Boot rồi vấp lỗi ở task bootJar.
  • Hardcode version thư viện rải rác khắp nơi thay vì dùng Gradle Version Catalog (libs.versions.toml).

Ví dụ trong bài dùng Gradle 8.x và Spring Boot 3.x. (Gradle 9 và Spring Boot 4 đã ra từ năm 2025; các ý chính trong bài vẫn giữ nguyên, chỉ cần nâng version trong catalog.)


# tại sao subprojects {} bị coi là anti-pattern?

Gradle kiểu cũ thường nhét hết cấu hình chung vào subprojects {} ở file build.gradle gốc:

// 🔴 MÔ HÌNH LỖI THỜI CẦN LOẠI BỎ:
subprojects {
    apply plugin: 'org.springframework.boot'
    apply plugin: 'io.spring.dependency-management'
    // Ép mọi module con phải nhận chung toàn bộ cấu hình!
}

# vì sao Gradle khuyến nghị bỏ subprojects?

  1. Cross-Project Configuration: cấu hình từ module cha "bắn" ngầm vào module con nên mất tính minh bạch. Mở build.gradle của module con ra, bạn không biết dependencies hay compiler flags nào đang thực sự được áp dụng.
  2. Chặn đường tối ưu của Gradle: Gradle đang hướng tới chế độ Isolated Projects, trong đó mỗi project được cấu hình độc lập, song song và cache riêng. Cấu hình chéo kiểu subprojects {} (project cha với tay vào sửa project con) vi phạm đúng điều kiện đó, nên Gradle phải cấu hình cả cây project cùng lúc, project càng nhiều càng chậm. Configuration cache thông thường vẫn chạy được, nhưng mỗi lần đổi file build gốc là toàn bộ cấu hình bị tính lại.
  3. Lẫn framework vào module không cần: một module core-domain thuần (Pure POJO) chỉ cần Java chuẩn mà vẫn bị subprojects ép nạp plugin Spring Boot.

Hướng thay thế chuẩn hiện nay (như nửa dưới sơ đồ trên) là viết Convention Plugins đặt trong thư mục buildSrc hoặc một composite build riêng tên build-logic (includeBuild("build-logic")). Thay vì đứng từ file gốc ép xuống, bạn đóng gói các cấu hình chung thành từng plugin có tên rõ ràng (như company.java-library chỉ lo cấu hình Java và test, còn company.spring-service mới kéo thêm Spring Boot). Module nào cần vai trò gì thì tự khai báo tường minh trong plugins {} của chính nó: vừa tái sử dụng được cấu hình không phải copy-paste, vừa giữ các module hoàn toàn độc lập để Gradle chạy song song.


# compile avoidance: api vs implementation

Plugin java-library tách compile cũ thành hai chế độ khai báo dependency:

# khác nhau ở đâu

  • implementation (nên dùng cho đa số trường hợp): thư viện chỉ dùng nội bộ trong module và không lộ ra Application Binary Interface (ABI). Module C phụ thuộc B sẽ không thấy A trên compile classpath, nên khi ABI của A đổi thì chỉ B phải biên dịch lại, C thì không. Thêm một cái lợi: C không thể vô tình import class của A.

    Còn nếu A chỉ đổi phần bên trong (thân method, field private) mà không đổi ABI, thì Gradle bỏ qua biên dịch lại các module phía trên bất kể dùng api hay implementation, vì nó so ABI chứ không so file. Đó mới là Compile Avoidance. Mức tiết kiệm thời gian build tuỳ hình dạng cây module, không có con số chung.

  • api: dùng khi kiểu dữ liệu của thư viện xuất hiện trực tiếp trên method public của module hiện tại (ví dụ return type hoặc parameter). Module nào phụ thuộc vào module này cũng thấy và dùng được thư viện đó.


# quản lý phụ thuộc tập trung với Gradle version catalog

Thay vì khai báo version rải rác bằng biến ext {} dễ xung đột, từ Gradle 7.4+ có Version Catalog qua file gradle/libs.versions.toml (các version dưới đây là ở thời điểm viết bài):

# gradle/libs.versions.toml
[versions]
springBoot = "3.3.4"
springDependencyManagement = "1.1.6"
lombok = "1.18.34"
mapstruct = "1.5.5.Final"
postgresql = "42.7.4"
 
[libraries]
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" }
spring-boot-starter-data-jpa = { module = "org.springframework.boot:spring-boot-starter-data-jpa" }
spring-boot-starter-validation = { module = "org.springframework.boot:spring-boot-starter-validation" }
spring-boot-starter-actuator = { module = "org.springframework.boot:spring-boot-starter-actuator" }
postgresql = { module = "org.postgresql:postgresql", version.ref = "postgresql" }
lombok = { module = "org.projectlombok:lombok", version.ref = "lombok" }
mapstruct = { module = "org.mapstruct:mapstruct", version.ref = "mapstruct" }
 
[bundles]
web-stack = ["spring-boot-starter-web", "spring-boot-starter-validation"]
 
[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "springBoot" }
spring-dependency-management = { id = "io.spring.dependency-management", version.ref = "springDependencyManagement" }

# lợi ích của version catalog

Đưa toàn bộ khai báo về libs.versions.toml giải quyết được ba nỗi khổ lớn khi quản lý nhiều module. Trước hết là Type-Safe Accessors: Gradle tự sinh code để IDE gợi ý và kiểm tra kiểu ngay lúc gõ (ví dụ libs.spring.boot.starter.web), chấm dứt cảnh gõ sai một ký tự trong chuỗi string mà tới lúc chạy build mới báo lỗi. Tiếp đó, file .toml đóng vai trò Single Source of Truth, khi cần vá bảo mật hay nâng cấp thư viện cho cả chục module con thì bạn chỉ sửa đúng một dòng trong mục [versions]. Ngoài ra, cơ chế Bundles cho phép gom các thư viện luôn đi cặp với nhau (như web và validation) thành một nhóm để các module gọi gọn bằng một dòng implementation(libs.bundles.web.stack).

Các starter của Spring Boot không ghi version trong catalog vì version do plugin io.spring.dependency-management (đọc BOM của Spring Boot) quyết định. Catalog chỉ khai báo "có thư viện này", không tự áp version cho dependency bắc cầu như BOM.


# xung đột bootjar vs jar

Lỗi kinh điển khi mới làm Spring Boot Multi-Module, ai cũng từng vò đầu một lần:

Execution failed for task ':common:bootJar'.
> Error while evaluating property 'mainClass' of task ':common:bootJar'.
   > Failed to calculate the value of task ':common:bootJar' property 'mainClass'.
      > Main class name has not been configured and it could not be resolved from classpath

# nguyên nhân

Khi apply plugin org.springframework.boot lên một module con, Spring Boot sẽ:

  1. Bật task bootJar: đóng gói ứng dụng thành "Fat JAR" có loader riêng của Spring, để chạy độc lập (java -jar). Task này cần một class có main; module thư viện thì không có, nên ./gradlew build lỗi như trên.
  2. Đổi tên JAR thường: từ Spring Boot 2.5, task jar vẫn chạy nhưng file ra có hậu tố -plain để khỏi đè lên fat JAR. (Ở Spring Boot 2.0–2.4, task jar bị tắt hẳn khi có bootJar, nên ngày đó tắt bootJar xong còn phải bật lại jar.)
  3. Module khác vẫn dùng được: khi một module khác khai báo implementation project(':common'), Gradle lấy output của task jar (bản plain) chứ không lấy fat JAR. Rắc rối thật sự chỉ là bootJar đòi main class, cộng thêm việc build ra một fat JAR vô dụng.

# cấu hình cho module thư viện (common/build.gradle)

// Tắt task đóng gói Fat JAR thực thi
bootJar {
    enabled = false
}
 
// Bắt buộc bật lại task sinh JAR Java tiêu chuẩn cho các module khác import!
jar {
    enabled = true
    archiveClassifier = '' // Đảm bảo tên file jar không bị đính kèm hậu tố lạ
}

Cách gọn hơn nữa là đừng apply plugin org.springframework.boot cho module thư viện. Module đó chỉ cần quản lý version, nên apply io.spring.dependency-management và import BOM của Spring Boot (mavenBom(SpringBootPlugin.BOM_COORDINATES)), hoặc dùng implementation(platform(...spring-boot-dependencies...)). Tài liệu Spring Boot Gradle plugin gọi cách này là dùng dependency management "in isolation".


# cấu trúc dự án mẫu

Lấy ví dụ một hệ thống E-Commerce Modular Monolith:

my-enterprise-app/
├── gradle/
│   └── libs.versions.toml        # Danh mục quản lý phiên bản tập trung
├── settings.gradle.kts           # Định nghĩa cấu trúc phân tầng modules
├── build.gradle.kts              # Root config tinh giản
├── domain/                       # Pure Java POJO (Zero Frameworks)
│   └── build.gradle.kts
├── infrastructure/
│   ├── persistence/              # JPA, PostgreSQL, HikariCP
│   │   └── build.gradle.kts
│   └── messaging/                # Kafka, RabbitMQ
│       └── build.gradle.kts
└── application/                  # Deployable Spring Boot Main Application
    └── build.gradle.kts

# settings.gradle.kts (bật type-safe accessors)

rootProject.name = "my-enterprise-app"
 
// Khai báo rõ ràng từng module con
include(":domain")
include(":infrastructure:persistence")
include(":infrastructure:messaging")
include(":application")
 
// Bật tính năng Type-Safe Project Accessors
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")

# domain/build.gradle.kts (module nghiệp vụ thuần)

plugins {
    `java-library` // Sử dụng java-library để hỗ trợ api/implementation
}
 
dependencies {
    // KHÔNG import Spring Boot Starter! Domain phải độc lập tuyệt đối với Framework!
    compileOnly(libs.lombok)
    annotationProcessor(libs.lombok)
 
    testImplementation(platform("org.junit:junit-bom:5.10.3"))
    testImplementation("org.junit.jupiter:junit-jupiter")
}

# infrastructure/persistence/build.gradle.kts

plugins {
    `java-library`
    alias(libs.plugins.spring.boot)
    alias(libs.plugins.spring.dependency.management)
}
 
// Module hạ tầng là thư viện, không tạo file bootJar runnable
// (hoặc bỏ hẳn plugin spring.boot, chỉ giữ dependency management như đã nói ở trên)
tasks.bootJar { enabled = false }
tasks.jar { enabled = true }
 
dependencies {
    // Phụ thuộc vào domain bằng Type-Safe Accessor
    api(projects.domain)
 
    implementation(libs.spring.boot.starter.data.jpa)
    runtimeOnly(libs.postgresql)
 
    compileOnly(libs.lombok)
    annotationProcessor(libs.lombok)
}

# application/build.gradle.kts (deployable host)

plugins {
    application
    alias(libs.plugins.spring.boot)
    alias(libs.plugins.spring.dependency.management)
}
 
// Đây là module duy nhất sinh ra file jar thực thi trên Production!
tasks.bootJar { enabled = true }
tasks.jar { enabled = false }
 
dependencies {
    implementation(projects.domain)
    implementation(projects.infrastructure.persistence)
    implementation(projects.infrastructure.messaging)
 
    implementation(libs.bundles.web.stack)
    implementation(libs.spring.boot.starter.actuator)
}

Một chi tiết dễ vấp: khi nhiều module cùng alias(libs.plugins.spring.boot), nên khai báo plugin đó một lần ở build.gradle.kts gốc với apply false (plugins { alias(libs.plugins.spring.boot) apply false }). Như vậy plugin chỉ được nạp vào một classloader chung, tránh các lỗi khó hiểu khi các module con nạp plugin riêng rẽ.


# bảng so sánh

Tiêu chíCấu hình Cổ Điển (Legacy Groovy)Chuẩn Enterprise Hiện Đại (Kotlin DSL)
Quản lý Phiên bảnRải rác biến ext {} khắp các fileTập trung trong libs.versions.toml
Kế thừa Cấu hìnhsubprojects {} / allprojects {}Convention Plugins hoặc cấu hình tường minh
Phân phối Phụ thuộccompile (đã bị xóa bỏ)api vs implementation (Compile Avoidance)
Kiểm soát ArtifactDễ lỗi mất JAR do xung đột bootJarTường minh: Runnable (bootJar) vs Library (jar)
Tốc độ BuildChậm, hay re-compile cả cây moduleNhanh hơn nhờ Build Cache và ABI check

# tổng kết

Có sẵn một dự án multi-module cũ thì không cần đập đi làm lại. Bốn việc, làm theo thứ tự, mỗi việc một PR:

  1. Tìm mọi module thư viện đang apply plugin org.springframework.boot, tắt bootJar hoặc bỏ hẳn plugin ở đó. Lỗi build biến mất ngay.
  2. Đưa version thư viện về libs.versions.toml. Việc này máy móc, ít rủi ro, làm sớm cho đỡ xung đột về sau.
  3. Rà các khai báo api: cái nào không lộ ra public API của module thì hạ xuống implementation để Compile Avoidance có đất làm việc.
  4. Cuối cùng mới gỡ subprojects {} ở file gốc, chuyển phần cấu hình chung sang convention plugin hoặc khai báo tường minh trong từng module.

Xong bước 1 và 3, thử đổi một dòng trong domain rồi build lại, so số task chạy với trước đó là thấy khác biệt.


Chỉ là những ghi chép cá nhân với hy vọng mang lại chút giá trị. Nếu thấy hữu ích, đừng ngại chia sẻ cho bạn bè & đồng nghiệp nhé!

Happy coding 😎 👍🏻 🚀 🔥.