Spring Data JPAで複合主キー（複数ID）を持つエンティティをスマートに扱う☕️

はじめに (対象読者・この記事でわかること)

この記事は、Spring FrameworkおよびSpring Data JPAを利用しているJava開発者を対象としています。特に、データベース設計で複合主キー（複数のカラムで構成される主キー）を採用しているものの、Spring Data JPAでのエンティティ定義やアクセス方法に戸惑っている方に最適です。

この記事を読むことで、Spring Data JPAにおける複合主キーを持つエンティティのベストプラクティスがわかるだけでなく、@EmbeddedIdアノテーションを用いたエンティティ定義から、リポジトリ層での効率的なデータアクセス方法、そしてサービス層での利用例まで、具体的な実装方法を習得できます。複合主キーに起因する一般的な問題点とその解決策も提示するため、開発中に直面するであろう課題を事前に回避できるようになるでしょう。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。 * Javaプログラミングの基本的な知識 * Spring FrameworkおよびSpring Bootの基本的な使用経験 * Spring Data JPAの基本的な使い方（JpaRepositoryの利用など） * リレーショナルデータベースとSQLの基礎知識（主キー、複合主キーの概念など）

複合主キーとSpring Data JPAの課題

データベース設計において、テーブルの主キーが単一の列で構成されるケースが一般的ですが、複数の列の組み合わせによって一意性を保証する「複合主キー」を採用することもあります。例えば、多対多の関係を表現する中間テーブルや、バージョン管理が必要な履歴テーブルなどでよく用いられます。複合主キーはデータの整合性を高める上で非常に有効な手段ですが、これをSpring Data JPAで扱う際には、いくつかの特有の考慮点と課題が存在します。

Spring Data JPAは、単一の主キーを持つエンティティの操作を非常に直感的に行えるよう設計されています。しかし、複合主キーの場合、単純に@Idアノテーションを複数付与するだけでは機能しません。JPAの仕様に沿って、複合主キーを表現するための特別な仕組みを用いる必要があります。具体的には、@IdClassアノテーションを使用する方法と、@EmbeddedIdアノテーションを使用する方法の二通りが存在します。

これらの方法を適切に理解し、実装しないと、エンティティの永続化や取得が正しく行われなかったり、findByIdメソッドが期待通りに動作しなかったりする問題に直面する可能性があります。特に、複合主キーオブジェクトの等価性（equalsとhashCode）の扱いが重要になり、これを怠ると予期せぬバグの原因となるため、注意が必要です。

本記事では、より一般的で推奨されることが多い@EmbeddedIdアプローチを中心に、複合主キーを持つエンティティの定義から、Spring Data JPAリポジトリでの効率的なアクセス方法までを具体的に解説し、これらの課題をどのように乗り越えるかを示します。

Spring Data JPAで複数IDを持つエンティティを扱う

ここからは、Spring Data JPAで複合主キー（複数ID）を持つエンティティを具体的にどのように実装し、アクセスしていくかを見ていきます。ここでは、@EmbeddedIdアノテーションを用いたアプローチを主軸に解説します。

ステップ1: 複合主キーを持つエンティティの定義

@EmbeddedIdを使用する場合、複合主キーを表現するための別クラスを作成し、それをエンティティに埋め込みます。このIDクラスはSerializableを実装し、equalsとhashCodeメソッドを適切にオーバーライドする必要があります。

まず、複合主キーを表すIDクラスを作成します。

Java

// ProductOrderId.java
package com.example.demo.domain;

import jakarta.persistence.Embeddable;
import java.io.Serializable;
import java.util.Objects;

@Embeddable
public class ProductOrderId implements Serializable {

    private static final long serialVersionUID = 1L;

    private Long productId;
    private Long orderId;

    // デフォルトコンストラクタはJPAの要件
    public ProductOrderId() {}

    public ProductOrderId(Long productId, Long orderId) {
        this.productId = productId;
        this.orderId = orderId;
    }

    public Long getProductId() {
        return productId;
    }

    public void setProductId(Long productId) {
        this.productId = productId;
    }

    public Long getOrderId() {
        return orderId;
    }

    public void setOrderId(Long orderId) {
        this.orderId = orderId;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        ProductOrderId that = (ProductOrderId) o;
        return Objects.equals(productId, that.productId) &&
               Objects.equals(orderId, that.orderId);
    }

    @Override
    public int hashCode() {
        return Objects.hash(productId, orderId);
    }

    @Override
    public String toString() {
        return "ProductOrderId{" +
               "productId=" + productId +
               ", orderId=" + orderId +
               '}';
    }
}

次に、このIDクラスを@EmbeddedIdとして持つエンティティクラスを定義します。

Java

// OrderItem.java
package com.example.demo.domain;

import jakarta.persistence.EmbeddedId;
import jakarta.persistence.Entity;
import jakarta.persistence.Table;
import jakarta.persistence.Column;

