Play Framework Ebean RawSqlBuilder columnMapping 導致查詢空值排查指南

問題現象

使用 RawSqlBuilder.unparsed(sql).columnMapping(...) 手動映射欄位後，Ebean.findList() 返回實體屬性為 null 或預設值，但原生 SQL 直接執行有資料。

常見根因

1. 映射名稱不匹配：columnMapping 的「SQL 別名」→「實體屬性」對應錯誤（區分大小寫、底線/駝峰）。
2. 缺少主鍵映射：Ebean 要求 @Id 欄位必須在映射中，否則無法正確實體化物件。
3. 關聯導航屬性未映射：@ManyToOne 等關聯欄位需映射外鍵欄位（如 user_id），而非關聯物件。
4. SQL 別名與 Java 屬性命名慣例衝突：建議 SQL 統一用 snake_case，映射到 camelCase 屬性。

排查步驟

1. 啟用 Ebean SQL 日誌：ebean.logging.sql=true，檢視實際執行 SQL。
2. 對比 RawSqlBuilder 產生的 RawSql 物件 getColumnMapping() 與實體 @Column 註解。
3. 先用 SqlQuery 執行原生 SQL 映射到 Map<String, Object> 驗證欄位名稱：
   List<Map<String, Object>> rows = Ebean.createSqlQuery(sql).findList();
4. 若 Map 有值但實體為 null，確為映射問題。

最佳實踐範本

String sql = "SELECT u.id AS user_id, u.name AS user_name, u.email " +
             "FROM users u WHERE u.status = :status";

RawSql rawSql = RawSqlBuilder
    .unparsed(sql)
    .columnMapping("user_id", "User.id")      // 實體屬性路徑
    .columnMapping("user_name", "User.name")
    .columnMapping("email", "User.email")
    .create();

List users = Ebean.find(User.class)
    .setRawSql(rawSql)
    .setParameter("status", 1)
    .findList();

官方文件參考

Ebean RawSql 官方指南 — 含完整映射規則、巢狀物件映射、分頁與效能調優。