JPA 與 Hibernate 實現複合主鍵：@Embeddable 與 @IdClass 實戰詳解

問題背景：何時需要複合主鍵

複合主鍵由多欄位組合唯一標識記錄，又稱自然鍵或業務鍵。優點是業務語義明確；缺點是設計編碼較複雜，且將數據庫模型綁定特定業務域，遷移困難。常見於遺留系統整合或業務強制要求場景。

實體類設計

1. 複合鍵類 BillingAddress (使用 @Embeddable)

@Embeddable
public class BillingAddress implements Serializable {
    private String street;
    private String city;

    public BillingAddress() {}
    public BillingAddress(String street, String city) {
        this.street = street; this.city = city;
    }
    // Getter/Setter 省略
}

關鍵點：實現 Serializable、標註 @Embeddable 使其可嵌入其他實體。

2. 主實體 PurchaseOrder (使用 @IdClass)

@Entity
@Table(name = "PURCHASE_ORDERS")
@IdClass(BillingAddress.class)
public class PurchaseOrder {
    @Id
    @AttributeOverrides({
        @AttributeOverride(name = "street", column = @Column(name = "STREET")),
        @AttributeOverride(name = "city", column = @Column(name = "CITY"))
    })
    private String street;
    private String city;
    private String itemName;

    public PurchaseOrder() {}
    public PurchaseOrder(BillingAddress addr) {
        this.street = addr.getStreet();
        this.city = addr.getCity();
    }
    // Getter/Setter 省略
}

註解解析：

• @IdClass 指定複合鍵類
• @Id + @AttributeOverrides 將嵌入類屬性映射為表主鍵欄位
• 主實體必須重複聲明複合鍵屬性 (street, city)，這是 JPA 規範要求

數據庫 Schema 定義

CREATE TABLE PURCHASE_ORDERS (
    street VARCHAR(255) NOT NULL,
    city VARCHAR(255) NOT NULL,
    itemName VARCHAR(255),
    PRIMARY KEY (street, city)
);

客戶端持久化測試代碼

EntityManagerFactory emf = Persistence.createEntityManagerFactory("helloworld");
EntityManager em = emf.createEntityManager();
EntityTransaction tx = em.getTransaction();
tx.begin();

PurchaseOrder order = new PurchaseOrder(new BillingAddress("Broad Street", "Boston"));
order.setItemName("My new computer");
em.persist(order);

tx.commit();
em.close();

執行後數據庫記錄：

STREET       | CITY    | ITEMNAME
Broad Street | Boston  | My new computer

總結與最佳實踐

1. 複合鍵適用於向後兼容遺留系統，新系統優先考慮代理鍵
2. @Embeddable + @IdClass 是 JPA 標準實現方式
3. 主實體中重複聲明鍵屬性雖顯冗餘，但確保了 ORM 映射的明確性
4. 遷移策略：若業務允許，漸進式引入代理鍵並維護舊鍵唯一約束