新人と先輩の会話形式で理解しよう

新人

「先輩、Spring MVCでデータベースと連携する時に『エンティティ』ってよく聞くんですが、どういうものなんですか？」

先輩

「エンティティは、Javaのクラスとデータベースのテーブルを対応させる役割を持っているんだ。JPAを使うことで、エンティティを通じて簡単にデータベース操作ができるんだよ。」

新人

「なるほど！でも具体的にどんな風に使うんですか？」

先輩

「それじゃあ、エンティティの基本から一緒に見ていこう！」

1. エンティティとは？

エンティティとは、Javaのクラスでデータベースのテーブルに対応するオブジェクトのことを指します。JPAを使うことで、エンティティを通じてデータの保存、更新、削除、検索が簡単にできるようになります。これにより、SQLを書かなくてもデータベースとやり取りができ、開発効率が大幅に向上します。

2. エンティティの役割と重要性

エンティティは、Javaアプリケーションとデータベースの橋渡しをする重要な役割を担っています。エンティティを使うことで、オブジェクト指向の考え方を保ったままデータベース操作が可能です。特に、Spring MVCと組み合わせることで、データの受け渡しがスムーズになり、コードの保守性や可読性も向上します。

データの一貫性を保つことができる
コードの再利用性が高まる
データベース操作のエラーを減らせる

3. エンティティの基本構造とアノテーション

エンティティを作成するには、クラスに@Entityアノテーションを付けます。また、テーブル名を指定する場合は@Tableを使用します。各フィールドには@Id（主キー）や@Column（列情報）などのアノテーションを付与して、データベースとの対応関係を明示します。


package com.example.demo.entity;

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Column;
import jakarta.persistence.Table;

@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 100)
    private String name;

    @Column(unique = true, length = 150)
    private String email;

    // ゲッターとセッター
    public Long getId() {
        return id;
    }

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

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

このコードでは、Userクラスがusersというテーブルに対応しています。@Idは主キーを表し、@GeneratedValueは自動採番を指定しています。@Columnで列の属性（長さ、null許可、ユニーク制約）を定義できます。

4. エンティティの作成手順（実際のコード例を含めて解説）

ここでは、Spring MVCとJPAを使ったエンティティの作成手順を実際のコード例を交えて説明します。エンティティはデータベースのテーブルと直接対応し、Javaオブジェクトを通じてデータベース操作を簡単に行えます。

4.1 プロジェクトの準備

まず、pleiadesでSpring Bootプロジェクトを作成し、Gradleを使用してJPAとデータベース接続用の依存関係を追加します。依存関係はpleiadesのチェックボックスで簡単に追加できます。


dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
    runtimeOnly 'com.h2database:h2' // 開発用データベース（H2）
}

4.2 エンティティクラスの作成

次に、ユーザー情報を管理するエンティティクラスUserを作成します。これはデータベースのusersテーブルに対応します。


package com.example.demo.entity;

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Column;
import jakarta.persistence.Table;

@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 100)
    private String name;

    @Column(unique = true, length = 150)
    private String email;

    // ゲッターとセッター
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

このコードでは、@Entityでクラスをエンティティとして定義し、@Table(name = "users")でデータベースのテーブル名を指定しています。@Idは主キーを表し、@GeneratedValueで自動採番を設定しています。

5. エンティティとデータベースの関係性（テーブルとのマッピング）

エンティティは、データベースのテーブルと1対1で対応しています。クラス名はテーブル名と、フィールドは列（カラム）にマッピングされます。JPAを使うことで、オブジェクトを操作するだけで自動的にデータベースに反映されます。


@Entity
@Table(name = "products")
public class Product {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String name;

    @Column(nullable = false)
    private double price;

    // ゲッターとセッター省略
}

このProductクラスはproductsテーブルに対応します。エンティティを作成すると、Spring Bootの自動構成により、以下のようなテーブルが生成されます。


CREATE TABLE products (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    price DOUBLE NOT NULL
);

エンティティのフィールドに付与するアノテーションで、データベースの列に関する制約や設定が可能です。例えば、@Column(nullable = false)は「NULL不可」を意味します。

6. エンティティのライフサイクル（管理と状態遷移）

エンティティはJPAによって管理され、さまざまな状態を持ちます。エンティティのライフサイクルを理解することで、データベースとのやり取りがスムーズになります。主な状態は以下の通りです。

新規（New）: 新しく作成されたが、まだデータベースに保存されていない状態。
管理対象（Managed）: EntityManagerが管理している状態。
デタッチ（Detached）: 管理対象から外れた状態。
削除（Removed）: 削除予約状態で、トランザクション完了時にデータベースから削除される。


