深入理解 @ComponentScan：Spring 如何發現并管理 Bean？

在 Spring Boot 開發中，自動掃描和注冊組件 是一個非常重要的機制，它決定了 Spring 容器如何發現并管理你的類。而 @ComponentScan 就是實現這一機制的核心工具之一。

本篇文章將用最容易理解的方式，結合類比、實際案例和底層原理，幫助你徹底搞懂 @ComponentScan 的作用和邏輯。

一、為什么需要 @ComponentScan？

Spring 是一個依賴注入（DI）框架，它的核心思想是讓容器去管理對象，而不是手動創建對象。但問題是：

?? Spring 容器怎么知道哪些類應該被管理呢？

有兩種方式告訴 Spring 該管理哪些類：

1. 手動注冊（@Bean 或 XML 配置）

   @Configuration
   public class AppConfig {
       @Bean
       public MyService myService() {
           return new MyService();
       }
   }
   

   這種方式比較繁瑣，需要手動定義每個 Bean。

2. 自動掃描（@ComponentScan + @Component 系列注解）

   @Component
   public class MyService {
   }
   

   @ComponentScan 負責掃描并自動注冊所有標注了 @Component 及其派生注解的類（如 @Service、@Controller、@Repository 等）。

二、@ComponentScan 的作用

1. 基本作用

• @ComponentScan 告訴 Spring 容器應該掃描哪些包，查找哪些類，并自動注冊為 Spring Bean。
• 只會掃描標注了 @Component 及其派生注解 的類，例如：
  • @Component —— 通用組件
  • @Service —— 業務邏輯組件
  • @Repository —— 數據訪問層組件
  • @Controller / @RestController —— Web 控制器組件

2. 直觀類比

你可以把 Spring 容器想象成一個托兒所，它負責照顧小朋友（Bean），但首先它需要知道有哪些孩子。

• @ComponentScan 就像是托兒所的招生公告，告訴老師們去哪些社區里招收孩子（掃描哪些包）。
• @Component（及其派生注解）就像孩子的報名表，只有填寫報名表的孩子才會被托兒所接收（被注冊為 Bean）。

如果 @ComponentScan 沒有正確指定包，就相當于托兒所老師不知道該去哪招生，結果可能會漏掉一些孩子（Bean 不能被 Spring 管理）。

三、@ComponentScan 的用法

1. 默認行為

如果 @ComponentScan 沒有指定任何參數，它會默認掃描當前類所在包及其子包：

@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

等價于：

@ComponentScan(basePackages = "com.example")
@SpringBootApplication
public class MyApplication {
}

默認情況下，@SpringBootApplication 自帶 @ComponentScan，它會掃描當前包及子包下的所有 @Component 類。

2. 自定義掃描包

如果你的組件（Bean）不在 @SpringBootApplication 默認掃描的包里，你需要手動指定 @ComponentScan：

@ComponentScan(basePackages = {"com.example.service", "com.example.dao"})
@SpringBootApplication
public class MyApplication {
}

這樣，Spring 就會去 com.example.service 和 com.example.dao 里找 @Component 組件。

3. 只掃描特定類型的 Bean

有時候你可能不想掃描所有的 @Component，可以使用 includeFilters 和 excludeFilters：

@ComponentScan(
    basePackages = "com.example",
    includeFilters = @ComponentScan.Filter(type = FilterType.ANNOTATION, classes = Service.class),
    excludeFilters = @ComponentScan.Filter(type = FilterType.ANNOTATION, classes = Repository.class)
)

• 這樣只會掃描 @Service，但不會掃描 @Repository。

四、底層實現

@ComponentScan 的核心邏輯在 ClassPathBeanDefinitionScanner 里。

Spring 啟動時：

1. @ComponentScan 解析出所有要掃描的包。
2. ClassPathBeanDefinitionScanner 在這些包里查找 @Component 及其派生注解的類。
3. 找到后，Spring 容器將它們注冊為 BeanDefinition，最終變成 Spring Bean。

五、結合 @SpringBootApplication 看整體流程

@SpringBootApplication 其實是一個組合注解：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@SpringBootConfiguration
@EnableAutoConfiguration
@ComponentScan
public @interface SpringBootApplication {
}

• @ComponentScan：自動掃描當前包及子包中的組件
• @EnableAutoConfiguration：自動配置 Spring Boot 需要的 Bean
• @SpringBootConfiguration：標識當前類為配置類

所以，當你寫：

@SpringBootApplication
public class MyApplication {
}

實際上已經隱式包含了：

@ComponentScan(basePackages = "com.example") // 默認掃描當前包
@EnableAutoConfiguration // 自動加載 Spring Boot 相關配置

六、總結

Spring Bean 掃描的核心流程

1. @ComponentScan 確定要掃描的包
2. ClassPathBeanDefinitionScanner 找到 @Component 及其派生注解
3. Spring 把這些類注冊為 Bean
4. Spring 容器可以在整個應用中管理和使用這些 Bean

七、FAQ（常見問題解答）

1. 為什么 @SpringBootApplication 會默認掃描 main 方法所在包？

因為 @SpringBootApplication 里面包含 @ComponentScan，默認掃描它所在的包及其子包。

2. 如果我的 Bean 不在 @SpringBootApplication 默認掃描的包里怎么辦？

可以手動指定 @ComponentScan：

@ComponentScan(basePackages = "com.other.package")
@SpringBootApplication
public class MyApplication {
}

3. @ComponentScan 會掃描 @Configuration 標注的類嗎？

是的，@Configuration 也是 @Component 的子注解，會被掃描并注冊。

八、后記

理解 @ComponentScan，你就掌握了Spring Bean 是如何被發現和注冊的，也能更靈活地管理 Spring Boot 項目的結構。希望這篇文章對你有所幫助！ ??