Spring Boot Starters: Những Kẻ Thay Đổi Cuộc Chơi Được Giải Thích

Spring Boot Starters không phải thư viện bạn import vào code. Chúng là những POM mỏng: một danh sách dependency đã được kiểm chứng với nhau, cộng với auto-configuration được đăng ký qua AutoConfiguration.imports. Hiểu hai phần đó giải thích vì sao cùng một starter có thể dựng ứng dụng trong ba phút, hoặc làm nó chết ngay lúc khởi động.

Bài viết dùng Spring Boot 4.1.2, Spring Framework 7.0.10 và Java 25 LTS; các starter bên dưới đã được đối chiếu với POM trên Maven Central.

Cập nhật 2026

  • Starter web đổi tên. Boot 4.1 deprecate spring-boot-starter-web để chuyển sang spring-boot-starter-webmvc. POM cũ vẫn resolve và vẫn chạy, nhưng code mới nên dùng tên mới.
  • Không còn spring-boot-starter-aop. Artifact này không tồn tại ở 4.1.2 (và cả 4.0.9); thay bằng spring-boot-starter-aspectj, kéo aspectjweaver 1.9.25.1 và spring-aop 7.0.10.
  • Modularization đổi package auto-configuration. Boot 4 tách jar theo công nghệ. DataSourceAutoConfiguration giờ ở org.springframework.boot.jdbc.autoconfigure, WebMvcAutoConfiguration ở org.springframework.boot.webmvc.autoconfigure. Chuỗi FQN trong spring.autoconfigure.exclude của dự án cũ có thể đã sai.

Một starter gồm hai thứ, không phải một

Mở POM của spring-boot-starter-webmvc 4.1.2, bạn thấy đúng năm dependency và không có một dòng code nào:

<!-- File: spring-boot-starter-webmvc-4.1.2.pom -->
<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jackson</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-tomcat</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-http-converter</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-webmvc</artifactId>
  </dependency>
</dependencies>

Không dependency nào ghi version. Starter không biết bạn dùng Boot nào, nên việc điền version thuộc về BOM ở phía dự án tiêu thụ. Phần thứ hai — thứ thực sự tạo ra hành vi — nằm trong module spring-boot-webmvc: các lớp @AutoConfiguration được liệt kê trong một file text.

Khi build, Boot đọc file META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports của mọi jar trên classpath. Mỗi dòng không phải comment là một FQN. Với mỗi lớp, các điều kiện như @ConditionalOnClass được đánh giá; khớp thì bean được đăng ký, không khớp thì bỏ qua im lặng. Đó là lý do starter không cần annotation, không cần cấu hình: chỉ cần có mặt trên classpath.

Hệ quả cần nhớ: starter không thêm API cho code của bạn. Nếu bạn cần gọi trực tiếp một class của thư viện, class đó đến từ dependency mà starter kéo theo, không phải từ starter. Bản thân jar starter gần như rỗng.

Vì sao bạn không ghi version

spring-boot-dependencies là một POM chỉ chứa dependencyManagement: một bảng version đã được test cùng nhau cho toàn bộ hệ sinh thái. spring-boot-starter-parent kế thừa chính POM đó, rồi bổ sung cấu hình plugin, encoding và resource filtering.

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>4.1.2</version>
  <relativePath/>
</parent>

Nếu tổ chức đã có parent riêng, đừng chèn thêm starter-parent vào giữa. Hãy import BOM trực tiếp; bạn chỉ mất phần plugin management và phải tự cấu hình spring-boot-maven-plugin:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>4.1.2</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Với Gradle không có khái niệm starter-parent; dùng platform:

dependencies {
    implementation platform("org.springframework.boot:spring-boot-dependencies:4.1.2")
    implementation "org.springframework.boot:spring-boot-starter-webmvc"
}

Một nguồn version, một lần nâng cấp. Nếu bạn ghi <version> cho một starter, bạn tự tách nó khỏi bảng và tự chịu trách nhiệm về tương thích.

