Stereotype & @ComponentScan — cơ chế scan biến class thành bean

TL;DR: @Component là annotation đánh dấu "class này là Spring bean, hãy scan tôi". @ComponentScan đọc classpath, tìm mọi class có @Component (hoặc stereotype kế thừa từ nó), tạo BeanDefinition cho từng class và đăng ký vào beanDefinitionMap — chưa tạo object, chỉ ghi metadata. Trong 4 stereotype, chỉ @Repository có hành vi đặc biệt (exception translation qua PersistenceExceptionTranslationPostProcessor); @Controller được Spring MVC nhận diện để route request; @Service là marker thuần. Tách stereotype có hai lý do thực sự: rõ intent theo layer và AOP pointcut có thể target đúng annotation. Filter mode của @ComponentScan cho phép include/exclude class theo annotation, kiểu, regex, hay custom logic — hữu ích cho test slice và module isolation. Meta-annotation cho phép tự define stereotype như @DomainService = @Component + cross-cutting concern.

1. Vấn đề mà @Component giải quyết

Trước khi có component scan, mọi bean phải khai báo trong XML hoặc @Bean method — tức là mỗi class business phải được đề cập hai lần: một lần viết code, một lần khai báo với container. Với app 500 service/repository, đây là boilerplate không thể bảo trì.

@Component và @ComponentScan giải quyết bằng convention: đặt annotation vào class, Spring tự tìm. Bạn chỉ viết code một lần; container tự biết class đó cần quản lý.

// Truoc annotation-driven: khai bao explicit tung bean
// applicationContext.xml
// <bean id="orderService" class="com.olhub.service.OrderService"/>
// <bean id="paymentService" class="com.olhub.service.PaymentService"/>
// ... 200 dong XML cho 100 class

// Sau @Component + @ComponentScan: khong XML
@Service
public class OrderService { /* ... */ }

@Service
public class PaymentService { /* ... */ }
// Container tu scan va register ca 2

2. Cơ chế bên dưới — scan biến class thành BeanDefinition ra sao

@ComponentScan không scan bytecode raw — nó dùng ClassPathScanningCandidateComponentProvider để đọc metadata annotation mà không load class vào JVM (dùng ASM bytecode reader). Khi tìm thấy class phù hợp, nó tạo ScannedGenericBeanDefinition và đăng ký vào beanDefinitionMap của DefaultListableBeanFactory.

flowchart TB
    CS["@ComponentScan(basePackages)"]
    Scan["ClassPathScanningCandidateComponentProvider<br/>doc bytecode qua ASM, khong load class"]
    Filter{"Co @Component<br/>hoac stereotype?"}
    BD["tao ScannedGenericBeanDefinition<br/>(METADATA ONLY: class, scope, name)"]
    Map["dang ky vao beanDefinitionMap"]
    Skip["bo qua class"]
    Inst["createBean() - chi khi getBean() goi<br/>hoac eager singleton luc startup"]

    CS --> Scan
    Scan --> Filter
    Filter -->|"Co"| BD
    Filter -->|"Khong"| Skip
    BD --> Map
    Map --> Inst

Điểm cốt lõi: sau khi scan xong, container biết "có bean tên orderService, class OrderService" nhưng object OrderService chưa tồn tại trong heap. Instance chỉ được tạo ở pha sau (eager startup với ApplicationContext, hoặc lazy khi getBean với BeanFactory trần) — xem BeanFactory vs ApplicationContext để rõ hai pha này.

Cơ chế ASM (không load class) có lợi quan trọng: container có thể scan toàn bộ classpath mà không khởi động class với static initializer, không tốn memory heap cho class không được dùng.

2.1 @ComponentScan đặt ở đâu

@Configuration
@ComponentScan(basePackages = "com.olhub")
public class AppConfig { }

Hoặc không cần explicit nếu dùng @SpringBootApplication — annotation đó đã bao gồm @ComponentScan với basePackages mặc định là package của class được annotate. Xem thêm tại Resource & @SpringBootApplication.

3. @Component và 4 stereotype

