MySQL YEAR 字段在 Hibernate 中映射與數據插入技巧

MySQL YEAR 類型與 Java 映射關係

在 MySQL 中，YEAR 類型佔用 1 個字節，範圍為 1901 到 2155。許多開發者在使用 Hibernate 映射時會疑惑：Java 中該用什麼類型對應？常見做法是映射為 java.sql.Date 或 java.time.Year（Java 8+）。

核心問題：如何只插入年份（如 1990），不包含月、日？

若使用 java.sql.Date，其內部以 1900 年為基準（即年份值 = 實際年份 - 1900）。因此，若要插入 1990 年，需構造 new java.sql.Date(90, 0, 1)（月、日設為 1 月 1 日），Hibernate 會自動截取年份部分寫入 YEAR 列。

實戰代碼示例

// Entity 映射
@Column(name = "birth_year", columnDefinition = "YEAR")
private java.sql.Date birthYear;

// 設置年份 1990
entity.setBirthYear(new java.sql.Date(1990 - 1900, 0, 1)); // 90 代表 1990

進階建議：使用 Java 8 Year 類型

若項目使用 Java 8 或以上，推薦配合 Year 類型並編寫自定義 AttributeConverter，實現無損轉換：

@Converter(autoApply = true)
public class YearConverter implements AttributeConverter<Year, Integer> {
    @Override
    public Integer convertToDatabaseColumn(Year attribute) {
        return attribute != null ? attribute.getValue() : null;
    }
    @Override
    public Year convertToEntityAttribute(Integer dbData) {
        return dbData != null ? Year.of(dbData) : null;
    }
}

// Entity 中直接使用
@Column(name = "birth_year")
private Year birthYear;

常見坑點提醒

• 時區影響：java.sql.Date 受時區影響，建議在連接字串加上 serverTimezone=UTC 或統一使用 Year 避免偏差。
• 數據校驗：插入前確保年份在 1901~2155 範圍內，否則 MySQL 會報錯或截斷。
• Hibernate 方言：確認方言類正確識別 YEAR 類型（如 MySQL57Dialect 已內置支援）。

掌握上述映射細節，即可在 Hibernate 中優雅地處理 MySQL YEAR 字段，避免月、日干擾，保持數據精簡準確。