Đọc cây dependency trước khi tin vào starter

mvn dependency:tree là công cụ duy nhất trả lời được “cái gì thực sự vào classpath”. Ba biến thể đủ dùng:

# toàn bộ cây
mvn dependency:tree

# chỉ nhánh Spring Boot
mvn dependency:tree -Dincludes=org.springframework.boot:*

# xem thư viện nào kéo tomcat, kèm lý do bị loại
mvn dependency:tree -Dverbose -Dincludes=org.apache.tomcat.embed

Đọc kết quả theo ba dấu hiệu: +- là nhánh còn sống, \- là nhánh cuối, và các dòng ghi omitted for duplicate hoặc omitted for conflict cho biết Maven đã chọn phiên bản gần gốc nhất. Gradle tương đương: ./gradlew dependencies --configuration runtimeClasspath. Muốn biết version được BOM điền là bao nhiêu, dùng mvn help:effective-pom thay vì đoán.

Loại bỏ dependency và loại bỏ auto-configuration

Đây là hai cơ chế khác nhau, và lẫn lộn chúng là nguồn gốc của phần lớn thời gian debug.

Cách 1: exclusion xóa một nhánh khỏi cây dependency. Ví dụ khi bạn muốn thay logging backend, loại spring-boot-starter-logging khỏi starter web:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-webmvc</artifactId>
  <exclusions>
    <exclusion>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-logging</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Exclusion nằm trên dependency khai báo, không phải global. Nó bỏ cả subtree bên dưới, nên sau khi sửa hãy chạy lại dependency:tree để chắc rằng không có đường khác kéo cùng thư viện vào.

Cách 2: tắt auto-configuration không xóa jar, chỉ ngăn bean được tạo. Hai cách tương đương:

import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.jdbc.autoconfigure.DataSourceAutoConfiguration;

@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)
public class ShopApplication {
}
# application.properties
spring.autoconfigure.exclude=org.springframework.boot.jdbc.autoconfigure.DataSourceAutoConfiguration

Property nhận danh sách FQN phân tách bằng dấu phẩy, và có thể dùng cùng lúc với attribute exclude. Chú ý package: với Boot 4, org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration của Boot 3 không còn đúng. Nếu FQN trỏ tới class không có trên classpath, Boot bỏ qua im lặng — bạn tưởng đã tắt nhưng thực ra không. Còn nếu class có mặt mà không phải auto-configuration class, startup fail với IllegalStateException và thông báo could not be excluded because they are not auto-configuration classes.

Các Spring Boot Starters thường gặp và tên đúng năm 2026

Starter (4.1.2) Kéo theo (theo POM) Dùng khi
spring-boot-starter-webmvc starter-jackson, starter-tomcat, spring-boot-webmvc REST API và MVC, Tomcat nhúng
spring-boot-starter-data-jpa starter-jdbc, spring-boot-data-jpa, spring-boot-jdbc JPA/Hibernate, transaction; không kèm driver
spring-boot-starter-security spring-boot-security, spring-aop Xác thực, phân quyền
spring-boot-starter-validation hibernate-validator 9.1.5.Final, tomcat-embed-el @Valid trên DTO
spring-boot-starter-actuator micrometer-observation, spring-boot-health Health, metrics, endpoint vận hành
spring-boot-starter-test JUnit Jupiter 6, Mockito, AssertJ, Spring Test Test; luôn đặt scope test
spring-boot-starter-aspectj aspectjweaver, spring-aop @Aspect, advice
spring-boot-starter-thymeleaf spring-boot-thymeleaf View server-side

Hai cái bẫy nằm ngay trong bảng. spring-boot-starter-web vẫn có ở 4.1.2 nhưng mô tả của nó đã ghi rõ “deprecated in favor of spring-boot-starter-webmvc”; đừng copy từ bài viết cũ. Còn spring-boot-starter-aop thì không có artifact 4.1.2 để tải — mvn dependency:tree sẽ dừng ở dependency resolution, không phải ở runtime.

