Spring không tạo bean vì bạn viết @Service. Spring IoC container tạo bean vì bên trong nó có một bean definition, và annotation chỉ là một trong bốn cách ghi definition đó vào. Hiểu đường đi này giúp bạn trả lời những câu hỏi thực tế: tại sao bean không được tìm thấy, tại sao có hai candidate, tại sao @Transactional không mở transaction, và tại sao một lớp cấu hình nhỏ lại làm startup chậm.
Bài này đi từ ApplicationContext đến vòng đời bean, qua bốn đường đăng ký, rồi dừng ở những chỗ hay debug sai. Code dùng Boot 4.1.2 trên Java 25 LTS.
Mục lục
Cập nhật 2026
- Container API không đổi. Boot 4.1.2 và Framework 7.0.10 vẫn dùng
ApplicationContext,BeanDefinition,BeanPostProcessor,@Beannhư bạn biết. Boot 4 không viết lại IoC container; nó thay đổi cách đóng gói và cấu hình xung quanh. javax.annotationđã bị bỏ.@PostConstructvà@PreDestroygiờ đến từjakarta.annotation(Jakarta EE 11). Code copy từ blog cũ sẽ không compile, và Framework 7 cũng không còn hỗ trợjavax.inject.- Boot 4 chia jar theo công nghệ. Auto-configuration của từng công nghệ nằm trong module tương ứng; cơ chế
@ConditionalOnMissingBeanvẫn là thứ cho phép bean của bạn thắng default. - Virtual threads không đổi luật chơi.
spring.threads.virtual.enabled=truelàm blocking rẻ hơn, nhưng singleton vẫn là một instance dùng chung. Scope và thread-safety không thay đổi.
ApplicationContext: IoC container bạn thực sự đang chạy
BeanFactory là interface gốc: giữ bean definition và trả instance theo tên hoặc kiểu. ApplicationContext mở rộng nó với resource loading, message source, event, tích hợp AOP và khả năng web-aware. Trong Boot, SpringApplication.run trả về một ConfigurableApplicationContext; với web app, đó là context servlet.
Bạn hiếm khi tự new AnnotationConfigApplicationContext trong production. Hãy để Boot dựng context, rồi inject ApplicationContext ở chỗ cần chẩn đoán: ApplicationRunner, endpoint admin hoặc test. Service bình thường nên nhận dependency cụ thể; nhận cả context rồi getBean bên trong chỉ biến DI thành service locator.
// File: src/main/java/com/example/catalog/ops/ContainerReport.java
package com.example.catalog.ops;
import java.util.Map;
import com.example.catalog.pricing.PricingService;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.context.ApplicationContext;
import org.springframework.stereotype.Component;
@Component
public class ContainerReport implements ApplicationRunner {
private final ApplicationContext context;
public ContainerReport(ApplicationContext context) {
this.context = context;
}
@Override
public void run(ApplicationArguments args) {
String[] names = context.getBeanNamesForType(PricingService.class);
PricingService one = context.getBean(PricingService.class);
Map<String, PricingService> all = context.getBeansOfType(PricingService.class);
System.out.printf("%d definition, primary=%s, tong instance=%d%n",
names.length, one.getClass().getSimpleName(), all.size());
}
}
Ba lời gọi không tương đương. getBeanNamesForType chỉ đọc metadata. getBean(Class) trả đúng một instance và ném lỗi nếu có nhiều candidate. getBeansOfType trả map tên → instance và khởi tạo từng bean khớp, nên đừng gọi trong vòng lặp nóng. Cần lấy bean theo điều kiện thì dùng ObjectProvider.
Chuỗi refresh — đọc definition, chạy BeanFactoryPostProcessor, tạo singleton — được mô tả ở bài Cách Spring hoạt động. Nắm thứ tự đó trước khi đọc phần vòng đời.
Bean definition và bốn đường đăng ký
BeanDefinition là metadata, không phải instance: class, scope, lazy flag, factory method, init/destroy, qualifier. Container đọc definition rồi mới quyết định tạo gì, khi nào và tiêm gì.
- Component scanning —
@Component,@Service,@Repository,@Controllervà meta-annotation. Chỉ class trong package được quét mới được đăng ký. Tên mặc định là tên class viết thường chữ đầu:OrderNotifierthànhorderNotifier. @Beantrong@Configuration— dùng cho class thư viện, object cần dựng có điều kiện, hoặc logic khởi tạo phức tạp. Tham số method là dependency; tên bean mặc định là tên method.@Import— kéo lớp cấu hình ngoài vùng scan: config module nội bộ, config riêng cho test, hoặc config từ thư viện không có auto-configuration.@ImportResource— nạp file XML cũ. Mỗi<bean>trở thành một bean definition tương đương; đây là cầu nối migration, không phải cách viết dự án mới.
// File: src/main/java/com/example/catalog/orders/OrderNotifier.java
package com.example.catalog.orders;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
@Service
public class OrderNotifier {
private static final Logger log = LoggerFactory.getLogger(OrderNotifier.class);
public void notifyAccepted(String orderId) {
log.info("order {} accepted", orderId);
}
}
Class trên được đăng ký vì nằm dưới package gốc. Nếu không muốn phụ thuộc vào scan, khai báo tường minh bằng @Bean:
// File: src/main/java/com/example/catalog/CatalogConfig.java
package com.example.catalog;
import java.time.Clock;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration(proxyBeanMethods = false)
public class CatalogConfig {
@Bean
Clock clock() {
return Clock.systemUTC();
}
}
Clock là ví dụ tốt cho @Bean: thuộc JDK, không thể thêm annotation, và trong test bạn muốn thay bằng Clock.fixed. Còn @Import và @ImportResource thường đi cùng nhau khi bọc code cũ:
// File: src/main/java/com/example/catalog/LegacyBridgeConfig.java
package com.example.catalog;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.context.annotation.ImportResource;
@Configuration(proxyBeanMethods = false)
@Import(CatalogConfig.class)
@ImportResource("classpath:legacy-beans.xml")
public class LegacyBridgeConfig {
}
Điểm cần nhớ: @Service không tạo bean, nó tạo definition lúc parse cấu hình. Instance chỉ xuất hiện khi container khởi tạo singleton, nên lỗi constructor fail lúc refresh — hoặc lúc request đầu nếu bean lazy.
Cách tiêm dependency vẫn là constructor injection như bài Hiểu về Dependency Injection: một constructor, tham số là collaborator, không cần @Autowired.
Boot 4.1 thêm gì lên trên
Boot không tạo bean theo cơ chế khác. Nó đóng gói sẵn các bean definition có điều kiện, gọi là auto-configuration. Cấu hình của bạn được đăng ký trước, auto-configuration chạy sau, nên điều kiện “chưa có ai tạo” nhìn thấy bean của bạn và rút lui.
// File: src/main/java/com/example/catalog/infra/ClockAutoConfiguration.java
package com.example.catalog.infra;
import java.time.Clock;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
@AutoConfiguration
public class ClockAutoConfiguration {
@Bean
@ConditionalOnMissingBean
Clock clock() {
return Clock.systemUTC();
}
}
@AutoConfiguration là @Configuration có thêm ordering. Khi không chỉ định value, type hay name, @ConditionalOnMissingBean lấy kiểu trả về làm tiêu chí — ở đây là Clock. Nếu app đã có bean Clock, method này không chạy. Nếu hai auto-configuration cùng có thể tạo một bean, dùng after/before để xác định ai chạy trước; điều kiện không nhìn thấy tương lai. Lớp @AutoConfiguration không được scan tự động: khi tự viết, đăng ký nó qua @Import hoặc metadata của module.
Đừng đặt @ConditionalOnMissingBean trên @Bean trong config thường: kết quả phụ thuộc thứ tự parse và dễ tạo bean trùng tên. Annotation này chỉ đáng tin trong auto-configuration.
Boot 4 chia jar theo công nghệ, nên auto-configuration của MVC, JPA hay Security nằm trong module tương ứng. Khi tra một class, tra theo module và starter đang dùng; cơ chế override không đổi. Bài Spring Boot Autoconfiguration giải thích phần discovery chi tiết hơn.
Kiểm thử auto-configuration bằng ApplicationContextRunner
ApplicationContextRunner (trong spring-boot-test, có trong API 4.1.2) dựng context tối thiểu, không web server, không scan toàn app. Đây là công cụ đúng để test điều kiện và thứ tự.
// File: src/test/java/com/example/catalog/infra/ClockAutoConfigurationTest.java
package com.example.catalog.infra;
import static org.assertj.core.api.Assertions.assertThat;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
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;
class ClockAutoConfigurationTest {
private final ApplicationContextRunner runner = new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(ClockAutoConfiguration.class));
@Test
void tao_clock_mac_dinh_khi_khong_co_bean_nao() {
runner.run(context -> assertThat(context).hasSingleBean(Clock.class));
}
@Test
void nhuong_cho_bean_cua_nguoi_dung() {
runner.withUserConfiguration(FixedClockConfig.class).run(context -> {
assertThat(context).hasSingleBean(Clock.class);
assertThat(context.getBean(Clock.class)).isSameAs(FixedClockConfig.FIXED);
});
}
@Configuration(proxyBeanMethods = false)
static class FixedClockConfig {
static final Clock FIXED =
Clock.fixed(Instant.parse("2026-11-09T00:00:00Z"), ZoneOffset.UTC);
@Bean
Clock clock() {
return FIXED;
}
}
}
Test thứ hai chứng minh cơ chế override: bean người dùng thắng, số bean vẫn là một, instance đúng object bạn khai báo. Nếu fail vì hai bean Clock, bạn đã đặt điều kiện sai chỗ hoặc auto-configuration chạy trước nguồn bean kia.
Vòng đời bean: proxy xuất hiện ở đâu
Container không chỉ gọi constructor. Với một singleton, thứ tự thực tế là:
- Instantiation — gọi constructor, resolve tham số. Constructor injection giải quyết dependency ngay tại đây.
- Populate — tiêm field/setter nếu bạn dùng chúng. Circular dependency với constructor fail ngay ở bước 1, không phải lúc compile; setter injection mới lộ ra ở bước này.
- BeanPostProcessor before-init —
CommonAnnotationBeanPostProcessorgọi@PostConstruct, sau đó làInitializingBean.afterPropertiesSetvà custom init method. - BeanPostProcessor after-init — đây là nơi
AbstractAutoProxyCreatorvà processor của@Asyncbọc bean bằng proxy nếu cần. - Ready — bean nằm trong singleton registry và được inject cho người khác dưới dạng proxy nếu có.
- Destruction — khi context đóng:
@PreDestroy,DisposableBean.destroy, rồi destroy method. Prototype không được container quản lý sau khi tạo.
// File: src/main/java/com/example/catalog/orders/OrderAudit.java
package com.example.catalog.orders;
import jakarta.annotation.PostConstruct;
import jakarta.annotation.PreDestroy;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import org.springframework.transaction.annotation.Transactional;
@Component
public class OrderAudit {
private static final Logger log = LoggerFactory.getLogger(OrderAudit.class);
public OrderAudit() {
log.info("1. constructor");
}
@PostConstruct
void init() {
log.info("2. postconstruct - bean van la object that, chua co proxy");
// this.record("boot") o day chay truc tiep, khong qua @Transactional
}
@Transactional
public void record(String note) {
log.info("3. record trong transaction cho {}", note);
}
@PreDestroy
void shutdown() {
log.info("4. predestroy");
}
}
Proxy được tạo sau init callback. Trong @PostConstruct, this vẫn là object thật: gọi method @Transactional của chính bean không mở transaction, gọi @Async cũng chạy đồng bộ. Gọi nội bộ cùng class ở bất kỳ lúc nào cũng bỏ qua proxy, vì lời gọi không qua ranh giới bean. Đây là lỗi self-invocation kinh điển.
Ngược lại, bean khác inject bean này sẽ nhận proxy, nên @Transactional hoạt động khi gọi từ ngoài. Bạn có thể xác nhận bằng một BeanPostProcessor nhỏ:
// File: src/main/java/com/example/catalog/infra/ProxyReport.java
package com.example.catalog.infra;
import org.springframework.aop.support.AopUtils;
import org.springframework.beans.factory.config.BeanPostProcessor;
import org.springframework.stereotype.Component;
@Component
public class ProxyReport implements BeanPostProcessor {
@Override
public Object postProcessAfterInitialization(Object bean, String beanName) {
if (AopUtils.isAopProxy(bean)) {
System.out.println(beanName + " -> "
+ AopUtils.getTargetClass(bean).getSimpleName());
}
return bean;
}
}
Nếu orderAudit xuất hiện trong output, proxy tồn tại và @Transactional có cơ hội hoạt động. Nếu không, kiểm tra transaction manager, visibility của method và lời gọi có đi qua bean.
Tên bean và va chạm
Scan lấy tên class viết thường chữ đầu; @Bean lấy tên method. Đổi bằng @Service("manualPricing") hoặc @Bean("fixedClock"). Hai class khác package cùng tên đơn giản sẽ tạo cùng bean name và báo ConflictingBeanDefinitionException lúc khởi động — đổi tên tường minh là cách sửa.
// File: src/main/java/com/example/catalog/infra/ClockConfig.java
package com.example.catalog.infra;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
@Configuration(proxyBeanMethods = false)
public class ClockConfig {
@Bean
@Primary
Clock systemClock() {
return Clock.systemUTC();
}
@Bean("fixedClock")
Clock fixedClock() {
return Clock.fixed(Instant.EPOCH, ZoneOffset.UTC);
}
}
Hai bean cùng kiểu Clock: getBean(Clock.class) và inject theo kiểu vẫn chạy nhờ @Primary. Bỏ @Primary, lỗi là NoUniqueBeanDefinitionException — Spring không đoán ý bạn. @Qualifier("fixedClock") tại điểm inject thắng @Primary; hai @Primary trên cùng kiểu cũng gây lỗi.
Sáu lỗi thường gặp
- Main class sai package.
@SpringBootApplicationquét package của main và package con. Main ởcom.example.catalog.appcòn service ởcom.example.catalog.servicethì service không được đăng ký. Đưa main lên package gốc hoặc dùngscanBasePackages. @Beanmethod trả vềvoid. Đây không phải factory method; Spring chặn lúc tạo bean với thông báo “needs to have a non-void return type!”. Muốn chạy setup, chuyển sang@PostConstructcủa bean, hoặc trả về object thật.- Hiểu sai full và lite mode.
@Configurationmặc địnhproxyBeanMethods=truevà CGLIB chặn lời gọi giữa các@Beanmethod để trả singleton. Vớifalse, lời gọi là Java thường và tạo instance mới. Cách an toàn: truyền dependency qua tham số, đừng gọi chéo. - Static state trong singleton.
staticdùng chung cả giữa các context trong cùng JVM — test song song lộ ra trước. Giữ bean stateless hoặc dùng cấu trúc đồng bộ có chủ đích. - Eager initialization đắt. Mặc định mọi singleton được tạo lúc startup; bean mở connection, nạp cache, warmup client cộng dồn vào thời gian boot. Đo trước; nếu chấp nhận, dùng
spring.main.lazy-initialization=truenhưng biết lỗi sẽ dời sang request đầu. - Dùng context như service locator.
getBeantrong business code che dependency và biến lỗi cấu hình thành lỗi runtime. Inject dependency cụ thể; chỉ dùng context ở lớp chẩn đoán.
Khi nào dùng cách nào
| Cách | Dùng khi | Tránh khi |
|---|---|---|
| Component scan | Class do bạn viết, quan hệ rõ ràng, phần lớn service/repository/controller | Class thư viện, object cần dựng có điều kiện |
@Bean |
Class bên thứ ba, cấu hình đọc từ property, nhiều biến thể của cùng một kiểu | Chỉ để gom logic khởi tạo vào config class |
@Import |
Config của module nội bộ, config dùng riêng cho test, thư viện không auto-config | Muốn scan tự động trong cùng package |
@ImportResource |
Dự án legacy còn XML, cần chạy song song trong lúc migration | Dự án mới hoặc module mới |
Trong dự án mới, tỉ lệ lành mạnh là scan cho code của bạn, @Bean cho thứ bạn không sở hữu, gần như không có XML. Nếu phải dùng @ImportResource, đặt nó trong config class riêng có tên rõ mục đích để sau này xóa dễ.
Nhìn về 2027
Spring Boot 4.2 và Framework 7.1 đang RC, đừng viết tài liệu nội bộ dựa trên chúng. Java 29 là LTS kế tiếp theo nhịp hai năm, dự kiến 2027. Container API nhiều khả năng giữ nguyên; thứ đáng theo dõi là module hóa artifact và đóng gói auto-configuration.
Checklist
- Đặt main class ở package gốc; kiểm tra bằng
getBeanNamesForTypethay vì đoán. - Dùng constructor injection, một constructor, không field injection.
- Kiểm tra bean bạn định thay default có thật sự thắng bằng một test
ApplicationContextRunner. - Không gọi method
@Transactional/@Asynctừ@PostConstructhoặc từ chính class. - Giữ singleton stateless; mọi trạng thái thay đổi phải nằm ở request, local variable hoặc cấu trúc thread-safe.
- Đo thời gian startup trước khi bật lazy initialization.
Bước tiếp theo là phạm vi tồn tại của bean — singleton, prototype và các scope web — trong bài Spring Bean Scopes. Hiểu vòng đời ở đây sẽ giúp phần đó không còn là danh sách annotation.