package com.example.demo.service;

import com.example.demo.entity.Product;
import jakarta.persistence.EntityManager;
import jakarta.persistence.PersistenceContext;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class ProductService {

    @PersistenceContext
    private EntityManager entityManager;

    @Transactional
    public void manageEntityLifecycle() {
        // 新規状態
        Product product = new Product();
        product.setName("ノートパソコン");
        product.setPrice(120000);

        // 管理対象に追加
        entityManager.persist(product);

        // 管理対象からデタッチ
        entityManager.detach(product);

        // 削除状態に変更
        entityManager.remove(product);
    }
}

このコードでは、persistでエンティティが管理対象になり、detachで管理対象から外れます。removeを呼び出すと、削除状態になります。

7. 実際にエンティティを使った簡単なデータ操作（作成・保存・検索）

ここでは、Spring MVCとJPAを使ってエンティティを作成し、データベースへの保存や検索を行う方法を実際のコードを通じて解説します。初心者でもすぐに試せるように、具体的な手順を順に説明します。

7.1 リポジトリの作成

エンティティを使ったデータベース操作には、JpaRepositoryインターフェースを継承したリポジトリを作成します。以下はUserRepositoryの例です。


package com.example.demo.repository;

import com.example.demo.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;
import java.util.Optional;

public interface UserRepository extends JpaRepository<User, Long> {
    Optional<User> findByEmail(String email);
}

このリポジトリを作成することで、デフォルトでsave（保存）、findById（検索）、delete（削除）などが利用でき、findByEmailのようにメソッド名で検索条件を指定することも可能です。

7.2 コントローラの作成とデータ保存

次に、データを作成して保存するためのコントローラを作成します。


package com.example.demo.controller;

import com.example.demo.entity.User;
import com.example.demo.repository.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;

@Controller
public class UserController {

    @Autowired
    private UserRepository userRepository;

    @GetMapping("/form")
    public String showForm() {
        return "user-form";
    }

    @PostMapping("/save")
    public String saveUser(@RequestParam String name, @RequestParam String email, Model model) {
        User user = new User();
        user.setName(name);
        user.setEmail(email);
        userRepository.save(user);
        model.addAttribute("message", "ユーザー情報を保存しました。");
        return "result";
    }
}

このコードでは、/formエンドポイントで入力フォームを表示し、/saveでデータを保存します。保存後は結果画面で確認できます。

7.3 フォーム画面と結果画面の作成

user-form.html（フォーム画面）:


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>ユーザー登録</title>
</head>
<body>
    <h2>ユーザー情報入力</h2>
    <form th:action="@{/save}" method="post">
        <label>名前:</label>
        <input type="text" name="name" required><br>
        <label>メールアドレス:</label>
        <input type="email" name="email" required><br>
        <button type="submit">保存</button>
    </form>
</body>
</html>

result.html（結果画面）:


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>保存結果</title>
</head>
<body>
    <h2 th:text="${message}"></h2>
    <a th:href="@{/form}">戻る</a>
</body>
</html>

7.4 実行結果の例

ブラウザでlocalhost:8080/formにアクセスし、名前とメールアドレスを入力して送信すると、保存結果が表示されます。


ユーザー情報を保存しました。

8. よくあるエンティティ関連のエラーとその解決方法

エンティティを扱う際に初心者がつまずきやすいエラーと、その対処法を紹介します。

8.1 エラー: EntityNotFoundException

原因: 指定したIDでデータが存在しない場合に発生します。


userRepository.findById(999L).orElseThrow(() -> new EntityNotFoundException("ユーザーが見つかりません"));

解決方法: Optionalを使って存在確認を行い、エラーメッセージを明確に表示します。

8.2 エラー: DuplicateEntryException（重複エラー）

原因: ユニーク制約のある列に同じ値を保存しようとすると発生します。


// email列がユニーク制約付きの場合に同じ値を保存しようとするとエラーに。
User user = new User();
user.setEmail("test@example.com");
userRepository.save(user);

解決方法: 保存前にfindByEmailで既存データを確認してから保存します。

8.3 エラー: LazyInitializationException

原因: 関連エンティティを遅延読み込みの状態でトランザクション外でアクセスした場合に発生します。


@Transactional
public void loadUser() {
    User user = userRepository.findById(1L).orElseThrow();
    user.getOrders().size(); // トランザクション内ならエラー回避
}

解決方法: トランザクション内で処理を行うか、fetch = FetchType.EAGERを使用しますが、パフォーマンスに注意が必要です。

9. 記事全体の振り返りと実践アドバイス

本記事では、エンティティの基本概念から実際のデータ操作、よくあるエラーまでを解説しました。エンティティを理解することで、JPAを使った効率的なデータベース操作が可能になります。

