@Configuration, @Bean, @Component — 3 cách khai báo bean và sự khác biệt

Spring có 3 cách chính khai báo bean: @Component (và bạn bè @Service/@Repository/@Controller), @Bean, và @Configuration. Newcomer thường confused vì các bài blog dùng lẫn lộn: "đặt @Service", "viết @Bean method", "annotate @Configuration class chứa @Bean". 3 cách hoạt động bên dưới khác nhau hoàn toàn — và sự khác nhau ảnh hưởng tới performance, testability, và behavior subtle.

Bài này phân tích 3 annotation ở mức bản chất, giải thích vì sao @Configuration class bị Spring enhance bằng CGLIB, sự khác biệt giữa "lite mode" và "full mode", @Import cho composition config, filter mode của @ComponentScan, family @ConditionalOn*, và cách tự define meta-annotation cho domain.

1. Bảng tổng kết — 3 cách

Phân biệt nhanh:

• "Tôi có class OrderService của tôi viết, muốn nó thành bean" → @Service (sub-class của @Component).
• "Tôi cần bean DataSource từ Hikari (third-party)" → @Bean method trong class @Configuration.
• "Tôi muốn nhóm các @Bean method cùng concern" → @Configuration class.

2. @Component và stereotypes

@Component là annotation gốc — đánh dấu class là Spring-managed bean để component scan tìm thấy.

@Component
public class EmailValidator {
    public boolean isValid(String email) { /* ... */ }
}

Spring có 3 alias chuyên biệt theo layer, gọi là stereotype annotations:

flowchart TB
    Component["@Component<br/>(generic stereotype)"]
    Service["@Service"]
    Repository["@Repository"]
    Controller["@Controller"]
    RestController["@RestController"]

    Component --> Service
    Component --> Repository
    Component --> Controller
    Controller --> RestController

    style Component fill:#fef3c7

Tất cả đều @Component ở mức code (annotation chain). Component scan tìm cả 4 đều gom vào bean.

Quy tắc thực dụng: chọn stereotype rõ nhất theo layer. Đừng dùng @Component trần khi class có vai trò rõ ràng:

@Service
public class OrderService { ... }       // dung — business layer

@Repository
public class OrderRepository { ... }    // dung — data layer

@Component                                // dung — utility class generic, khong fit layer nao
public class JsonSchemaValidator { ... }

Lợi ích phụ: developer khác đọc code biết ngay class này thuộc layer nào, không phải đọc body.

2.1 Bean naming conventions

Khi @Component không khai báo name, Spring tự sinh:

Spring dùng Introspector.decapitalize để sinh name — chuyển chữ đầu lowercase trừ khi 2 chữ đầu đều uppercase.

Khai báo name explicit:

@Service("orderProcessor")           // override default
public class OrderService { ... }

@Bean("dataSource")                  // override default = methodName
public DataSource buildDataSource() { ... }

Bean name unique trong cùng context. Trùng → từ Spring Boot 2.1 throw BeanDefinitionOverrideException (override mặc định tắt — spring.main.allow-bean-definition-overriding=false).

3. @Bean method — khi class không thuộc về bạn

@Component yêu cầu bạn annotate class. Nhưng nhiều khi bean cần là class third-party — bạn không sửa source được:

@Configuration
public class DataSourceConfig {

    @Bean
    public DataSource dataSource(@Value("${db.url}") String url,
                                  @Value("${db.user}") String user,
                                  @Value("${db.pass}") String pass) {
        var ds = new HikariDataSource();
        ds.setJdbcUrl(url);
        ds.setUsername(user);
        ds.setPassword(pass);
        ds.setMaximumPoolSize(20);
        return ds;
    }

    @Bean
    public ObjectMapper objectMapper() {
        return new ObjectMapper()
            .registerModule(new JavaTimeModule())
            .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
    }
}

Phân tích:

• Method được annotate @Bean. Method return object — đó là bean.
• Bean name mặc định = method name (dataSource, objectMapper).
• Bean class = return type khai báo (DataSource, ObjectMapper).
• Method parameter cũng được Spring inject — @Value resolve từ properties.

