您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 綜合教學

Hibernate 註解開發完全手冊：核心註解、關聯映射與主鍵策略

編輯：Java 綜合教學

註解開發優勢

JPA 註解 (`javax.persistence.*`) 為標準化規範，可移植性強；Hibernate 專有註解 (`org.hibernate.annotations.*`) 提供增強功能（如 `@Proxy`、`@BatchSize`、`@Where`）。實際項目常**混合使用**：JPA 註解作為基礎，Hibernate 註解補充特有需求。

實體類基礎註解

註解	包	作用	關鍵屬性
@Entity	javax.persistence	聲明持久化實體類	`name`：實體名稱 (HQL 查詢用)
@Entity	org.hibernate.annotations	Hibernate 擴展實體功能	`dynamicUpdate`/`dynamicInsert`、`selectBeforeUpdate`、`polymorphism`
@Table	javax.persistence	指定映射表名、Schema、唯一約束	`name`、`schema`、`catalog`、`uniqueConstraints`
@Proxy	org.hibernate.annotations	類級別延遲加載策略	`lazy=true/false` (默認 true)，`proxyClass`

主鍵與標識符生成

註解	包	說明	典型組合
@Id	javax.persistence	標識主鍵屬性/字段	配合 @GeneratedValue
@GeneratedValue	javax.persistence	主鍵生成策略	`strategy`：AUTO/IDENTITY/SEQUENCE/TABLE
@SequenceGenerator	javax.persistence	定義序列生成器 (Oracle/PostgreSQL)	`name`、`sequenceName`、`allocationSize`
@TableGenerator	javax.persistence	定義表生成器 (通用、可移植)	`name`、`table`、`pkColumnName`、`valueColumnName`
@GenericGenerator	org.hibernate.annotations	Hibernate 通用生成器 (uuid、assigned、hilo 等)	`name`、`strategy`、`parameters`

主鍵策略代碼示例

// 1. 自增 (MySQL/SQL Server)
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

// 2. 序列
@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "seq_gen")
@SequenceGenerator(name = "seq_gen", sequenceName = "SEQ_ID", allocationSize = 1)
private Long id;

// 3. UUID (跨庫無關)
@Id
@GeneratedValue(generator = "uuid")
@GenericGenerator(name = "uuid", strategy = "uuid2")
private String id;

// 4. 表生成器
@Id
@GeneratedValue(strategy = GenerationType.TABLE, generator = "table_gen")
@TableGenerator(name = "table_gen", table = "ID_GEN", pkColumnName = "GEN_KEY", valueColumnName = "GEN_VALUE")
private Long id;

列映射與基本類型

註解	包	作用	常用屬性
@Column	javax.persistence	字段級映射細節	`name`、`nullable`、`unique`、`length`、`precision`、`scale`、`columnDefinition`、`insertable`/`updatable`
@Transient	javax.persistence	標識非持久化屬性 (忽略映射)	無
@Temporal	javax.persistence	日期時間類型映射	`value`：DATE/TIME/TIMESTAMP
@Enumerated	javax.persistence	枚舉類型映射	`value`：ORDINAL/STRING
@Lob	javax.persistence	大對象映射 (Blob/Clob)	配合 @Basic(fetch=LAZY)
@Formula	org.hibernate.annotations	衍生屬性 (SQL 片段計算)	`value`：SQL 表達式

關聯映射註解

多對一 (@ManyToOne)

@ManyToOne(targetEntity = Hotel.class, fetch = FetchType.LAZY)
@JoinColumn(name = "hotel_no", nullable = false, foreignKey = @ForeignKey(name = "FK_ROOM_HOTEL"))
private Hotel hotel;

`targetEntity`：目標實體類 (集合泛型可推斷時可省略)
`fetch`：LAZY (默認) / EAGER
`@JoinColumn`：外鍵列定義，`name` 對應當前表列名，`referencedColumnName` 對應目標表主鍵列 (默認主鍵)

一對多 (@OneToMany)

@OneToMany(mappedBy = "hotel", cascade = CascadeType.ALL, fetch = FetchType.LAZY, orphanRemoval = true)
@OrderBy("roomNo ASC")
private Set<Room> rooms = new HashSet<>();

`mappedBy`：**關鍵**，指定關聯維護端 (多方) 的屬性名，表明由多方維護外鍵
`cascade`：級聯操作 (PERSIST/MERGE/REMOVE/REFRESH/DETACH/ALL)
`orphanRemoval`：孤兒刪除，從集合移除即刪除實體
`@OrderBy`：集合排序

多對多 (@ManyToMany)

// 擁有端
@ManyToMany(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
@JoinTable(
    name = "student_course",
    joinColumns = @JoinColumn(name = "student_id"),
    inverseJoinColumns = @JoinColumn(name = "course_id")
)
private Set<Course> courses = new HashSet<>();

// 反向端
@ManyToMany(mappedBy = "courses")
private Set<Student> students = new HashSet<>();

`@JoinTable`：定義中間表，`joinColumns` 持有端外鍵，`inverseJoinColumns` 反向端外鍵
雙向關聯需一端 `mappedBy`，另一端維護中間表

一對一 (@OneToOne)

// 共享主鍵
@OneToOne
@PrimaryKeyJoinColumn
private UserProfile profile;

// 外鍵關聯
@OneToOne
@JoinColumn(name = "profile_id", unique = true)
private UserProfile profile;

繼承映射策略

策略	註解	表結構	優缺點
單表	@Inheritance(strategy=SINGLE_TABLE) @DiscriminatorColumn(name="DTYPE") @DiscriminatorValue("EMP")	一張表，含所有子類字段 + 判別列	查詢快、修改鎖爭用、空列多
連表	@Inheritance(strategy=JOINED)	父表 + 子表各自表，主鍵關聯	範式好、查詢需 Join、插入多表
每類一表	@Inheritance(strategy=TABLE_PER_CLASS)	每個具體類一張表，含繼承字段	多態查詢需 Union、主鍵生成複雜