エンティティはJavaクラスとデータベーステーブルの橋渡しをする重要な役割を担います。
@Entityや@Columnなどのアノテーションを適切に使うことで、安全で効率的な開発が可能です。
リポジトリとコントローラを組み合わせてデータの作成・保存・検索が簡単に行えます。
実行前に依存関係とデータベース設定を確認することで、不要なエラーを防げます。

これから実際に手を動かしてみて、エンティティを使ったSpring MVC開発に慣れていきましょう！

まとめ

エンティティという存在は、Spring Boot とデータベースを結びつけるうえで避けて通れない重要な要素です。記事全体を振り返ってみると、エンティティは単なる Java クラスではなく、アプリケーションが扱う「情報の形」を定義し、データベースのテーブルと自然につながる構造を生み出してくれる役割を担っていることがわかります。特に、@Entityや@Table、@Id、@Columnといったアノテーションを理解することで、Java のオブジェクトとデータベースのカラムがどのようにマッピングされていくかを視覚的にとらえられるようになります。これは、Spring Boot での開発を一歩深く理解するうえで非常に大きなポイントです。

また、エンティティの作成手順を通じて、クラス構造を整えることがデータの扱いやすさにつながるということも改めて実感できます。同じ構造のクラスが増えてきても、適切にパッケージを分け、関連するリポジトリやサービスと組み合わせていくことで、コード全体の整合性や保守性も大きく向上します。リポジトリを通した CRUD 操作は、Spring Data JPA の提供するメソッド名だけで自然と処理が成立するため、難しい SQL を書かずにデータベース処理を行える便利さも魅力でしょう。

さらに、エンティティが持つ「ライフサイクル」を理解することで、処理の流れを自然に捉えられるようになります。エンティティが「新規」から始まり、「管理対象」に入り、「デタッチ」や「削除」へと移る流れを押さえておくことは、アプリケーションの動きを深く理解するうえで欠かせません。特に、JPA の処理がどのタイミングでデータベースに反映されるのか、なぜトランザクション内での操作が必要なのか、といった疑問もこの仕組みを知ることで解決します。

実際のデータ操作では、リポジトリとコントローラの連携によってデータの保存や検索が容易に実現できることを確認しました。フォームから送信された値をエンティティへセットし、それをリポジトリへ渡すだけでデータベースへ保存できる流れは、Spring Boot の最大の魅力のひとつです。画面・コントローラ・サービス・リポジトリ・エンティティが自然と連携する仕組みは、使うほどに理解が深まり、より複雑な処理にも挑戦できるようになります。

最後に、よくあるエラーについても触れましたが、特にEntityNotFoundException、LazyInitializationException、ユニーク制約違反などは初心者が一度は必ず遭遇するものです。この記事で紹介した解決方法を参考にすることで、エラーの原因を落ち着いて探れるようになり、スムーズな開発へつながります。Spring MVC と JPA を扱ううえで、これらの理解は確実に役立つはずです。

■ エンティティのまとめコード例


package com.example.demo.entity;

import jakarta.persistence.Entity;
import jakarta.persistence.Table;
import jakarta.persistence.Id;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Column;

@Entity
@Table(name = "items")
public class Item {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 200)
    private String title;

    @Column(nullable = false)
    private int stock;

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }

    public int getStock() { return stock; }
    public void setStock(int stock) { this.stock = stock; }
}

上記のコード例は、記事内で学んだ内容をぎゅっと凝縮したシンプルなエンティティです。こうした基本形をしっかり押さえることで、より複雑なエンティティ設計も理解しやすくなり、関連テーブルやリレーションを伴う構造へもスムーズに発展させていけるでしょう。

先生と生徒の振り返り会話

生徒：「エンティティって聞いたことはあったけど、こんなに多くの役割があるんですね。Java のクラスとテーブルがそのままつながるのは便利でした。」

先生：「そうだね。Spring Boot と JPA の仕組みを使うことで、データ操作の基本が自然に扱えるようになるよ。特にアノテーションがどんな意味を持つか理解できたのは大きいね。」

生徒：「リポジトリを使うと save とか findById とか簡単にできて、SQL 書かなくてもいいのは驚きました。」

先生：「そこが Spring Data JPA の強みだね。エンティティがしっかり設計されていれば、データベース処理はぐっと楽になるよ。」

生徒：「エンティティのライフサイクルも理解できました。状態が変わっていく感じがイメージしやすかったです。」

先生：「あれは難しい部分だけど、理解しておくとアプリケーション全体の流れがつかみやすくなるよ。これからは関連エンティティの扱いやリレーションにも挑戦していこう。」