JPA (Java Persistence API) 是 Java EE 官方持久化規範，Hibernate 是其主流實現。使用 JPA 註解可屏蔽具體 ORM 框架差異，便於遷移。本文系統整理 JPA 核心註解、關聯映射、Bean Validation 整合及 EntityManager API。
hibernate-entitymanager、javax.persistence-api 等META-INF/persistence.xml 配置持久化單元EntityManager API 操作數據<persistence xmlns="https://java.sun.com/xml/ns/persistence" version="1.0">
<persistence-unit name="mysqlJPA" transaction-type="RESOURCE_LOCAL">
<properties>
<property name="hibernate.dialect" value="org.hibernate.dialect.MySQL5Dialect"/>
<property name="hibernate.connection.driver_class" value="com.mysql.jdbc.Driver"/>
<property name="hibernate.connection.url" value="jdbc:mysql://localhost:3306/hibernate_db"/>
<property name="hibernate.connection.username" value="root"/>
<property name="hibernate.connection.password" value="root"/>
<property name="hibernate.hbm2ddl.auto" value="update"/>
<property name="hibernate.show_sql" value="true"/>
</properties>
</persistence-unit>
</persistence>| 註解 | 用途 | 關鍵屬性 |
|---|---|---|
@Entity | 聲明實體類 | name（可選） |
@Table | 映射表信息 | name, catalog, schema |
@Id | 主鍵字段 | — |
@GeneratedValue | 主鍵生成策略 | strategy (AUTO/IDENTITY/SEQUENCE/TABLE), generator |
@Column | 列詳細定義 | name, nullable, unique, length, precision, scale, columnDefinition |
@Basic | 基本屬性映射 | fetch (EAGER/LAZY), optional |
@Transient | 非持久化字段 | — |
@Temporal | 日期時間類型 | DATE/TIME/TIMESTAMP |
@Lob | 大對象 | —（配合 @Column 區分 BLOB/CLOB） |
@OrderBy | 集合加載排序 | 如 "name ASC, id DESC" |
@MappedSuperclass | 父類註解繼承 | — |
@Embeddable/@Embedded | 可嵌入類/字段 | — |
// IDENTITY：依賴數據庫自增
@Id @GeneratedValue(strategy=GenerationType.IDENTITY)
@Column(name="user_id") private int userId;
// TABLE：通用表生成，適合遷移
@Id @GeneratedValue(strategy=GenerationType.TABLE)
@Column(name="user_code") private String userCode;
// SEQUENCE：Oracle/PostgreSQL 序列
@Id @GeneratedValue(strategy=GenerationType.SEQUENCE)
@SequenceGenerator(name="seq_user")
@Column(name="user_id") private int userId;| 關聯類型 | 擁有方註解 | 反向/被擁有方註解 | 關鍵點 |
|---|---|---|---|
| 多對一 | @ManyToOne | @OneToMany(mappedBy="...") | 多方持有外鍵，@JoinColumn 定義列 |
| 一對一 | @OneToOne + @JoinColumn | @OneToOne(mappedBy="...") | 共享主鍵或外鍵唯一約束 |
| 一對多 | @OneToMany | @ManyToOne | 建議多方為擁有方 |
| 多對多 | @ManyToMany + @JoinTable | @ManyToMany(mappedBy="...") | 中間表由 @JoinTable 定義 |
// 多方 OrderItem
@ManyToOne
@JoinColumn(name="order_id")
private UserOrder userOrder;
// 一方 UserOrder
@OneToMany(mappedBy="userOrder", cascade=CascadeType.ALL, orphanRemoval=true)
private Set<OrderItem> orderItems = new HashSet<>();// 主方 Boy
@OneToOne(mappedBy="boy", cascade=CascadeType.ALL)
private Girl girl;
// 從方 Girl
@Id
@OneToOne
@JoinColumn(name="boy_id")
private Boy boy;// Student
@ManyToMany
@JoinTable(name="stu_course",
joinColumns=@JoinColumn(name="s_id"),
inverseJoinColumns=@JoinColumn(name="c_id"))
private Set<Course> courses = new HashSet<>();
// Course
@ManyToMany(mappedBy="courses")
private Set<Student> students = new HashSet<>();persist(entity)：保存（相當於 save）merge(entity)：合併游離態（相當於 update/saveOrUpdate）remove(entity)：刪除find(Class, id)：按主鍵查詢createQuery(jpql)：JPQL 查詢getTransaction()：事務控制| 註解 | 適用類型 | 說明 |
|---|---|---|
@NotNull | 任意 | 非 null |
@NotEmpty | 集合/數組/字符串 | 非空 |
@NotBlank | 字符串 | 非空且含非空白字符 |
@Size(min,max) | 集合/數組/字符串 | 長度範圍 |
@Min/@Max | 數值 | 最小/最大值 |
@Pattern(regex) | 字符串 | 正則匹配 |
@Email | 字符串 | 郵箱格式 |
@Past/@Future | 日期 | 過去/未來時間 |
@Range(min,max) | 數值 | 範圍（Hibernate 擴展） |
所有註解支持 message 屬性自定義錯誤消息，可組合使用。
JPA 註解提供標準化 ORM 映射，Hibernate 作為實現完美支持並擴展。掌握核心註解（@Entity/@Id/@Column/@*To*）、關聯映射擁有方原則、主鍵生成策略選型、EntityManager API 及 Bean Validation 整合，即可構建可移植、可維護的持久層。
