您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

Hibernate 兩大配置格式深度解析：XML vs Properties 差異與初始化陷阱

編輯：Java 相關知識

Hibernate 支援兩種配置格式，預設檔名分別為 hibernate.cfg.xml 與 hibernate.properties。兩者不僅語法不同，初始化 API 更有嚴格對應關係。

格式對比

XML 配置初始化

// 1. 預設檔名 hibernate.cfg.xml 在 classpath 根目錄
Configuration cfg = new Configuration().configure();

// 2. 指定檔名/路徑 (支援相對/絕對路徑、URL)
Configuration cfg = new Configuration().configure("com/myapp/hibernate-mysql.cfg.xml");
Configuration cfg = new Configuration().configure(new File("/opt/config/hibernate.cfg.xml"));
Configuration cfg = new Configuration().configure(new URL("https://config-server/hibernate.cfg.xml"));

迷思破解：網路/書本常說「配置檔必須放在 classpath 根目錄」錯誤。configure(String/URL/File) 可載入任意位置檔案。

Properties 配置初始化

Configuration cfg = new Configuration();
cfg.addClass(User.class);           // 單一實體
cfg.addJar(new File("entities.jar")); // 整個 JAR 掃描
cfg.addDirectory(new File("mappings")); // 目錄下所有 .hbm.xml
cfg.addResource("User.hbm.xml");    // 單一映射檔
cfg.addProperties(props);           // 額外屬性覆蓋

Properties 格式 不支援 addClass() 以外的映射引用方式，所有映射必須透過程式碼註冊。

Configuration 核心 API 速查

特性	hibernate.cfg.xml	hibernate.properties
語法	XML 標籤結構	鍵值對 (key=value)
映射檔引用	`<mapping resource="..."/>`	不支援，需程式碼 `addResource()`
初始化方法	`new Configuration().configure()`	`new Configuration().addClass(Entity.class)`
彈性	高 (支援所有配置項)	低 (僅基本屬性)
適用場景	標準專案、生產環境	快速原型、單元測試

方法	用途
`addCacheableFile(File)`	載入快取過的映射檔 (.bin)
`addClass(Class)`	依慣例載入同包同名 .hbm.xml
`addDirectory(File)`	遞迴載入目錄下所有映射檔
`addDocument(Document)`	從 DOM Document 載入
`addFile(File)`	載入指定 XML 映射檔
`addInputStream(InputStream)`	從輸入流載入
`addJar(File)`	掃描 JAR 內映射檔
`addProperties(Properties)`	合併額外屬性
`addResource(String)`	從 classpath 載入映射檔
`addURL(URL)`	從 URL 載入映射檔
`addXML(String)`	從 XML 字串載入

最佳實踐建議

生產環境統一用 XML：映射檔集中宣告、支援 DTD/XSD 驗證、IDE 智慧提示
測試/原型用 Properties + 程式碼註冊：啟動快、無 XML 解析開銷
多環境配置：hibernate.cfg.xml 放共用設定，環境差異 (連線參數) 用 cfg.addProperties(envProps) 覆蓋
避免混用：同一 SessionFactory 只能選一種初始化方式