Vì Boot 4 đã modularize, các starter giờ là alias mỏng trên những module công nghệ như spring-boot-webmvc hay spring-boot-jdbc. Bạn sẽ thấy chúng trong cây dependency và có thể khai báo trực tiếp, nhưng starter vẫn là entry point được hỗ trợ vì nó gom đủ các mảnh phụ (Jackson, Tomcat, EL).

Không phải lúc nào starter cũng đúng. Nếu bạn chỉ cần RestClient và không muốn Tomcat hay Jackson, khai báo trực tiếp org.springframework:spring-web rẻ hơn nhiều so với kéo cả spring-boot-starter-webmvc. Ngược lại, đừng tự lắp từng mảnh của một stack phổ biến: bạn sẽ phải tự giữ tương thích, đúng việc mà BOM đang làm hộ.

Custom starter: ba mảnh, không hơn

Starter nội bộ giúp chuẩn hóa cấu hình giữa nhiều dự án. Cấu trúc chuẩn là hai module: acme-spring-boot-autoconfigure chứa code, và acme-spring-boot-starter chỉ là POM phụ thuộc vào module kia. Đặt tên spring-boot-starter-* dành cho starter chính thức; của bạn nên là *-spring-boot-starter.

Mảnh thứ nhất, lớp auto-configuration:

// File: acme-spring-boot-autoconfigure/src/main/java/com/acme/autoconfigure/AcmeClientAutoConfiguration.java
package com.acme.autoconfigure;

import com.acme.client.AcmeClient;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;

@AutoConfiguration
@ConditionalOnClass(AcmeClient.class)
@EnableConfigurationProperties(AcmeClientProperties.class)
public class AcmeClientAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    AcmeClient acmeClient(AcmeClientProperties properties) {
        return new AcmeClient(properties.endpoint(), properties.timeout());
    }
}

Bốn annotation làm bốn việc khác nhau: @AutoConfiguration đánh dấu lớp chỉ được nạp qua file imports, @ConditionalOnClass bảo vệ khi client không có trên classpath, @ConditionalOnMissingBean cho phép người dùng override bean. @EnableConfigurationProperties biến record cấu hình thành bean.

Mảnh thứ hai, properties có kiểu:

// File: acme-spring-boot-autoconfigure/src/main/java/com/acme/autoconfigure/AcmeClientProperties.java
package com.acme.autoconfigure;

import java.time.Duration;
import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "acme.client")
public record AcmeClientProperties(String endpoint, Duration timeout) {
}

Record nhận constructor binding, nên acme.client.endpoint và acme.client.timeout=5s được bind mà không cần setter. Thêm spring-boot-configuration-processor dạng optional để IDE gợi ý key.

Mảnh thứ ba, đăng ký:

$ cat src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
com.acme.autoconfigure.AcmeClientAutoConfiguration

Đừng đặt lớp này trong package mà @SpringBootApplication quét. Auto-configuration phải được nạp bởi file imports, không bởi component scan; nếu bị quét, điều kiện có thể được đánh giá theo cách khác và @ConditionalOnMissingBean mất tác dụng. Một ApplicationContextRunner trong module autoconfigure là bài test rẻ nhất để chứng minh starter hoạt động.

Vì sao thêm một starter khiến ứng dụng không khởi động được

Ba nguyên nhân thực tế:

Thiếu driver. spring-boot-starter-data-jpa kéo JPA và connection pool nhưng không kéo JDBC driver. Không có org.postgresql:postgresql hay com.mysql:mysql-connector-j, DataSourceAutoConfiguration vẫn chạy và fail với thông báo Failed to determine a suitable driver class. Thêm driver ở scope runtime, hoặc tắt DataSourceAutoConfiguration nếu ứng dụng chưa cần database — nhưng khi đó repository JPA cũng không có EntityManagerFactory.