@Component là annotation gốc. Spring cung cấp 4 alias chuyên biệt theo layer — tất cả đều có @Component trong annotation chain:

flowchart TB
    Component["@Component<br/>(annotation goc, generic)"]
    Service["@Service<br/>(business layer)"]
    Repository["@Repository<br/>(data layer)"]
    Controller["@Controller<br/>(web MVC)"]
    RestController["@RestController<br/>(@Controller + @ResponseBody)"]

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

    style Component fill:#fef3c7
    style Repository fill:#dcfce7
    style Controller fill:#dbeafe

Tất cả đều được @ComponentScan gom vào bean — Spring tra annotation chain, không chỉ annotation trực tiếp.

3.1 @Repository và exception translation

@Repository là stereotype duy nhất có hành vi runtime đặc biệt ngoài việc làm bean.

Vấn đề: mỗi persistence framework ném exception riêng — Hibernate ném HibernateException, JDBC ném SQLException, JPA ném PersistenceException. Business code catch những exception này sẽ bị coupling chặt với implementation tầng data.

Giải pháp của Spring: PersistenceExceptionTranslationPostProcessor — một BeanPostProcessor được Spring tự đăng ký — wrap mọi bean annotate @Repository trong AOP proxy. Proxy đó intercept method call và chuyển exception JDBC/JPA/Hibernate thành DataAccessException hierarchy của Spring.

@Repository
public class OrderRepository {

    public Order findById(Long id) {
        // Neu JDBC nem SQLException hoac Hibernate nem HibernateException
        // -> proxy @Repository intercept -> convert thanh DataAccessException
        return em.find(Order.class, id);
    }
}

// Business code chi catch DataAccessException - khong phu thuoc DB driver
@Service
public class OrderService {
    private final OrderRepository repo;

    public Order getOrder(Long id) {
        try {
            return repo.findById(id);
        } catch (DataAccessException e) {
            // Handle loi DB o muc truu tuong - khong biet la JDBC hay JPA
            throw new OrderNotFoundException(id, e);
        }
    }
}

Nếu dùng @Component thay @Repository, exception translation vẫn có thể hoạt động nếu implement PersistenceExceptionTranslator, nhưng mất signal intent rõ ràng. Quy tắc đơn giản: tầng data → luôn dùng @Repository.

3.2 @Controller và Spring MVC

Spring MVC's DispatcherServlet chỉ xét @RequestMapping method trên class có @Controller hoặc @RestController. Class @Service dù có @RequestMapping cũng không tạo route — Spring MVC bỏ qua.

@Controller                          // dung - DispatcherServlet xu ly route
public class OrderController {
    @GetMapping("/orders/{id}")
    public String detail(@PathVariable Long id, Model model) { /* ... */ }
}

@Service                             // SAI cho web route - DispatcherServlet bo qua
public class OrderService {
    @GetMapping("/orders/{id}")      // annotation nay khong co tac dung
    public void wrong() { }
}

@RestController = @Controller + @ResponseBody trên toàn class — mọi method return value tự serialize thành JSON/XML thay vì resolve view name.

4. Vì sao tách stereotype — không chỉ code style

Câu hỏi thường gặp: nếu container treat tất cả stereotype như @Component, tại sao không dùng @Component cho hết?

Có hai lý do kỹ thuật thực sự:

Lý do 1 — AOP pointcut target chính xác theo layer. Annotation là metadata runtime — AOP aspect có thể match annotation cụ thể:

// Chi wrap transaction quanh method cua @Repository bean
@Around("@within(org.springframework.stereotype.Repository)")
public Object auditDataAccess(ProceedingJoinPoint pjp) throws Throwable {
    long start = System.currentTimeMillis();
    try {
        return pjp.proceed();
    } finally {
        log.debug("Data access took {}ms", System.currentTimeMillis() - start);
    }
}

// Chi log vao business boundary - chi service bean
@Before("@within(org.springframework.stereotype.Service)")
public void logServiceEntry(JoinPoint jp) {
    log.info("Service call: {}", jp.getSignature());
}