Use case của @Bean:

3.1 Lifecycle qua @Bean

@Bean cho phép cấu hình lifecycle method:

@Bean(initMethod = "start", destroyMethod = "stop")
public CacheCluster cacheCluster() { return new CacheCluster(); }

@Bean(destroyMethod = "")     // tat destroy method tu (inferred)
public DataSource dataSource() { return new HikariDataSource(); }

Spring tự deduce destroyMethod cho:

• Method close() (Closeable/AutoCloseable).
• Method shutdown().

Nếu bạn không muốn Spring gọi auto, set destroyMethod = "" (empty string).

@Bean cũng support @Lazy, @Scope, @DependsOn, @Primary, @Qualifier cùng vị trí:

@Bean
@Lazy
@Scope("prototype")
@Qualifier("readReplica")
public DataSource readReplica() { ... }

4. @Configuration — không chỉ là container của @Bean

@Configuration là @Component đặc biệt với 1 super-power: Spring enhance class này bằng CGLIB để intercept @Bean method call. Đây là điểm thiết yếu mà 80% dev không biết.

4.1 Vấn đề @Bean trong "lite mode"

public class LiteConfig {                    // KHONG @Configuration

    @Bean
    public Foo foo() { return new Foo(); }

    @Bean
    public Bar bar() {
        return new Bar(foo());                // goi method foo() truc tiep
    }
}

Đoạn này không có @Configuration. Spring vẫn process @Bean method (lite mode), nhưng không enhance class. Kết quả:

• foo() được Spring gọi 1 lần để tạo bean foo.
• Khi bar() được Spring gọi tạo bean bar, code new Bar(foo()) chạy — nhưng foo() ở đây là gọi method Java thuần, không qua Spring. Kết quả: tạo 1 instance Foo mới, khác với bean foo đã đăng ký.
• Bạn có 2 instance Foo trong app: 1 do Spring quản, 1 nằm bên trong Bar. Bug subtle.

4.2 @Configuration với CGLIB enhancement

@Configuration
public class FullConfig {

    @Bean
    public Foo foo() { return new Foo(); }

    @Bean
    public Bar bar() {
        return new Bar(foo());                // call duoc intercept
    }
}

Có @Configuration, Spring tạo CGLIB subclass của FullConfig với các @Bean method override. Override logic: kiểm tra container có bean đó chưa — có thì return bean cache, không thì call method gốc.

Kết quả: foo() trong body bar() trả về cùng instance với bean foo đã đăng ký. Chỉ 1 instance Foo trong app.

sequenceDiagram
    participant Ctx as Container
    participant Cfg as FullConfig$$EnhancerByCGLIB
    participant Real as FullConfig (real)

    Ctx->>Cfg: bar()
    Cfg->>Cfg: foo() invoked
    alt foo bean exists in cache
        Cfg-->>Cfg: return cached foo
    else first time
        Cfg->>Real: foo() (super call)
        Real-->>Cfg: new Foo()
        Cfg->>Ctx: register as bean foo
    end
    Cfg->>Real: bar() body with foo
    Real-->>Ctx: return Bar

Đây là lý do reference docs Spring luôn khuyến nghị annotate class chứa @Bean bằng @Configuration:

4.3 Hệ quả của CGLIB enhancement

• Class @Configuration không được final — CGLIB không subclass được class final → throw tại startup.
• Method @Bean không được private/final — không override được.
• Hơi tốn memory — 1 class CGLIB subclass cho mỗi config class. Negligible với app thường, đáng cân nhắc cho app native image.
• Spring 5.2+ thêm proxyBeanMethods = false: tắt CGLIB enhancement nếu bạn chắc chắn không gọi method @Bean lẫn nhau:

@Configuration(proxyBeanMethods = false)
public class FastConfig {

    @Bean
    public Foo foo() { return new Foo(); }

    @Bean
    public Bar bar(Foo foo) {                  // inject qua parameter, KHONG goi foo() body
        return new Bar(foo);
    }
}