Security mặc định. Chỉ cần spring-boot-starter-security trên classpath, Boot áp một SecurityFilterChain chặn mọi request, bật form login và in mật khẩu generated ra console. REST API bắt đầu trả 401 hoặc chuyển hướng 302, dù bạn chưa viết dòng bảo mật nào. Đây là hành vi đúng, không phải lỗi: phải tự khai báo SecurityFilterChain với lambda DSL.

Bean trùng kiểu. Khi hai nguồn cùng đóng góp bean cho một interface, inject theo interface sẽ ném NoUniqueBeanDefinitionException. Cách chữa không phải là xóa starter, mà là đánh dấu @Primary, hoặc tắt đúng auto-configuration đang tranh chấp. Đọc log startup sẽ thấy tên bean và tên lớp cấu hình — đó là thông tin đủ để quyết định.

Pitfalls

  • Hard-code version. Một starter có <version> riêng sẽ lệch khỏi bảng BOM và kéo cả một nhánh phiên bản khác. Nếu buộc phải ghim, ghim ở dependencyManagement và ghi rõ lý do.
  • Dùng parent và BOM cùng lúc. Kế thừa starter-parent 4.1.2 rồi import thêm spring-boot-dependencies 4.0.9 là hai nguồn quản lý version. Chọn một: parent cho dự án độc lập, BOM import cho dự án đã có parent công ty.
  • Exclude quá nhiều. Bỏ spring-boot-starter-logging mà không thay backend thì mất log; bỏ spring-boot-starter-tomcat thì không còn server nhúng. Mỗi exclusion phải kiểm chứng bằng dependency tree và một lần chạy ứng dụng.
  • Tưởng starter là thư viện. Không có package org.springframework.boot.starter để import. Starter chỉ là descriptor; API nằm ở thư viện mà nó kéo theo.
  • Tưởng exclude auto-config xóa dependency. Jar vẫn trên classpath, @ConditionalOnClass ở nơi khác vẫn khớp. Nếu mục tiêu là giảm kích thước, phải dùng exclusion.
  • Quên scope test. spring-boot-starter-test ở scope compile đưa JUnit và Mockito vào artifact production; luôn dùng <scope>test</scope> hoặc testImplementation.
  • Thêm starter cho “chắc ăn”. Mỗi starter là một bề mặt auto-configuration mới. Thêm security khi chưa cần biến mọi endpoint thành 401.

Checklist

  • Dùng spring-boot-starter-webmvc, không dùng spring-boot-starter-web, cho code mới trên Boot 4.1.
  • Dùng spring-boot-starter-aspectj nếu cần AOP; đừng tìm -aop.
  • Chạy mvn dependency:tree sau mỗi lần thêm hoặc exclude một starter.
  • Kiểm tra FQN trong spring.autoconfigure.exclude sau khi nâng Boot 4, vì package đã đổi.
  • Driver database là dependency riêng, không nằm trong starter JPA.
  • Custom starter phải có file AutoConfiguration.imports và không nằm trong component scan.

Nhìn về 2027

Boot 4.2 đang ở RC2, chưa GA; đừng đưa vào production chỉ vì tò mò. Hướng đi rõ ràng là tiếp tục modularization, nên tên artifact và package auto-configuration có thể còn dịch chuyển. Khi bump version, đọc release notes của starter trước khi sửa POM — rẻ hơn nhiều so với việc đọc stack trace lúc startup.

Nền tảng của cơ chế này nằm ở bài Spring Boot Autoconfiguration — Có gì diễn ra bên dưới?. Để thấy starter web ráp thành ứng dụng hoàn chỉnh ra sao, đọc Các thành phần thiết yếu của một ứng dụng web Spring MVC. Khi cần quan sát ứng dụng đang chạy, Actuator là bước tiếp theo; toàn bộ thứ tự bài học nằm trong Spring Boot Roadmap.