Struts2 類型轉換錯誤：CfgUserAreeTermTree 與 CfgUserAreeTermTreeId 混淆排查

錯誤訊息

ccms.entity.CfgUserAreeTermTree cannot be cast to ccms.entity.CfgUserAreeTermTreeId

錯誤本質

嘗試將 實體類別 `CfgUserAreeTermTree` 的實例 強制轉型為 其主鍵類別 `CfgUserAreeTermTreeId`，兩者完全無繼承關係，屬於同包下不同類，直接導致 `ClassCastException`。

常見觸發場景

排查步驟

1. 全局搜尋：IDE 中搜尋 `CfgUserAreeTermTreeId` 所有使用處，重點檢查強制轉型 `(CfgUserAreeTermTreeId)`、泛型聲明 `List`、查詢投影。
2. 檢查實體定義：

   
   // 典型複合主鍵寫法
   @Entity
   @IdClass(CfgUserAreeTermTreeId.class) // 或 @EmbeddedId
   public class CfgUserAreeTermTree {
       @Id String field1;
       @Id String field2;
       // ...
   }
   

   確認主鍵類別名稱拼寫完全一致。
3. 檢查 DAO/Repository 方法簽名：返回類型是否錯誤聲明為實體而實際返回主鍵。
4. 啟用 SQL 日誌：觀察實際執行的查詢是否包含 `select id ...` 而非 `select entity ...`。

最佳實踐：避免此類錯誤

• 主鍵類別命名規範：`PK` 或 `Id`，並在 package-info.java 註明用途。
• DAO 方法嚴格泛型化：`List findAll()`、`PK getId(Entity)`、`Entity findById(PK)`。
• 使用 Spring Data JPA / MyBatis 等成熟框架，減少手寫 HQL/SQL 投影錯誤。
• 單元測試覆蓋查詢轉型邏輯。

快速修正範例

// 錯誤
List list = session.createQuery("select t.id from CfgUserAreeTermTree t").list();

// 正確 1: 查詢完整實體
List list = session.createQuery("from CfgUserAreeTermTree").list();

// 正確 2: 僅需 ID 列表
List ids = session.createQuery("select t.id from CfgUserAreeTermTree t").list();