Ưu điểm: faster startup (no CGLIB), better cho native image. Nhược: bạn phải kỷ luật — mọi dependency qua method parameter, không qua method call.

Spring Boot 2.2+ tự annotate proxyBeanMethods = false cho hầu hết autoconfig — cho native-friendly.

5. @ComponentScan — chi tiết filter modes

Default @ComponentScan quét mọi class có @Component (hoặc stereotype). Customize qua filter:

@Configuration
@ComponentScan(
    basePackages = {"com.olhub.domain", "com.olhub.api"},
    includeFilters = {
        @ComponentScan.Filter(type = FilterType.ANNOTATION, classes = MyService.class),
        @ComponentScan.Filter(type = FilterType.ASSIGNABLE_TYPE, classes = Repository.class)
    },
    excludeFilters = {
        @ComponentScan.Filter(type = FilterType.REGEX, pattern = ".*Test.*"),
        @ComponentScan.Filter(type = FilterType.ANNOTATION, classes = Deprecated.class)
    },
    useDefaultFilters = false                      // chi dung includeFilters, bo qua @Component default
)
public class AppConfig { }

5 filter type:

Default Spring Boot dùng @SpringBootApplication với @ComponentScan không filter — đủ 99% case.

5.1 Khi nào dùng filter

Hiếm — default đủ. Nhưng có vài case:

• Test bypass production bean: excludeFilters để bỏ @Configuration của production khi test slice.
• Module isolation: lib module muốn scan riêng package — không pull bean từ module khác.
• Plugin architecture: chỉ scan plugin có annotation @MyPlugin, không bean thường.

6. @Import — composition của config

@Configuration có thể @Import config khác:

@Configuration
@Import({DataSourceConfig.class, SecurityConfig.class, MessagingConfig.class})
public class AppConfig {
    // ...
}

Tương đương khai báo 4 config class với @SpringBootApplication. Khác @ComponentScan:

Spring Boot autoconfig không dùng @ComponentScan — nó dùng @Import qua file META-INF/spring/...AutoConfiguration.imports. Lý do: autoconfig phải explicit, không phụ thuộc package layout.

@Import cũng accept ImportSelector (logic chọn class config động) và ImportBeanDefinitionRegistrar (register bean programmatically). Đây là cơ chế của @EnableJpaRepositories, @EnableScheduling, ... — Module 02 đào sâu.

7. Conditional bean — feature mạnh của Spring Boot

Spring Boot mở rộng @Bean với @Conditional* — register bean tuỳ điều kiện:

@Configuration
public class CacheConfig {

    @Bean
    @ConditionalOnClass(name = "org.springframework.data.redis.core.RedisTemplate")
    public CacheManager redisCacheManager() {
        return new RedisCacheManager(/* ... */);
    }

    @Bean
    @ConditionalOnMissingBean(CacheManager.class)
    public CacheManager fallbackCacheManager() {
        return new ConcurrentMapCacheManager();
    }

    @Bean
    @ConditionalOnProperty(name = "feature.audit.enabled", havingValue = "true")
    public AuditLogger auditLogger() {
        return new DefaultAuditLogger();
    }
}

Family @ConditionalOn* đầy đủ:

Đây là cốt lõi của Spring Boot auto-configuration — Module 02 sẽ đào sâu. Bài này chỉ cần biết: @Bean + condition là cách Spring Boot adapt với classpath/config.

7.1 Custom @Conditional

Tự define condition:

public class OnLinuxCondition implements Condition {
    public boolean matches(ConditionContext ctx, AnnotatedTypeMetadata md) {
        return System.getProperty("os.name").toLowerCase().contains("linux");
    }
}

@Configuration
public class FilesystemConfig {
    @Bean
    @Conditional(OnLinuxCondition.class)
    public FileSystemMonitor inotifyMonitor() { ... }
}

Hữu ích cho domain-specific condition (vd "chỉ load bean nếu license valid").

8. Meta-annotation — tự define stereotype