Nếu mọi class dùng @Component, aspect phải match tên class hoặc package — giòn, phụ thuộc naming convention. Match theo stereotype annotation rõ ràng hơn và không phá khi rename package.

Lý do 2 — @Repository có exception translation. Đã giải thích ở §3.1 — đây là hành vi runtime, không chỉ intent.

Lý do 3 — Intent tài liệu cho người đọc code và tool. IDE, static analysis tool, architecture rule checker (ArchUnit) có thể enforce "layer A không import từ layer B" dựa trên stereotype annotation. Dùng @Component trần mất khả năng kiểm tra tự động này.

5. @ComponentScan filter modes

@ComponentScan với default filter scan mọi class có @Component (hoặc stereotype). Customize qua includeFilters/excludeFilters:

@Configuration
@ComponentScan(
    basePackages = "com.olhub",
    includeFilters = {
        @ComponentScan.Filter(
            type = FilterType.ANNOTATION,
            classes = MyPlugin.class          // chi scan class co @MyPlugin
        )
    },
    excludeFilters = {
        @ComponentScan.Filter(
            type = FilterType.REGEX,
            pattern = ".*IntegrationTest"     // bo qua class ten ket thuc IntegrationTest
        ),
        @ComponentScan.Filter(
            type = FilterType.ANNOTATION,
            classes = Deprecated.class        // bo qua class @Deprecated
        )
    },
    useDefaultFilters = false                 // tat scan @Component default
)
public class PluginConfig { }

5 filter type:

Khi nào dùng filter: 99% app không cần. Các case thực tế:

• Test slice: excludeFilters bỏ @Configuration production khi viết @WebMvcTest hay @DataJpaTest — Spring Boot tự làm trong các slice annotation, không cần tự config.
• Module isolation: library muốn scan package riêng, không pull bean từ consumer package.
• Plugin architecture: chỉ scan class có @MyPlugin, không scan bean bình thường.
• useDefaultFilters = false cần thiết khi chỉ muốn includeFilters custom — nếu không set, default filter vẫn scan @Component song song, kết quả là scan cả hai.

6. Meta-annotation — tự định nghĩa stereotype

Spring resolve annotation theo chain — annotation đặt trên annotation khác cũng được tính. Điều này cho phép tự tạo stereotype tổng hợp:

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

// Su dung:
@DomainService
public class OrderService { /* ... */ }
// Tuong duong viet @Service @Transactional tren class

@DomainService có @Service trong chain → được scan như @Component. Có @Transactional trong chain → được AOP proxy wrap cho transaction. @AliasFor map attribute value từ @DomainService sang @Service.value — giữ bean naming convention.

Spring dùng AnnotationUtils.findAnnotation() và MergedAnnotations API để traverse chain annotation bất kỳ độ sâu. Đây là cơ chế cho phép @SpringBootApplication = @SpringBootConfiguration + @EnableAutoConfiguration + @ComponentScan hoạt động như một annotation gộp.

Use case thực tế:

