AIによる要約
@MappedSuperclassは、作成日時や更新日時のようなEntity共通のマッピングを継承させる仕組みです。@Embeddableは、住所や金額のような意味のある値を、所有Entityの一部として組み込む仕組みです。単なる重複削減ではなく、「Entityとして共通の性質か」「独立した値のまとまりか」で使い分けます。


JPAでEntityを増やすと、ID、作成日時、更新日時、住所、担当者コードなど、似たフィールドが繰り返し登場します。重複を減らすために親クラスへまとめたくなりますが、すべてを継承へ寄せると巨大なBaseEntityになりがちです。
監査日時は複数のEntityに同じ意味で必要です。一方、住所は注文が持つ値で、請求先と配送先を別々に保存します。この二つを例に、共通の列を継承する場合と、値の型を埋め込む場合を比べます。
この記事のポイント
@MappedSuperclassはEntityへマッピングを継承させる@Embeddableは所有Entityの一部となる値を表す- 監査項目は継承、住所や期間は埋め込みが候補になる
@Entityの継承戦略とは別の仕組みとして考える
実行用サンプル
同じ住所型を二度埋め込んだときの列重複と、列を分けた後のH2のDDL・再取得を確認します。 ソース全文、JUnitの検証コード、生成DDL、pom.xml、READMEを収録しています。JDK 17とMaven 3.9系で mvn test を実行します。Spring Boot 3.5.16のサンプルです。
@MappedSuperclassとは
@MappedSuperclass を付けたクラスは、子Entityにマッピングを引き継がせます。このサンプルの AuditableEntity はJPAのEntityとして登録されず、親クラス専用のテーブルも作りません。
AuditableEntity.java の全文
package info.syachiku.embedded.model;
import jakarta.persistence.Column;
import jakarta.persistence.EntityListeners;
import jakarta.persistence.MappedSuperclass;
import java.time.LocalDateTime;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.jpa.domain.support.AuditingEntityListener;
@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class AuditableEntity {
@CreatedDate
@Column(name = "created_at", nullable = false, updatable = false)
private LocalDateTime createdAt;
@LastModifiedDate
@Column(name = "updated_at", nullable = false)
private LocalDateTime updatedAt;
public LocalDateTime createdAt() {
return createdAt;
}
public LocalDateTime updatedAt() {
return updatedAt;
}
}サンプルでは PurchaseOrder と CustomerAccount が同じクラスを継承します。H2で作成された purchase_orders と customer_accounts の両方に、created_at と updated_at が入ります。
PurchaseOrder.java の抜粋。Entity名と監査項目の継承
@Entity
@Table(name = "purchase_orders")
public class PurchaseOrder extends AuditableEntity {
@Id
private Long id;この実行例は @EnableJpaAuditing と AuditingEntityListener を組み合わせています。両方のEntityを保存してコミットし、別の EntityManager で取得して、作成・更新日時が入っていることを確認します。
@Embeddableとは
@Embeddable はEntityが持つ値の型を表します。今回の @Embedded では、Address の列を注文テーブルに置きます。住所そのものをIDで検索する使い方なら、別のEntityとして管理するか検討します。
Address.java の全文
package info.syachiku.embedded.model;
import jakarta.persistence.Column;
import jakarta.persistence.Embeddable;
@Embeddable
public class Address {
@Column(name = "postal_code", nullable = false, length = 8)
private String postalCode;
@Column(name = "city", nullable = false, length = 80)
private String city;
@Column(name = "street", nullable = false, length = 160)
private String street;
protected Address() {}
public Address(String postalCode, String city, String street) {
this.postalCode = postalCode;
this.city = city;
this.street = street;
}
public String postalCode() {
return postalCode;
}
public String city() {
return city;
}
public String street() {
return street;
}
}Address では基本の列名を postal_code、city、street と定義します。注文側で @Embedded を使い、配送先では shipping_ で始まる列名へ上書きします。
PurchaseOrder.java の抜粋。配送先の住所を注文に埋め込むフィールド
@Embedded
@AttributeOverride(name = "postalCode", column = @Column(name = "shipping_postal_code", nullable = false, length = 8))
@AttributeOverride(name = "city", column = @Column(name = "shipping_city", nullable = false, length = 80))
@AttributeOverride(name = "street", column = @Column(name = "shipping_street", nullable = false, length = 160))
private Address shippingAddress;Java側では郵便番号、市区町村、番地を Address としてまとめ、PurchaseOrder は請求先と配送先を別のフィールドで持ちます。列名を変える箇所は、住所の共通型を置いたファイルから、注文の各フィールドに移ります。
違いを表で整理する
| 観点 | @MappedSuperclass | @Embeddable |
|---|---|---|
| 関係 | 継承する | 所有して組み込む |
| 向く内容 | Entity共通のマッピング・仕組み | 意味のある値のまとまり |
| 独自テーブル | 持たない | 持たない |
| 独自ID | 子Entity側の一部として定義可能 | 持てない |
| 代表例 | 作成日時、更新日時、共通ID | 住所、期間、金額、氏名 |
重複している列を見つけたら、まず「すべてのEntityが同じ性質として持つものか」「Entityが所有する値のまとまりか」を判断します。
監査項目はMappedSuperclassが向きやすい
作成日時、更新日時、作成者、更新者は、多くのEntityで共通する技術的な監査情報です。これらは親クラスへまとめることで、アノテーションや更新方法を統一しやすくなります。
ただし、「共通だから」と論理削除フラグ、ステータス、承認者、部署コードまで追加すると、使わないEntityにも項目が広がります。BaseEntityは何でも置き場にせず、本当に横断的な情報へ絞ります。
住所や期間はEmbeddableが向きやすい
住所、利用期間、金額、氏名などは、複数の値で1つの意味を作ります。これらは継承関係ではなく、Entityが持つ値として表現する方が自然です。
UsagePeriod.java の全文
package info.syachiku.embedded.model;
import jakarta.persistence.Embeddable;
import java.time.LocalDate;
import java.util.Objects;
@Embeddable
public class UsagePeriod {
private LocalDate startDate;
private LocalDate endDate;
protected UsagePeriod() {}
public UsagePeriod(LocalDate startDate, LocalDate endDate) {
this.startDate = Objects.requireNonNull(startDate);
this.endDate = Objects.requireNonNull(endDate);
if (endDate.isBefore(startDate)) {
throw new IllegalArgumentException("終了日は開始日以降にしてください");
}
}
public boolean includes(LocalDate target) {
return !target.isBefore(startDate) && !target.isAfter(endDate);
}
}期間の開始日と終了日も一つの値にまとめられます。UsagePeriod は両端の日を含み、終了日が開始日より前なら例外にします。ZIPのテストでは境界を確認し、後述する住所のDDLは住所を持つ注文と監査項目を持つ顧客の2表で検証します。
@Entityの継承とは違う
@MappedSuperclassはマッピング情報を子Entityへ引き継ぎますが、親クラス自体はEntityではありません。親型を対象にJPQLで一括検索するようなEntity継承の用途とは違います。
@Inheritanceを使うEntity継承は、単一テーブル、結合テーブルなど継承戦略の検討が必要です。共通カラムを減らしたいだけで、Entity継承へ進まないよう注意します。
よくある失敗
- 重複列を見つけるたびにBaseEntityへ追加する
- 業務上は別物の値を、列構成が同じという理由だけで共通化する
- 同じEmbeddableを1つのEntityで複数回使い、列名が衝突する
- JPA用の引数なしコンストラクタを用意していない
- Entity継承とMappedSuperclassを同じものとして説明する
既存の注文に請求先を追加し、同じ Address を二度 @Embedded で宣言すると、二つの属性が同じ基本列名を使います。この構成では、Hibernate 6.6.53.Finalが EntityManagerFactory の起動時に city の重複を検出します。
PurchaseOrderWithoutOverrides.java の抜粋。二つの住所が同じ列名を使う失敗例
@Embedded
private Address billingAddress;
@Embedded
private Address shippingAddress;JUnitが起動失敗の根本例外を捕捉して出力した先頭部分です。ここではデータベースへINSERTする前に、JPAのマッピング検査で止まります。
org.hibernate.MappingException: Column 'city' is duplicated in mapping for entity 'info.syachiku.embedded.broken.PurchaseOrderWithoutOverrides'修正は、請求先と配送先の @Embedded それぞれで列名を変えることです。@AttributeOverride の name には、DBの列名 postal_code ではなく、Address のJavaフィールド名 postalCode を指定します。上書き先の @Column に、長さとNULL可否も明示します。
PurchaseOrder.java の抜粋。請求先と配送先を別の列へ割り当てる修正
@Embedded
@AttributeOverride(name = "postalCode", column = @Column(name = "billing_postal_code", nullable = false, length = 8))
@AttributeOverride(name = "city", column = @Column(name = "billing_city", nullable = false, length = 80))
@AttributeOverride(name = "street", column = @Column(name = "billing_street", nullable = false, length = 160))
private Address billingAddress;
@Embedded
@AttributeOverride(name = "postalCode", column = @Column(name = "shipping_postal_code", nullable = false, length = 8))
@AttributeOverride(name = "city", column = @Column(name = "shipping_city", nullable = false, length = 80))
@AttributeOverride(name = "street", column = @Column(name = "shipping_street", nullable = false, length = 160))
private Address shippingAddress;修正後のH2向けDDLです。purchase_orders に請求先3列と配送先3列があり、customer_accounts と合わせて監査日時の列があります。H2の情報スキーマで、この検証用DBのテーブルがこの2表であることも確かめました。
schema.sql の全文
create table customer_accounts (
created_at timestamp(6) not null,
id bigint not null,
updated_at timestamp(6) not null,
name varchar(255) not null,
primary key (id)
);
create table purchase_orders (
billing_postal_code varchar(8) not null,
created_at timestamp(6) not null,
id bigint not null,
shipping_postal_code varchar(8) not null,
updated_at timestamp(6) not null,
billing_city varchar(80) not null,
shipping_city varchar(80) not null,
billing_street varchar(160) not null,
shipping_street varchar(160) not null,
primary key (id)
);列名を分けて起動できても、請求先と配送先が期待どおり入るかは別の確認です。テストでは請求先を千代田区、配送先を大阪市北区でコミットし、別の EntityManager で取得した各住所が元の値と一致することを確かめます。
EmbeddedColumnsTest.java の抜粋。コミット後、別のEntityManagerで2つの住所と監査日時を検証
try (var reader = factory.createEntityManager()) {
var order = reader.find(PurchaseOrder.class, 1L);
var customer = reader.find(CustomerAccount.class, 10L);
assertThat(order.billingAddress()).usingRecursiveComparison().isEqualTo(billing);
assertThat(order.shippingAddress()).usingRecursiveComparison().isEqualTo(shipping);
assertThat(order.createdAt()).isNotNull();
assertThat(order.updatedAt()).isNotNull();
assertThat(customer.createdAt()).isNotNull();
assertThat(customer.updatedAt()).isNotNull();
}列名や制約を既存DBで変える場合は、データ移行用のDDLと既存行の扱いを別に決めます。掲載DDLは、サンプルを初期化したH2で生成したものです。
Tests run: 4, Failures: 0, Errors: 0, Skipped: 0現場レビューでの見られ方
レビューでは「請求先と配送先の両方を保存して読み直し、片方の値で上書きされないことをテストしてください」「DBに既存列があるなら、新しいマッピングが既存の列名と制約に合うか確認してください」と伝えられます。
レビュー前のセルフチェック
確認リスト
- 共通化する対象がEntity共通の性質か、値のまとまりか
- MappedSuperclass自体をEntityとして検索しようとしていないか
- Embeddableへ独自IDを持たせようとしていないか
- 請求先・配送先の列が3つずつあり、既存DBの列名・長さ・NULL制約と合うか
- BaseEntityが業務項目の寄せ集めになっていないか
JPAとデータアクセスを体系的に学ぶ参考書
継承と値の所有の違いを整理した後、Entityのマッピングをデータアクセス全体と結びつけたい人には、『Spring徹底入門 第2版』が候補です。Spring Data JPAやトランザクションを含めて、Springの仕組みを体系的に確認できます。Spring Framework 5を前提とした本なので、掲載コードと現在の環境の違いは公式ドキュメントで補ってください。出版社の紹介・目次で範囲を確認できます。
Spring徹底入門 第2版
アプリを作った後に、DIやDB更新の仕組みを調べる。
DI、MVC、データアクセス、テスト、セキュリティまで幅広く確認できます。小さなWebアプリを一通り作り、Springの仕組みを詳しく学びたい人に向く参考書です。
- Springで小さなWebアプリを作ったことがある
- DIやトランザクションの仕組みを確認したい
Spring Framework 5向けです。Boot 3の実装に使うコード・設定は、採用している版の公式資料と照合してください。
当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。
この記事とあわせて読みたい
まとめ
監査日時を複数のEntityへ引き継ぐときは @MappedSuperclass が候補です。注文が請求先と配送先を持つ場合は、同じ Address を二つの @Embedded に使い、@AttributeOverride で列を分けます。
作成日時などの横断的な監査項目はMappedSuperclass、住所や期間など業務上意味のある値はEmbeddableを候補にします。重複を消すことより、モデルを読んだ時に意味が伝わることを優先してください。