Bạn có thể tạo annotation custom inherit từ @Component:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Component
@Transactional
public @interface DomainService {
    @AliasFor(annotation = Component.class) String value() default "";
}

// Su dung:
@DomainService
public class OrderService { ... }      // = @Component + @Transactional + naming

Spring nhận diện meta-annotation qua chain. OrderService được scan thành bean (do @Component chain) và auto-tx (do @Transactional chain).

Use case:

• Domain-specific stereotype: @DomainService, @ApplicationService, @DomainEvent cho DDD codebase.
• Cross-cutting concern: @Loggable = @Component + AOP advice cho logging.
• Short-hand: tránh lặp @Service @Validated @Transactional 200 lần.

@AliasFor map attribute từ meta-annotation sang annotation lồng — giữ contract API.

9. Khi nào dùng cái nào — quyết định

flowchart TD
    Start[Toi can declare bean]
    Q1{Class la cua toi?}
    Q2{Co fit layer service/repo/controller?}
    UseStereotype["@Service / @Repository / @Controller"]
    UseComponent["@Component"]
    Q3{Co nhieu bean cung group?}
    UseConfiguration["@Configuration class<br/>+ @Bean methods"]
    UseBeanInExisting["@Bean method<br/>trong @Configuration co san"]

    Start --> Q1
    Q1 -->|Co| Q2
    Q2 -->|Co| UseStereotype
    Q2 -->|Khong| UseComponent
    Q1 -->|Khong third-party| Q3
    Q3 -->|Co| UseConfiguration
    Q3 -->|It, 1-2 bean| UseBeanInExisting

Quy tắc rút gọn:

• Class của bạn? → stereotype phù hợp layer. Mặc định @Service cho business logic.
• Class third-party? → @Bean method.
• Nhiều bean cùng group (DataSource + Flyway + JPA config)? → tách @Configuration class riêng, ví dụ DatabaseConfig.
• 1-2 bean? → bỏ vào @Configuration có sẵn (vd ngay trong @SpringBootApplication class — nó đã là @Configuration).

10. Pitfall tổng hợp

❌ Nhầm 1: Quên @Configuration cho class chứa @Bean gọi nhau.

public class MyConfig {           // KHONG @Configuration
    @Bean Foo foo() { return new Foo(); }
    @Bean Bar bar() { return new Bar(foo()); }   // 2 instance Foo trong app
}

✅ Thêm @Configuration, hoặc đổi sang @Bean Bar bar(Foo foo) (param injection).

❌ Nhầm 2: Class @Configuration là final.

@Configuration
public final class C { ... }   // CGLIB khong subclass duoc → startup fail

✅ Bỏ final, hoặc dùng proxyBeanMethods = false.

❌ Nhầm 3: @Bean method private/final.

@Configuration class C {
    @Bean private Foo foo() { ... }   // Spring khong override duoc
}

✅ Method public hoặc protected.

❌ Nhầm 4: Annotate @Service cho class third-party.

@Service                          // BAN khong sua source HikariDataSource duoc
public class HikariDataSource { ... }

✅ Class third-party → @Bean method trong config.

❌ Nhầm 5: Đặt @Component cho class chỉ chứa method static utility.

@Component
public class StringUtils {
    public static String camelCase(String s) { ... }
}

✅ Class util tĩnh không cần Spring quản. Bỏ @Component. Hoặc convert thành bean với instance method nếu cần inject dep.

❌ Nhầm 6: Inject @Configuration class qua @Autowired để gọi @Bean method.

@Service class S {
    @Autowired MyConfig cfg;
    public void use() { Foo f = cfg.foo(); }   // anti-pattern
}

✅ Inject bean Foo thẳng. Không dùng config class như factory runtime.

❌ Nhầm 7: @ComponentScan overlap nhiều basePackages.

@ComponentScan(basePackages = {"com.olhub", "com.olhub.api"})   // bao trum

✅ Chỉ scan rộng nhất — com.olhub đã bao gồm com.olhub.api. Khai báo lồng nhau dư thừa và scan trùng.