// DDD codebase: phan biet Application Service vs Domain Service
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Service
@Transactional(readOnly = true)   // query service: default read-only tx
public @interface ApplicationService {
    @AliasFor(annotation = Service.class, attribute = "value")
    String value() default "";
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Service
@Transactional                    // domain service: full read-write tx
public @interface DomainService {
    @AliasFor(annotation = Service.class, attribute = "value")
    String value() default "";
}

// Su dung:
@ApplicationService
public class OrderQueryService {      // chi query, tx read-only
    public Order findById(Long id) { /* ... */ }
}

@DomainService
public class OrderCommandService {    // co write, tx read-write
    public void placeOrder(Order o) { /* ... */ }
}

Quy tắc dùng meta-annotation: chỉ define khi pattern lặp lại từ 5 class trở lên. Codebase nhỏ hơn — explicit annotation dễ đọc hơn.

7. Pitfall thường gặp

Pitfall 1 — Bean ngoài basePackages không được scan.

@SpringBootApplication          // @ComponentScan default: package cua class nay
public class OlhubApp { }       // vi du: com.olhub.app

// SAI - bean trong package khac khong duoc scan
package com.olhub.plugin;       // ngoai com.olhub.app
@Service
public class PluginService { }  // KHONG duoc scan - container khong biet co no

// DUNG:
@SpringBootApplication
@ComponentScan(basePackages = {"com.olhub.app", "com.olhub.plugin"})
public class OlhubApp { }

Hoặc di chuyển OlhubApp lên package root com.olhub để mọi subpackage đều trong scan scope.

Pitfall 2 — Nhầm @Service cho class không phải bean Spring.

@Service                          // THUA - khong co dependency nao can inject
public class MathUtils {
    public static int add(int a, int b) { return a + b; }
}

Class chỉ có static method không cần Spring quản. Bỏ annotation — gọi trực tiếp MathUtils.add(1, 2) từ mọi nơi, không cần inject.

Pitfall 3 — @Component cho class third-party.

// KHONG the annotate - ban khong sua source duoc
@Component
public class HikariDataSource { /* ... */ }

Class không thuộc quyền sở hữu của bạn → dùng @Bean method trong @Configuration. Đây là ranh giới chính xác giữa @Component và @Bean — xem @Bean & @Configuration.

Pitfall 4 — Quên @Repository, dùng @Component cho data layer.

@Component                        // co the dung nhung...
public class OrderJdbcRepository {
    public Order findById(Long id) throws SQLException { /* ... */ }
}
// SQLException se KHONG bi translate thanh DataAccessException
// Business code buoc phai catch SQLException - coupling voi JDBC

@Repository                       // DUNG: exception translation hoat dong
public class OrderJdbcRepository {
    public Order findById(Long id) { /* ... */ }
    // SQLException tu dong convert -> DataAccessException
}

Liên hệ các bài khác

• BeanFactory vs ApplicationContext: scan tạo BeanDefinition trong beanDefinitionMap; bài kia giải thích beanDefinitionMap là gì và tại sao nó tách khỏi singletonObjects. Hai bài đọc cùng nhau cho thấy toàn bộ đường đi từ annotation → metadata → object.
• Resource & @SpringBootApplication: @SpringBootApplication bao gồm @ComponentScan với basePackages mặc định — bài đó giải thích tại sao đặt main class ở root package là convention quan trọng, không phải tùy chọn.
• @Bean & @Configuration: hai cách khai báo bean bổ sung nhau — @Component cho class bạn sở hữu, @Bean cho class third-party hoặc cần factory logic. Bài tiếp theo đào sâu cơ chế CGLIB của @Configuration.

Tóm tắt

• @Component đánh dấu class để @ComponentScan tìm thấy và tạo BeanDefinition (metadata) trong beanDefinitionMap — chưa tạo object.
• Scan dùng ASM đọc bytecode, không load class vào JVM — nhanh và không có side effect static initializer.
• 4 stereotype (@Service, @Repository, @Controller, @RestController) đều kế thừa @Component qua annotation chain — đều được scan.
• Chỉ @Repository có hành vi runtime đặc biệt: PersistenceExceptionTranslationPostProcessor wrap bean trong AOP proxy để translate exception JDBC/JPA → DataAccessException.
• @Controller được Spring MVC nhận diện để route @RequestMapping; @Service là marker thuần.
• Tách stereotype có lý do kỹ thuật: AOP pointcut match chính xác theo annotation, exception translation, và tooling enforce layer rule.
• @ComponentScan có 5 filter type (ANNOTATION, ASSIGNABLE_TYPE, ASPECTJ, REGEX, CUSTOM) — 99% app không cần, dùng khi test slice hoặc module isolation.
• Meta-annotation cho phép tự define stereotype tổng hợp (@DomainService = @Service + @Transactional); Spring resolve chain annotation bất kỳ độ sâu.

Tự kiểm tra

@ComponentScan(
  basePackages = "com.olhub",
  includeFilters = @Filter(
      type = FilterType.ANNOTATION,
      classes = MyPlugin.class
  ),
  useDefaultFilters = false   // chi scan theo includeFilters
)

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

Bài tiếp theo: @Bean & @Configuration