@Entity
@Table(name = "order_items")
public class OrderItem {

    @EmbeddedId
    private ProductOrderId id; // 複合主キーを埋め込む

    @Column(name = "quantity")
    private Integer quantity;

    @Column(name = "price_per_unit")
    private Double pricePerUnit;

    // デフォルトコンストラクタはJPAの要件
    public OrderItem() {}

    public OrderItem(ProductOrderId id, Integer quantity, Double pricePerUnit) {
        this.id = id;
        this.quantity = quantity;
        this.pricePerUnit = pricePerUnit;
    }

    public ProductOrderId getId() {
        return id;
    }

    public void setId(ProductOrderId id) {
        this.id = id;
    }

    public Integer getQuantity() {
        return quantity;
    }

    public void setQuantity(Integer quantity) {
        this.quantity = quantity;
    }

    public Double getPricePerUnit() {
        return pricePerUnit;
    }

    public void setPricePerUnit(Double pricePerUnit) {
        this.pricePerUnit = pricePerUnit;
    }

    // 必要に応じてequals, hashCode, toStringをオーバーライド
    // 通常はEmbeddedIdのequals, hashCodeに依存するため、エンティティ側では不要な場合が多い
}

ステップ2: リポジトリでの基本操作とカスタムクエリ

ProductOrderIdを複合主キーとして持つOrderItemエンティティのリポジトリを定義します。JpaRepositoryのジェネリクスには、エンティティクラスとIDクラスを指定します。

Java

// OrderItemRepository.java
package com.example.demo.repository;

import com.example.demo.domain.OrderItem;
import com.example.demo.domain.ProductOrderId;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import java.util.List;
import java.util.Optional;

public interface OrderItemRepository extends JpaRepository<OrderItem, ProductOrderId> {

    // 1. findByIdでのアクセス
    // JpaRepositoryが提供するfindById(ID id)メソッドは、ProductOrderIdオブジェクトを受け取る

    // 2. 特定のproductIdに属するすべての注文アイテムを取得
    List<OrderItem> findByIdProductId(Long productId);

    // 3. 特定のorderIdに属するすべての注文アイテムを取得
    List<OrderItem> findByIdOrderId(Long orderId);

    // 4. productIdとorderIdの両方で特定のOrderItemを検索（findByIdとは別の表現）
    Optional<OrderItem> findByIdProductIdAndIdOrderId(Long productId, Long orderId);

    // 5. JPQLを使って特定のorderIdに属する複数のproductIdを持つOrderItemを検索
    @Query("SELECT oi FROM OrderItem oi WHERE oi.id.orderId = :orderId AND oi.id.productId IN :productIds")
    List<OrderItem> findByOrderIdAndProductIds(@Param("orderId") Long orderId, @Param("productIds") List<Long> productIds);

    // 6. 複数の複合ID（ProductOrderIdオブジェクトのリスト）を使って複数件取得
    // JpaRepositoryのfindAllById(Iterable<ID> ids)メソッドを利用できる
    // List<OrderItem> items = repository.findAllById(List.of(new ProductOrderId(...), new ProductOrderId(...)));
}

ステップ3: サービス層での利用例

上記で定義したリポジトリをサービス層で利用し、ビジネスロジックを実装します。

Java

// OrderItemService.java
package com.example.demo.service;

import com.example.demo.domain.OrderItem;
import com.example.demo.domain.ProductOrderId;
import com.example.demo.repository.OrderItemRepository;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.util.List;
import java.util.Optional;

@Service
@Transactional
public class OrderItemService {

    private final OrderItemRepository orderItemRepository;

    public OrderItemService(OrderItemRepository orderItemRepository) {
        this.orderItemRepository = orderItemRepository;
    }

    /**
     * 特定の複合主キーでOrderItemを取得する
     * @param productId 製品ID
     * @param orderId 注文ID
     * @return 該当するOrderItem (Optional)
     */
    public Optional<OrderItem> getOrderItemById(Long productId, Long orderId) {
        ProductOrderId id = new ProductOrderId(productId, orderId);
        return orderItemRepository.findById(id);
    }

    /**
     * 特定の注文に属するすべてのアイテムを取得する
     * @param orderId 注文ID
     * @return 注文アイテムのリスト
     */
    public List<OrderItem> getOrderItemsByOrderId(Long orderId) {
        return orderItemRepository.findByIdOrderId(orderId);
    }

    /**
     * 特定の注文IDと複数の製品IDに合致する注文アイテムを取得する
     * @param orderId 注文ID
     * @param productIds 製品IDのリスト
     * @return 注文アイテムのリスト
     */
    public List<OrderItem> getOrderItemsByOrderIdAndProductIds(Long orderId, List<Long> productIds) {
        return orderItemRepository.findByOrderIdAndProductIds(orderId, productIds);
    }