❌ Nhầm 8: Quên useDefaultFilters = false khi chỉ muốn includeFilters custom.

@ComponentScan(includeFilters = @Filter(MyMarker.class))
// VAN scan tat ca @Component default + class co MyMarker

✅ Set useDefaultFilters = false để chỉ scan theo includeFilters.

11. 📚 Deep Dive Spring Reference

12. Tóm tắt

• @Component + stereotypes (@Service, @Repository, @Controller): annotate class bạn sở hữu để component scan gom thành bean.
• @Bean method: tạo bean từ method, dùng cho class third-party hoặc cần config phức tạp. Support initMethod/destroyMethod/@Lazy/@Scope.
• @Configuration class: container của @Bean method. Spring enhance bằng CGLIB để @Bean method gọi nhau trả cùng instance ("full mode").
• Không có @Configuration → "lite mode" → method @Bean gọi nhau tạo instance mới mỗi lần (bug subtle).
• @Configuration class không được final; method @Bean không được private/final.
• proxyBeanMethods = false tắt CGLIB cho startup nhanh hơn (Boot autoconfig dùng), với điều kiện không gọi method @Bean lẫn nhau trong body.
• @Repository đặc biệt: thêm exception translation từ JDBC/JPA về DataAccessException.
• Bean name mặc định = class name decapitalize (OrderService → orderService). Trùng → throw BeanDefinitionOverrideException từ Spring Boot 2.1+.
• @ComponentScan có 5 filter type — default đủ 99% case.
• @Import cho composition explicit — Spring Boot autoconfig dùng @Import qua AutoConfiguration.imports, không scan.
• @Conditional* family (12+ annotation) cho phép register bean tuỳ classpath/property/profile — cốt lõi của Spring Boot auto-configuration.
• Meta-annotation + @AliasFor cho phép tự define stereotype domain-specific (@DomainService).
• Class util tĩnh không cần annotate Spring.

13. Tự kiểm tra

@Configuration
class Cfg {
  @Bean Counter counter() { return new Counter(); }
  @Bean Worker worker() { return new Worker(counter()); }
}

@Service
class Auditor {
  @Autowired Counter counter;
  @Autowired Worker worker;

  public int distinctCounters() {
      return Set.of(counter, worker.getCounter()).size();
  }
}

@Configuration
public class DataSourceConfig {

  @Bean
  @Primary
  @ConfigurationProperties("app.datasource.write")
  public DataSource writeDataSource() {
      return DataSourceBuilder.create().type(HikariDataSource.class).build();
  }

  @Bean
  @Qualifier("read")
  @ConfigurationProperties("app.datasource.read")
  public DataSource readDataSource() {
      return DataSourceBuilder.create().type(HikariDataSource.class).build();
  }
}

@Service
public class OrderService {
  private final DataSource write;
  private final DataSource read;

  public OrderService(DataSource write,                          // @Primary - default
                      @Qualifier("read") DataSource read) {      // explicit qualifier
      this.write = write;
      this.read = read;
  }
}

app.datasource.write.url=jdbc:postgresql://primary/app
app.datasource.write.username=app
app.datasource.read.url=jdbc:postgresql://replica/app
app.datasource.read.username=app_ro

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Service
@Validated
@Transactional
public @interface DomainService {
  @AliasFor(annotation = Service.class, attribute = "value")
  String value() default "";
}

@DomainService
public class OrderService { ... }    // = @Service @Validated @Transactional

@Configuration
public class CacheConfig {

  @Bean
  @ConditionalOnClass(name = "org.springframework.data.redis.core.RedisTemplate")
  @ConditionalOnProperty(name = "cache.type", havingValue = "redis", matchIfMissing = false)
  public CacheManager redisCacheManager(RedisConnectionFactory factory) { ... }

  @Bean
  @ConditionalOnMissingBean(CacheManager.class)
  public CacheManager fallback() {
      return new ConcurrentMapCacheManager();
  }
}

Bài tiếp theo: Mini-challenge — tự build mini IoC container 80 dòng