Spring Data JPAの@MappedSuperclassと@Embeddableの違いを解説する記事のアイキャッチ。Java道場風の空間で若手エンジニアがJPAのEntity設計を学ぶイラスト。

設計・テスト・レビュー

Spring Data JPAの@MappedSuperclassと@Embeddableの違い|共通項目をどこへまとめる?

AIによる要約

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

新人SE
新人SE
複数のEntityに同じカラムがあります。親クラスへまとめるのと@Embeddableにするのは何が違いますか?
ポンコツSE
ポンコツSE
作成日時のように全Entityへ共通する仕組みならMappedSuperclass、住所のようにEntityが所有する値のまとまりならEmbeddableが候補です。

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版」の表紙
商品画像:Amazon.co.jp
PR 入門後の参考書|Spring Framework 5向け

Spring徹底入門 第2版

株式会社NTTデータ (著), 株式会社NTTデータグループ (編集)

アプリを作った後に、DIやDB更新の仕組みを調べる。

DI、MVC、データアクセス、テスト、セキュリティまで幅広く確認できます。小さなWebアプリを一通り作り、Springの仕組みを詳しく学びたい人に向く参考書です。

  • Springで小さなWebアプリを作ったことがある
  • DIやトランザクションの仕組みを確認したい

Spring Framework 5向けです。Boot 3の実装に使うコード・設定は、採用している版の公式資料と照合してください。

当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。

この記事とあわせて読みたい

関連記事Spring Data Jpaと@Entityを使って複数テーブルで共通の値を親クラスにまとめて、子クラスで継承する方法 旧来の javax.persistence を使う保守環境向けです。親をEntityにする単一テーブル継承と、子の別テーブルへ共通列を引き継ぐ構成を比較します。 記事を読む 関連記事Spring BootのDTO変換はどこでやるべきか EntityとDTOの変換をController・Service・Mapperへ分ける判断を整理します。 記事を読む 関連記事Spring BootのRepositoryでよくある戻り値の扱い JPA RepositoryからEntityを取得する時のOptionalや複数件の扱いを確認します。 記事を読む

まとめ

監査日時を複数のEntityへ引き継ぐときは @MappedSuperclass が候補です。注文が請求先と配送先を持つ場合は、同じ Address を二つの @Embedded に使い、@AttributeOverride で列を分けます。

作成日時などの横断的な監査項目はMappedSuperclass、住所や期間など業務上意味のある値はEmbeddableを候補にします。重複を消すことより、モデルを読んだ時に意味が伝わることを優先してください。

-設計・テスト・レビュー
-