    /**
     * 複数の複合主キーを指定して複数のOrderItemを取得する
     * @param ids 複合主キーのリスト
     * @return 注文アイテムのリスト
     */
    public List<OrderItem> getOrderItemsByMultipleIds(List<ProductOrderId> ids) {
        return orderItemRepository.findAllById(ids);
    }

    /**
     * 新しいOrderItemを保存する
     * @param productId 製品ID
     * @param orderId 注文ID
     * @param quantity 数量
     * @param pricePerUnit 単価
     * @return 保存されたOrderItem
     */
    public OrderItem createOrderItem(Long productId, Long orderId, Integer quantity, Double pricePerUnit) {
        ProductOrderId id = new ProductOrderId(productId, orderId);
        OrderItem orderItem = new OrderItem(id, quantity, pricePerUnit);
        return orderItemRepository.save(orderItem);
    }
}

ハマった点やエラー解決

複合主キーを扱う際によく遭遇する問題と、その解決策をまとめます。

1. ProductOrderIdにSerializableを実装し忘れる、またはequals/hashCodeをオーバーライドしない

   • 現象: findByIdが常にOptional.empty()を返したり、データが重複して保存されたり、キャッシュが正しく機能しないなどの問題が発生します。JPAプロバイダがIDオブジェクトを比較する際に、オブジェクトの参照値（デフォルトのObject.equals()）で比較してしまうためです。
   • 解決策: ProductOrderIdクラスに必ずjava.io.Serializableを実装し、すべての主キーを構成するフィールドに基づいて equalsとhashCodeメソッドを適切にオーバーライドしてください。IDEの自動生成機能（IntelliJ IDEAのAlt+Insert -> equals() and hashCode()、EclipseのSource -> Generate hashCode() and equals()...）を活用すると良いでしょう。

2. findByIdに渡すProductOrderIdオブジェクトのフィールド値がデータベースと一致しない

   • 現象: データベースにはデータが存在するはずなのに、findById(new ProductOrderId(1L, 100L))がデータを見つけられない。
   • 解決策: ProductOrderIdオブジェクトを作成する際に、productIdとorderIdにデータベースに格納されている正確な値を設定しているか確認してください。数値型の場合、データ型が一致しているかも重要です（例: LongとIntegerの混同）。

3. カスタムクエリ（@Query）で複合主キーのフィールドを参照できない

   • 現象: @Query("SELECT oi FROM OrderItem oi WHERE oi.productId = :productId") のように記述すると、「productIdが見つからない」というエラーが発生。
   • 解決策: @EmbeddedIdを使用している場合、複合主キーの各フィールドは、エンティティ.埋め込みIDオブジェクト.フィールド名の形式で参照する必要があります。上記の例であれば、oi.id.productIdのように記述します。 java @Query("SELECT oi FROM OrderItem oi WHERE oi.id.productId = :productId") List<OrderItem> findByProductIdUsingQuery(@Param("productId") Long productId);
   • また、IN句で複数のIDを渡す場合も、同様に埋め込みIDオブジェクトのフィールドを指定します。 java @Query("SELECT oi FROM OrderItem oi WHERE oi.id.orderId = :orderId AND oi.id.productId IN :productIds") List<OrderItem> findByOrderIdAndProductIds(@Param("orderId") Long orderId, @Param("productIds") List<Long> productIds);

これらのポイントに注意することで、Spring Data JPAでの複合主キーの取り扱いが格段にスムーズになります。

まとめ

本記事では、Spring Data JPAにおける複合主キー（複数ID）を持つエンティティの扱い方について解説しました。

• 複合主キーの定義: @EmbeddedIdアノテーションと専用のIDクラスを使用し、IDクラスにはSerializableの実装とequals/hashCodeメソッドの適切なオーバーライドが必須であることを確認しました。
• リポジトリでの操作: JpaRepositoryのfindByIdメソッドが複合IDオブジェクトを受け取ることを理解し、カスタムクエリメソッド（findByIdProductIdなど）や@Queryアノテーションを用いたJPQLでの複合主キー検索方法を学びました。
• サービス層での活用: 定義したリポジトリをサービス層で活用し、ビジネスロジックに合わせた柔軟なデータアクセスを実現する例を示しました。

この記事を通して、Spring Data JPAで複合主キーを持つエンティティを自信を持って設計・実装できるようになるはずです。複合主キーの複雑さに臆することなく、より堅牢で効率的なデータモデルを構築するための知識とスキルを習得できたことでしょう。

今後は、@IdClassアプローチとの比較や、複合外部キーを持つ関連エンティティの扱い方など、より発展的な内容についても記事にする予定です。

参考資料

• Spring Data JPA Reference Documentation
• Hibernate User Guide - Composite Identifiers
• Baeldung: JPA Composite Primary Key