Spring packagesToScan 實戰指南：告別繁瑣 mapping 配置，實現實體類自動發現

痛點背景：傳統 Hibernate 映射配置的煩惱

在 Spring 2.5.6 之前，整合 Hibernate 需在 sessionFactory 中顯式配置 mappingResources 或 annotatedClasses，每新增一個實體類就要修改 XML，極易遺漏、難維護：

<!-- 傳統痛苦配置 -->
<property name="annotatedClasses">
    <list>
        <value>com.pplus.model.User</value>
        <value>com.pplus.model.Order</value>
        <value>com.pplus.model.Product</value>
        <!-- 每新增實體必須手動添加 -->
    </list>
</property>

packagesToScan：自動掃描的救星

Spring 2.5.6 引入 packagesToScan 屬性（屬於 AnnotationSessionFactoryBean 及其子類），自動掃描指定包下所有帶 @Entity/@Embeddable/@MappedSuperclass 註解的類，實現零配置映射註冊。

實戰配置範例

<bean id="sessionFactory" 
      class="org.springframework.orm.hibernate3.annotation.AnnotationSessionFactoryBean">
    
    <property name="dataSource" ref="dataSource"/>
    
    <property name="namingStrategy">
        <bean class="org.hibernate.cfg.ImprovedNamingStrategy"/>
    </property>
    
    <property name="hibernateProperties">
        <value>
            hibernate.dialect=${hibernate.dialect}
            hibernate.query.substitutions=true 'Y', false 'N'
            hibernate.cache.use_second_level_cache=true
            hibernate.cache.provider_class=org.hibernate.cache.EhCacheProvider
        </value>
    </property>
    
    <!-- 核心配置：自動掃描實體類 -->
    <property name="packagesToScan">
        <list>
            <value>com.pplus.*</value>
            <!-- 注意：寫成 com.pplus.model.* 可能掃描不到，見下文避坑指南 -->
        </list>
    </property>
</bean>

核心參數深度解析

packagesToScan 支持的模式

避坑指南：為什麼 com.pplus.model.* 可能失效？

• 類加載器差異：Spring 掃描依賴 ClassPathScanningCandidateComponentProvider，某些類加載器（如 JBoss 模塊、OSGi）不支持通配符遞歸
• 編譯輸出路徑：確保實體類 .class 文件確實在 target/classes/com/pplus/model/ 下
• 註解缺失：類必須標註 @Entity、@Embeddable 或 @MappedSuperclass
• 包名大小寫：Linux 區分大小寫，包名必須與文件系統完全一致

進階用法與最佳實踐

1. 排除特定類/包

<property name="packagesToScan">
    <list>
        <value>com.pplus.*</value>
    </list>
</property>

<!-- 配合 hibernate 排除 -->
<property name="hibernateProperties">
    <value>
        hibernate.ejb.entitymanager_factory_name=...
        
        hibernate.archive.autodetection=class, hbm
        
    </value>
</property>

2. Spring Boot 時代的自動配置

# application.yml (Spring Boot 2.x/3.x)
spring:
  jpa:
    packages-to-scan: com.pplus.*  # 自動配置 LocalContainerEntityManagerFactoryBean
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQL8Dialect

Spring Boot 內部同樣使用 packagesToScan，但封裝在 LocalContainerEntityManagerFactoryBean 中，配置更簡潔。

3. 多數據源場景下的精準掃描

@Configuration
@EnableJpaRepositories(basePackages = "com.pplus.dao.db1", 
                       entityManagerFactoryRef = "db1EntityManagerFactory")
public class Db1Config {
    
    @Bean
    public LocalContainerEntityManagerFactoryBean db1EntityManagerFactory() {
        LocalContainerEntityManagerFactoryBean emf = new LocalContainerEntityManagerFactoryBean();
        emf.setDataSource(db1DataSource());
        emf.setPackagesToScan("com.pplus.model.db1"); // 僅掃描 db1 相關實體
        emf.setJpaVendorAdapter(new HibernateJpaVendorAdapter());
        return emf;
    }
}

底層原理：ClassPath 掃描機制

AnnotationSessionFactoryBean.afterPropertiesSet()
        │
        ▼
Configuration.class.getPackagesToScan()  →  String[] packages
        │
        ▼
ClassPathScanningCandidateComponentProvider
        │
        ├── 構建掃描器 (excludeFilters: 排除非註解類)
        │
        ├── 掃描路徑: packagePath = "com/pplus/**/*.class"
        │
        ├── 讀取 .class 文件字節碼 (ASM 庫，不加載類)
        │
        ├── 檢查是否有 @Entity/@Embeddable/@MappedSuperclass
        │
        └── 收集類名 → Configuration.addAnnotatedClass(className)
        │
        ▼
SessionFactoryBuilder.buildSessionFactory()  ← 註冊所有發現的實體

性能影響與優化建議

常見問題排查清單

1. 實體類是否有 @Entity 註解？
2. 包名是否與 packagesToScan 模式匹配？
3. 是否使用了正確的 SessionFactoryBean 實現類？(AnnotationSessionFactoryBean 或 LocalSessionFactoryBean)
4. 構建輸出目錄是否包含實體類 .class 文件？
5. 日誌級別調至 DEBUG 查看掃描日誌：log4j.logger.org.springframework.orm.hibernate3=DEBUG

總結

packagesToScan 是 Spring 整合 Hibernate 的里程碑式特性，徹底消除了手動維護映射列表的痛苦。核心要點：

• 使用通配符 * 掃描包及子包，推薦 com.yourcompany.*
• 確保實體類帶有 JPA/Hibernate 實體註解
• 多數據源場景精準配置掃描範圍避免衝突
• Spring Boot 時代直接用 spring.jpa.packages-to-scan

掌握這一特性，能讓你的持久層配置更乾淨、更彈性、更易維護。