一份可速查的 Hibernate 註解大全
在 Spring Data JPA / Hibernate 開發中，註解配置已全面取代 XML。本文系統整理 實體定義、主鍵策略、字段映射、關聯關係 四大類高頻註解，附帶屬性詳解與代碼範例，適合開發時隨查隨用。
一、核心實體註解
| 註解 | 作用 | 關鍵屬性 |
|---|
@Entity | 聲明持久化實體類 | name（實體名，默認類名） |
@Table | 指定映射表名、目錄、Schema | name, catalog, schema, uniqueConstraints |
@Id | 標識主鍵字段 | 無 |
二、字段映射：@Column 詳解
@Column(
name = "username", // 列名（默認屬性名）
unique = false, // 唯一約束
nullable = false, // 允許 NULL
insertable = true, // 包含在 INSERT
updatable = true, // 包含在 UPDATE
columnDefinition = "", // 自定義 DDL 片段（跨庫慎用）
table = "", // 次表名（多表映射）
length = 255, // 字符串長度
precision = 0, // 數值精度
scale = 0 // 小數位數
)
三、主鍵生成策略大全
1. JPA 標準：@GeneratedValue
| 策略 | 含義 | 適用場景 |
|---|
AUTO | 由持久化提供者決定 | 通用，開發期 |
IDENTITY | 數據庫自增（MySQL/SQL Server） | 不支持 Sequence 的庫 |
SEQUENCE | 數據庫序列（Oracle/PostgreSQL） | 需配合 @SequenceGenerator |
TABLE | 專用表模擬序列 | 跨庫兼容，性能較差 |
2. Hibernate 擴展：@GenericGenerator 13 種策略
| 策略名 | 特點 | 典型用法 |
|---|
native | 跨庫自適應（Oracle→Sequence, MySQL→Identity） | 最常用，交給數據庫 |
uuid | 128位 UUID → 32位十六進制字符串 | 分布式系統，空間佔用大 |
assigned | 應用程序手動分配 | 業務主鍵，等同 JPA AUTO |
identity | MySQL/SQL Server 自增 | 不可用於 Oracle |
sequence | 調用數據庫 Sequence | 需指定 sequence 名稱 |
hilo / seqhilo | Hi/Lo 算法優化 | 高併發寫入，較少用 |
increment | 單進程內存計數器 | 集群禁用 |
foreign | 共享關聯實體主鍵 | 一對一主鍵關聯 |
guid | 數據庫原生 GUID 函數 | MySQL uuid(), SQL Server newid() |
uuid.hex | 同 uuid，建議用 uuid 替代 | - |
sequence-identity | 立即檢索 Sequence 值 | 需 JDBC 3.0+ |
3. 組合範例
// 方案 A：native（推薦）
@GeneratedValue(generator = "nativeGen")
@GenericGenerator(name = "nativeGen", strategy = "native")
private Long id;
// 方案 B：Oracle Sequence
@GeneratedValue(generator = "seqGen")
@GenericGenerator(name = "seqGen", strategy = "sequence",
parameters = @Parameter(name = "sequence", value = "SEQ_USER"))
private Long id;
// 方案 C：一對一共享主鍵
@Id
@GeneratedValue(generator = "foreignGen")
@GenericGenerator(name = "foreignGen", strategy = "foreign",
parameters = @Parameter(name = "property", value = "userInfo"))
@OneToOne
@PrimaryKeyJoinColumn
private UserInfo userInfo;
四、關聯關係映射
1. 一對一 @OneToOne
| 方式 | 主表配置 | 從表配置 | 特點 |
|---|
| 主鍵共享 | @OneToOne @PrimaryKeyJoinColumn | 無主鍵註解 | 主鍵值完全一致 |
| 外鍵關聯 | @OneToOne @JoinColumn(name="fk_col") | @OneToOne(mappedBy="主表屬性") | 最常用，@JoinColumn 可省（默認 屬性名_主鍵名） |
| 中間表 | @OneToOne @JoinTable(...) | @OneToOne(mappedBy="...") | 解耦，適用雙向可選 |
2. 多對一 @ManyToOne（從表視角）
// 單向
@ManyToOne(cascade = {PERSIST, MERGE})
@JoinColumn(name = "dept_id")
private Department department;
// 雙向（配合 @OneToMany mappedBy）
@ManyToOne
@JoinColumn(name = "dept_id")
private Department department;
3. 一對多 @OneToMany（主表視角）
| 方式 | 配置要點 | 外鍵維護方 | 備註 |
|---|
| mappedBy（推薦） | @OneToMany(mappedBy="department") | 從表（@ManyToOne 端） | 雙向關聯，不產生額外表 |
| @JoinColumn | @OneToMany @JoinColumn(name="dept_id") | 主表 | 單向，主表控制外鍵 |
| @JoinTable | @OneToMany @JoinTable(...) | 中間表 | 多對多退化形式 |
集合類型：List（保序）、Set（去重）、Map（@MapKey 指定 Key 字段）
4. 級聯與抓取策略
cascade：PERSIST、MERGE、REMOVE、REFRESH、ALL（實務常用 ALL）fetch：LAZY（默認，按需加載）、EAGER（立即加載，慎用）
五、最佳實踐速查
- 主鍵首選
native，跨庫零改動
- 雙向關聯必配
mappedBy，避免雙表維護外鍵
- 集合字段初始化：
private Set<Child> children = new HashSet<>(); 防 NPE
@Column(nullable=false) + Bean Validation @NotNull 雙重保障- 大字段（LOB）單獨映射：
@Lob @Basic(fetch=LAZY)
收藏本文，下次寫 Entity 時再也不用查文檔！📌
