利用 MiddleGen-Hibernate-r5 自動產生 HBM 映射檔與 POJO 實體類完整教學

前言

MiddleGen-Hibernate-r5 是早期 Hibernate 2/3 時代常用的代碼生成工具，透過 Ant 腳本讀取資料庫中繼資料，產生 .hbm.xml 映射檔與 Java 實體類。雖已較少用於新專案（現多用 JPA/Hibernate Tools/IDE 外掛），但維護舊系統時仍具參考價值。本文記錄完整環境建置、配置調整、生成流程與常見坑點。

一、前置環境準備

驗證：CMD 執行 ant -version 輸出版本資訊即成功。

二、必要 JAR 套件準備（放入 lib/ 目錄）

1. 產生 HBM 階段

• mysql-connector-java-5.1.11-bin.jar（依資料庫選擇對應驅動）

2. 產生 POJO 階段 (Hibernate 3 相依)

• hibernate3.jar
• dom4j-1.6.1.jar
• hibernate-tools.jar
• freemarker.jar
• slf4j-api-1.5.2.jar, slf4j-jdk14-1.5.2.jar, slf4j-log4j12-1.5.2.jar

來源建議：Hibernate 3.3.1 GA 分發包、HibernateTools 3.2.4 Beta、SLF4J 1.5.2 官網。

三、配置 build.xml 關鍵屬性

1. 資料庫連線設定 (約第 30-50 行)

<property name="database.driver.file" value="${lib.dir}/mysql-connector-java-5.1.11-bin.jar"/>
<property name="database.driver" value="com.mysql.jdbc.Driver"/>
<property name="database.url" value="jdbc:mysql://localhost:3306/your_db?useUnicode=true&characterEncoding=UTF-8"/>
<property name="database.userid" value="root"/>
<property name="database.password" value="your_pwd"/>
<property name="database.schema" value=""/>
<property name="database.catalog" value="your_db"/>
<property name="jboss.datasource.mapping" value="mySQL"/>

注意：驅動類別名、URL 格式需與 JAR 版本對應（MySQL 5.1 用 com.mysql.jdbc.Driver，8.0+ 用 com.mysql.cj.jdbc.Driver）。

2. 輸出目錄

<property name="build.gen-src.dir" value="${basedir}/build/mysrc"/>

預先建立 build/mysrc 目錄。

四、啟動 GUI 介面調整表屬性

執行 ant gui 啟動 Swing 介面，選中資料表後可調整：

五、生成 HBM 映射檔

1. GUI 中 File → Generate → Hibernate Mapping Files。
2. 或命令列：ant hbm（目標名視 build.xml 定義）。
3. 輸出位置：build/mysrc/ 對應套件結構下，檔名 *.hbm.xml。

六、生成 POJO 實體類 (關鍵調整)

1. 複製 POJO 階段 JAR 至 lib/

2. 修改 build.xml 中 hbm2java 目標 (約第 212 行)

<target name="hbm2java" description="Generate .java from .hbm files.">
  <taskdef name="hbm2java"
           classname="org.hibernate.tool.ant.HibernateToolTask"
           classpathref="lib.class.path"/>
  <hbm2java destdir="${build.gen-src.dir}">
    <configuration>
      <fileset dir="${build.gen-src.dir}">
        <include name="**/*.hbm.xml"/>
      </fileset>
    </configuration>
    <hbm2java jdk5="true"/> <!-- 生成 JDK 5 語法 (泛型、註解等) -->
  </hbm2java>
</target>

關鍵變更：classname 改為 org.hibernate.tool.ant.HibernateToolTask (Hibernate 3 專用)，新增 <configuration> 區塊與 jdk5="true"。

3. 修正 HBM 檔 DTD 宣告 (避免舊版警告)

將生成的 *.hbm.xml 開頭：

<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 2.0//EN"
    "https://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

改為：

<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
    "https://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

僅將 2.0 → 3.0，消除 Don't use old DTDs 警告。

4. 執行生成

ant hbm2java

POJO 輸出至 build/mysrc/model/ (依套件結構)。

七、常見問題與解決

Q: ClassNotFoundException: org.hibernate.tool.ant.HibernateToolTask

A: 確認 hibernate-tools.jar 已放入 lib/ 並被 lib.class.path 引用。

Q: 生成的 POJO 缺少 serialVersionUID

A: MiddleGen 預設不生成，手動補充或改用 Hibernate Tools / IDE 外掛可自訂模板。

Q: MySQL 8.0 連線失敗

A: 更新驅動 JAR 至 8.0 版，修改 database.driver 為 com.mysql.cj.jdbc.Driver，URL 加 useSSL=false&serverTimezone=UTC。

Q: 想自訂 POJO 模板 (加 Lombok 註解、Builder 等)

A: MiddleGen 使用 Velocity 模板，可修改 templates/pojo.vm；但建議遷移至 Hibernate Tools (Eclipse/IDEA 外掛) 或 MyBatis Generator，模板化支援更完善。

八、現代替代方案推薦

• Hibernate Tools (Eclipse/IDEA 外掛)：圖形化、支援 JPA 註解、雙向工程、FreeMarker/Velocity 模板。
• MyBatis Generator：XML/Mapper/Entity 一鍵生成，支援插件擴充。
• JPA Buddy (IDEA 付費外掛)：視覺化實體設計、遷移腳本、測試資料生成。
• Spring Boot + JPA + Flyway/Liquibase：以程式碼為主，資料庫遷移版本化，減少反向工程需求。

九、結語

MiddleGen-Hibernate-r5 完成了從資料庫到 HBM/POJO 的自動化橋樑，理解其配置邏輯（Ant、Hibernate Task、DTD 版本）有助於維護舊專案。新專案建議採用現代工具鏈，獲得更好的型別安全、模板彈性與持續整合友善度。