Bạn thêm spring-boot-starter-webmvc vào pom.xml, chạy hàm main, và một Tomcat nhúng cùng DispatcherServlet xuất hiện dù không ai viết cấu hình. Spring Boot Autoconfiguration không phải phép màu: đó là một chuỗi bước có thứ tự — đọc danh sách lớp từ file trong jar, đánh giá điều kiện, rồi đăng ký bean vào context.
Hiểu chuỗi này giúp bạn trả lời ba câu hỏi: vì sao bean của bạn thắng bean mặc định, vì sao một auto-config không chạy dù thư viện đã có, và vì sao nâng cấp Boot làm code loại trừ gãy. Code dùng Boot 4.1.2, Framework 7.0.10, Java 25 LTS.
Mục lục
Cập nhật 2026
- Boot 4 tách module. Auto-config của từng công nghệ nằm trong module riêng;
WebMvcAutoConfigurationgiờ ởorg.springframework.boot.webmvc.autoconfigure(modulespring-boot-webmvc). spring-boot-starter-webmvcthay-web. Từ Boot 4.1,spring-boot-starter-webbị deprecate nhưng vẫn resolve; code mới nên dùng starter mới.- Không còn
spring.factoriescho auto-config. Từ Boot 3.0, danh sách lớp nằm ởMETA-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports; Boot 4 giữ nguyên file này. - Cơ chế không đổi. Vẫn là import selector, condition evaluation và sắp thứ tự; Java 25 LTS là baseline thực tế, dù Boot 4.1 chỉ yêu cầu Java 17.
Spring Boot Autoconfiguration: chuỗi sáu bước từ main đến bean
SpringApplication.run tạo ApplicationContext kiểu servlet, reactive hoặc non-web tùy classpath, rồi đăng ký ConfigurationClassPostProcessor. Đây là BeanFactoryPostProcessor đọc toàn bộ lớp cấu hình trước khi bất kỳ bean nghiệp vụ nào được tạo. Toàn bộ autoconfiguration diễn ra trong pha này.
@SpringBootApplicationtrên lớp main được mở ra thành ba annotation:@SpringBootConfiguration,@EnableAutoConfiguration,@ComponentScan.@EnableAutoConfigurationmở tiếp thành@AutoConfigurationPackagevà@Import(AutoConfigurationImportSelector.class). Annotation thứ nhất ghi nhớ package gốc cho entity/repository scan; annotation thứ hai mới là động cơ.AutoConfigurationImportSelectorquét mọi jar trên classpath, tìm fileAutoConfiguration.imports, gom danh sách FQCN. Không lớp nào bị load ở bước này; chỉ metadata được đọc.AutoConfigurationSortersắp danh sách theo@AutoConfigureBefore,@AutoConfigureAftervà thứ tự alphabet khi hòa.ConfigurationClassParserđọc từng lớp;ConditionEvaluatorquyết định lớp hoặc method@Beancó bị bỏ qua không.ConfigurationClassBeanDefinitionReaderđăng kýBeanDefinitioncho những gì sống sót; container sau đó khởi tạo bean theo scope và dependency.
Bước 3 chỉ tạo danh sách: lớp auto-config có mặt trong jar không có nghĩa nó được áp dụng; điều kiện ở bước 5 mới quyết định. Nếu ApplicationContext và BeanFactoryPostProcessor còn mơ hồ, đọc trước Cách Spring hoạt động: kiến trúc cốt lõi.
Starter chỉ kéo dependency, quyết định nằm ở imports file
Như đã giải thích trong Spring Boot Starters, starter là bundle dependency, không chứa logic cấu hình. Logic nằm trong module công nghệ mà starter kéo vào, và mỗi module tự khai báo lớp auto-config của mình bằng một file text:
# File: src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
com.example.audit.AuditAutoConfiguration
Mỗi dòng là một FQCN; dòng bắt đầu bằng # là comment, dòng trống bị bỏ qua. Không có cặp key=value như spring.factories, nên không lẫn với các SPI khác. Boot 3.0 bỏ hẳn file cũ cho auto-config; Boot 4 vẫn dùng đúng file này.
Lớp trong file imports dùng @AutoConfiguration, không phải @Configuration thường. Annotation này tương đương @Configuration(proxyBeanMethods = false) và mang thêm metadata thứ tự; từ Boot 3, @AutoConfigureBefore/@AutoConfigureAfter chỉ hợp lệ trên lớp auto-config. Đừng @Import thẳng lớp auto-config vào cấu hình người dùng: nó bị xử lý như cấu hình thường và mất quyền lợi về thứ tự.
Bốn điều kiện quyết định lớp có chạy hay không
| Annotation | Câu hỏi | Ghi chú thực dụng |
|---|---|---|
@ConditionalOnClass |
Lớp có trên classpath? | Đọc metadata, không load class; dùng name nếu lớp có thể vắng mặt lúc biên dịch |
@ConditionalOnMissingBean |
Chưa có bean kiểu này? | Đánh giá lúc đăng ký bean, chỉ thấy bean đã đăng ký trước đó |
@ConditionalOnProperty |
Property có giá trị mong đợi? | prefix, name, havingValue, matchIfMissing; tên property dùng relaxed binding |
@ConditionalOnWebApplication |
Ứng dụng thuộc loại web? | type là SERVLET, REACTIVE hoặc ANY |
ConditionEvaluator chạy hai pha. PARSE_CONFIGURATION xử lý điều kiện chỉ cần metadata như @ConditionalOnClass và @ConditionalOnProperty. REGISTER_BEAN xử lý điều kiện cần trạng thái container như @ConditionalOnBean và @ConditionalOnMissingBean. Vì vậy điều kiện “thiếu bean” trên một method @Bean không thể thấy bean sẽ được đăng ký sau nó — kể cả bean do một auto-config khác tạo ra.
Vì sao @ConditionalOnMissingBean tồn tại? Tác giả thư viện không biết bạn sẽ khai báo gì. Nếu auto-config luôn tạo DataSource, RestClient.Builder hay ObjectMapper của riêng nó, bạn buộc phải bật bean overriding hoặc dùng @Primary — hai thứ dễ che lỗi. Điều kiện này biến việc ghi đè thành hành vi mặc định: bạn chỉ cần khai báo bean cùng kiểu, thư viện tự lùi. Đặt trên method để bỏ từng bean, trên lớp để bỏ cả lớp.
Với @ConditionalOnProperty, ba lỗi hay gặp là sai havingValue (phân biệt hoa thường), quên matchIfMissing nên tính năng tắt khi vắng property, và gõ sai tên. Còn @ConditionalOnWebApplication mặc định là ANY; nếu cần ServletContext, chỉ định type = Type.SERVLET.
Thứ tự: auto-config luôn chạy sau cấu hình của bạn
AutoConfigurationImportSelector là một DeferredImportSelector. Nhóm deferred được xử lý sau khi toàn bộ @Configuration thường của ứng dụng đã được parse. Nhờ đó bean của bạn đã nằm trong bean factory trước khi auto-config đánh giá @ConditionalOnMissingBean. Đây là bảo đảm quan trọng nhất của cả cơ chế, và cũng là lý do bạn hiếm khi cần @Primary.
Giữa các auto-config với nhau, thứ tự do @AutoConfiguration(before = ..., after = ...) hoặc @AutoConfigureBefore/@AutoConfigureAfter quyết định. Boot dùng thứ tự này cho những phụ thuộc thật: auto-config Tomcat nhúng phải chạy trước auto-config MVC để DispatcherServlet có môi trường servlet — câu chuyện máy chủ nhúng nằm ở Tomcat nhúng trong Spring Boot.
Hai giới hạn cần nhớ. Một, @AutoConfigureBefore/@AutoConfigureAfter chỉ sắp xếp auto-config với auto-config, còn cấu hình người dùng luôn được xử lý trước. Hai, khi không có quan hệ before/after, thứ tự alphabet của FQCN là tie-breaker — chi tiết triển khai, đừng thiết kế dựa vào nó. Nếu điều kiện phụ thuộc bean do auto-config khác tạo, hãy khai báo quan hệ thứ tự tường minh.
Bean của bạn thắng: cơ chế và cách làm sạch
Ví dụ thực tế nhất là RestClient.Builder. Boot auto-configure builder này với @ConditionalOnMissingBean, nên một bean cùng kiểu trong cấu hình của bạn sẽ thay thế nó cho mọi RestClient được dựng từ builder:
// File: src/main/java/com/example/shop/client/HttpClientConfig.java
package com.example.shop.client;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestClient;
@Configuration(proxyBeanMethods = false)
public class HttpClientConfig {
@Bean
RestClient.Builder restClientBuilder() {
return RestClient.builder()
.baseUrl("https://api.example.com")
.defaultHeader("X-Client", "shop");
}
}
Không cần @Primary hay bật bean overriding. Nhưng phân biệt hai nhu cầu: thay builder là thay mặc định toàn ứng dụng; nếu chỉ một client cần baseUrl riêng, khai báo bean RestClient và nhận builder của Boot, hoặc dùng RestClientCustomizer. Ghi đè ở mức thấp nhất còn hiệu quả là cách ít rủi ro nhất.
Nhìn thấy báo cáo: ba cách, ba mức chi tiết
Chạy với --debug. java -jar shop.jar --debug in ra CONDITIONS EVALUATION REPORT ngay khi khởi động, gồm Positive matches, Negative matches, Exclusions và Unconditional classes. Khi một bean không xuất hiện, đọc Negative matches trước: nó ghi rõ điều kiện nào trượt. debug=true trong application.properties cũng cho báo cáo này; đừng bật ở production vì log rất dài.
Đọc bằng code. Trong test, lấy report từ bean factory bằng ConditionEvaluationReport.get(context.getBeanFactory()) và kiểm tra lớp auto-config của bạn nằm ở positive hay negative match. Cách này hữu ích khi cần một test canh việc “không được tự bật khi thiếu property”.
Xem trên ứng dụng đang chạy. Thêm Actuator và expose endpoint conditions:
management.endpoints.web.exposure.include=health,conditions
Sau đó gọi GET /actuator/conditions. Endpoint trả về cùng dữ liệu với báo cáo debug, nhưng theo JSON và lấy được từ xa. Chỉ expose ở môi trường bạn kiểm soát: nó lộ cấu trúc cấu hình nội bộ.
Ghi đè hay loại trừ: chọn mức can thiệp
| Mức | Cách làm | Dùng khi |
|---|---|---|
| Thuộc tính | spring.* trong properties/env |
Mặc định đã đủ, chỉ cần chỉnh tham số |
| Customizer | WebServerFactoryCustomizer, RestClientCustomizer |
Thay chi tiết nhỏ, vẫn giữ bean gốc |
| Bean của bạn | @Bean cùng kiểu trong @Configuration |
Thay một bean, nhờ @ConditionalOnMissingBean |
| Loại trừ | exclude hoặc spring.autoconfigure.exclude |
Bỏ cả lớp auto-config vì bạn tự cấu hình toàn bộ |
Loại trừ bằng code trông như sau (ví dụ chọn lớp MVC vì package của nó đã đổi ở Boot 4):
// File: src/main/java/com/example/report/ReportApplication.java
package com.example.report;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.webmvc.autoconfigure.WebMvcAutoConfiguration;
@SpringBootApplication(exclude = WebMvcAutoConfiguration.class)
public class ReportApplication {
public static void main(String[] args) {
SpringApplication.run(ReportApplication.class, args);
}
}
Loại trừ WebMvcAutoConfiguration bỏ luôn static resources, message converters và view resolver mặc định — chỉ làm khi bạn tự cấu hình MVC. Cùng hiệu quả qua property:
spring.autoconfigure.exclude=org.springframework.boot.webmvc.autoconfigure.WebMvcAutoConfiguration
Nếu lớp cần loại trừ không có trên compile classpath, dùng excludeName với FQCN dạng chuỗi. Boot kiểm tra danh sách này lúc khởi động và báo lỗi nếu tên không phải auto-config; lỗi thường đến từ việc copy FQCN của Boot 3, khi các lớp còn nằm trong org.springframework.boot.autoconfigure.*.
Viết auto-config cho thư viện của bạn
Ba mảnh: lớp @AutoConfiguration, file imports, và một lớp @ConfigurationProperties. Lớp dưới đây ví dụ cho thư viện audit dùng RestClient; AuditClient và AuditProperties là lớp của thư viện, không phải API của Spring:
// File: src/main/java/com/example/audit/AuditAutoConfiguration.java
package com.example.audit;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.web.client.RestClient;
@AutoConfiguration
@ConditionalOnClass(RestClient.class)
@ConditionalOnProperty(prefix = "example.audit", name = "enabled",
havingValue = "true", matchIfMissing = true)
@EnableConfigurationProperties(AuditProperties.class)
public class AuditAutoConfiguration {
@Bean
@ConditionalOnMissingBean
AuditClient auditClient(AuditProperties properties, RestClient.Builder builder) {
return new AuditClient(builder.baseUrl(properties.getUrl()).build());
}
}
Điều kiện ở đây có chủ đích: chỉ chạy khi RestClient có mặt, chỉ chạy khi property không bị tắt, và nhường quyền cho người dùng nếu họ đã có AuditClient. Test slice dùng ApplicationContextRunner, không cần khởi động cả ứng dụng:
// File: src/test/java/com/example/audit/AuditAutoConfigurationTest.java
package com.example.audit;
import org.junit.jupiter.api.Test;
import org.springframework.boot.autoconfigure.AutoConfigurations;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestClient;
import static org.assertj.core.api.Assertions.assertThat;
class AuditAutoConfigurationTest {
private final ApplicationContextRunner runner = new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(AuditAutoConfiguration.class));
@Test
void backsOffWhenUserDefinesAuditClient() {
runner.withUserConfiguration(UserConfig.class).run(context -> {
assertThat(context).hasSingleBean(AuditClient.class);
assertThat(context.getBean(AuditClient.class).url())
.isEqualTo("https://custom.example.com");
});
}
@Test
void createsDefaultWhenPropertyPresent() {
runner.withPropertyValues("example.audit.url=https://audit.example.com")
.run(context -> assertThat(context).hasSingleBean(AuditClient.class));
}
@Configuration(proxyBeanMethods = false)
static class UserConfig {
@Bean
AuditClient auditClient() {
return new AuditClient(RestClient.builder()
.baseUrl("https://custom.example.com")
.build());
}
}
}
Test đầu tiên chứng minh @ConditionalOnMissingBean thật sự back off — test quan trọng nhất của một auto-config. Để kiểm tra nhánh @ConditionalOnClass, dùng FilteredClassLoader che RestClient. Đừng quên đăng ký lớp trong file imports; thiếu dòng đó, mọi thứ vẫn compile nhưng auto-config không bao giờ được biết đến.
Năm lỗi hay gặp
Đặt @EnableAutoConfiguration ngoài @SpringBootApplication
Annotation này kéo theo @AutoConfigurationPackage, lấy package của lớp mang nó làm gốc. Đặt nó trên lớp tiện ích ở package khác, entity/repository scan trỏ sai chỗ. Nó cũng không nên xuất hiện hai lần: nếu lớp mang nó bị component scan nhặt, bạn có hai đường kích hoạt auto-config trong cùng context. Một lớp main ở package gốc là đủ.
Component scan nhặt luôn lớp auto-config
Nếu lớp auto-config của thư viện nằm dưới package gốc của ứng dụng, @ComponentScan đăng ký nó như cấu hình người dùng trước khi auto-config chạy. Điều kiện được đánh giá ở thời điểm khác, @AutoConfigureAfter mất tác dụng, và bean lẽ ra phải back off lại được tạo. Đặt thư viện dưới package riêng và chỉ công bố lớp qua file imports.
Điều kiện không khớp mà không có log
Không khớp là im lặng theo thiết kế; chỉ báo cáo debug mới nói lý do. Ba nguyên nhân phổ biến: sai havingValue, profile chưa active, và @ConditionalOnMissingBean chạy trước bean của auto-config khác. Sửa bằng --debug rồi bằng thứ tự tường minh; đừng thêm @Primary để che triệu chứng.
Bean trùng kiểu hoặc trùng tên
Hai bean cùng kiểu chỉ nổ lúc inject với NoUniqueBeanDefinitionException; hai định nghĩa cùng tên nổ sớm hơn với BeanDefinitionOverrideException, vì Boot để allow-bean-definition-overriding=false. Đừng bật cờ đó: nó biến lỗi cấu hình thành hành vi phụ thuộc thứ tự. Bỏ định nghĩa thừa, dùng @ConditionalOnMissingBean, hoặc @Primary kèm lý do.
Dựa vào chi tiết nội bộ của auto-config
Exclude theo FQCN, inject bean nội bộ hay kế thừa lớp auto-config đều là hợp đồng không ai bảo vệ. Boot 4 đã chuyển nhiều lớp sang module riêng, nên chuỗi FQCN trong spring.autoconfigure.exclude có thể gãy ở lần nâng minor tới. Khi buộc phải exclude, giữ FQCN trong một hằng số và có test khởi động context.
Nhìn trước 2027
Boot 4.2 đang ở RC2; hướng đi không đổi: module hóa sâu hơn, auto-config nằm cùng module công nghệ, còn imports + conditions giữ nguyên. Với thư viện nội bộ, đầu tư đúng là điều kiện rõ ràng và test slice, không phải mẹo đặt tên lớp.
Checklist trước khi kết luận “auto-config hỏng”
- Chạy lại với
--debugvà đọc Negative matches của đúng lớp nghi ngờ. - Kiểm tra lớp đó có trong file
AutoConfiguration.importsvà có@AutoConfiguration, không chỉ@Configuration. - Kiểm tra property và biến môi trường quy về cùng key (relaxed binding).
- Nếu điều kiện phụ thuộc bean từ auto-config khác, khai báo
afterthay vì tin vào alphabet. - Nếu đã exclude, xác nhận FQCN đúng package của Boot hiện tại và có test khởi động context.
Đọc tiếp trong series
Nền tảng của bài này là Cách Spring hoạt động và Spring Boot Starters. Toàn bộ thứ tự bài học nằm ở Spring Boot Roadmap.



