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

新人

「JPAのエンティティって、いったい何のためにあるんですか？ただのクラスじゃダメなんですか？」

先輩

「エンティティは、データベースのテーブルとJavaのクラスを対応させるためのものなんだ。JPAでは、それをマッピングって言うんだよ。」

新人

「テーブルとクラスがつながるって、なんか難しそうですね……」

先輩

「順番にゆっくり解説していくから、安心してね。基本から一緒に学んでいこう！」

1. JPAのエンティティとは？

JPAのエンティティとは、データベースのテーブルと対応するJavaクラスのことです。エンティティを使うことで、SQL文を直接書かずにJavaのコードでデータベースの操作ができるようになります。

エンティティクラスには、@Entityというアノテーションを付けて、このクラスがJPAで管理されることを明示します。

たとえば、書籍情報を管理するためのクラスBookをエンティティとして定義するには、以下のように記述します。


import jakarta.persistence.Entity;
import jakarta.persistence.Id;

@Entity
public class Book {
    @Id
    private Long id;
    private String title;
    private String author;

    // getterとsetterは省略
}

このように、JPAのエンティティを定義するだけで、JPAがこのクラスとデータベースのテーブルを自動的に関連づけてくれるようになります。

2. なぜエンティティマッピングが必要なのか？

Javaでアプリケーションを作成する際、多くの場合はデータを保存するためにデータベースが使われます。従来はJDBCを使ってSQLを手書きしてデータベースにアクセスしていましたが、それではコードが長くなり、保守も大変です。

そこでJPAの出番です。エンティティマッピングを使うことで、データベースのテーブルとJavaのクラスを直接対応させることができ、SQLを書かずにJavaのオブジェクトとしてデータを扱えるようになります。

たとえば、書籍を1件追加したいとき、以下のようなイメージで操作ができます。


Book book = new Book();
book.setId(1L);
book.setTitle("JPA入門");
book.setAuthor("山田太郎");
bookRepository.save(book);

このように、エンティティを使えばJavaのコードだけでデータベースの操作が可能になります。マッピングが自動で行われるため、開発スピードも上がり、ミスも減らせます。

3. 最も基本的なエンティティクラスの作成方法

エンティティクラスの作成には、以下のアノテーションが最低限必要です。

@Entity：このクラスがエンティティであることを指定
@Id：主キー（Primary Key）を指定

それでは、もう少し実際的なエンティティクラスを見てみましょう。


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

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;

    public User() {}

    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; }
}

このように、@GeneratedValueアノテーションを使うことで、主キーの値を自動で生成することができます。また、デフォルトコンストラクタとgetter/setterも必要です。

このUserクラスをエンティティとして定義することで、テーブルに対応した形でユーザー情報をデータベースに保存・取得できるようになります。

4. 主キーの設定方法（@Id、@GeneratedValue）

エンティティクラスにおいて最も重要な要素のひとつが「主キー」の設定です。主キーとは、テーブル内のデータを一意に識別するための番号やIDのことです。JPAでは、主キーを表すために@Idというアノテーションを使用します。

さらに、主キーの値を自動で生成したい場合は、@GeneratedValueアノテーションを組み合わせて使います。これにより、開発者が手動でIDを設定しなくても、自動的に連番などが割り当てられるようになります。


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

@Entity
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private int price;

    // getter, setter, コンストラクタ省略
}

上記のようにGenerationType.IDENTITYを指定すると、データベースのオートインクリメント機能を使って主キーが自動採番されます。Pleiades + Gradle の環境でも、特別な設定は不要でこの方式が使えます。

5. フィールドとカラムのマッピング（@Column）

JPAでは、エンティティクラスのフィールドとデータベースのカラムを自動的にマッピングしてくれます。ただし、細かい設定を行いたいときは、@Columnアノテーションを使って制御できます。

たとえば、カラム名を明示的に指定したい場合や、長さやNULL制約などを設定したい場合に便利です。


import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;

@Entity
public class Customer {
    @Id
    private Long id;

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

    @Column(unique = true)
    private String email;

    // getter, setter, コンストラクタ省略
}

この例では、nameフィールドがfull_nameという名前のカラムと対応し、長さ制限やNULL不可の設定がされています。またemailフィールドにはunique = trueを指定することで、重複を許さない制約も付加できます。

このように、JPAの@Columnアノテーションを活用すれば、細かくカラムの設定をコントロールできます。

6. よく使うアノテーションの紹介（@Table、@Transientなど）

エンティティマッピングでは、@Entityや@Id、@Columnのほかにも便利なアノテーションがあります。ここではよく使われるものをいくつか紹介します。

@Table

@Tableは、エンティティがどのテーブルと対応するかを指定するアノテーションです。通常はクラス名がそのままテーブル名になりますが、テーブル名を変更したい場合に使います。


import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;

@Entity
@Table(name = "user_info")
public class User {
    @Id
    private Long id;
    private String name;
}

このように記述すると、Userクラスはuser_infoテーブルとマッピングされます。

@Transient

@Transientは、一時的に使用するフィールドでデータベースに保存しないものに使います。たとえば、画面表示用のフラグや計算結果など、永続化の必要がない場合に便利です。


import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Transient;

@Entity
public class Order {
    @Id
    private Long id;
    private String product;

    @Transient
    private int temporaryPrice; // DBには保存されない
}

@Transientが付けられたフィールドは、JPAがデータベースとマッピングを行わないため、処理の中だけで使いたい変数にぴったりです。

このように、@Table や @Transient などのアノテーションを知っておくことで、JPAのエンティティマッピングをより柔軟に使いこなすことができます。

7. エンティティクラス作成時の注意点

JPAでエンティティクラスを作成する際には、いくつか注意すべきポイントがあります。特に初心者が見落としやすいのが、デフォルトコンストラクタとgetter/setterの実装です。

まず、JPAは内部でリフレクションという仕組みを使ってエンティティを生成します。そのため、引数なしのコンストラクタ（デフォルトコンストラクタ）が必ず必要です。これがないと実行時エラーになる可能性があります。

また、各フィールドに対するgetterとsetterメソッドも必須ではありませんが、多くの場合で必要になります。特にSpringのDIやテンプレートエンジン（Thymeleafなど）では、getterを使ってデータを取り出すためです。


@Entity
public class Employee {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private String department;

    public Employee() {} // デフォルトコンストラクタ

    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 getDepartment() { return department; }
    public void setDepartment(String department) { this.department = department; }
}

このように、デフォルトコンストラクタ＋getter/setterを必ず書くようにすると、JPAのエンティティとして安定して動作します。

8. 実際のアプリケーションでの使用例

ここでは、エンティティを使って実際にデータを保存する一連の流れを紹介します。構成はController → Service → Repositoryの3層に分けます。これはSpringアプリケーションでよく使われる設計です。

Repositoryの定義


public interface EmployeeRepository extends JpaRepository<Employee, Long> {
}

Serviceクラス


@Service
public class EmployeeService {
    private final EmployeeRepository repository;

    public EmployeeService(EmployeeRepository repository) {
        this.repository = repository;
    }

    public void save(Employee employee) {
        repository.save(employee);
    }

    public List<Employee> findAll() {
        return repository.findAll();
    }
}

Controllerクラス（@Controller）


@Controller
public class EmployeeController {
    private final EmployeeService service;

    public EmployeeController(EmployeeService service) {
        this.service = service;
    }

    @GetMapping("/employees")
    public String list(Model model) {
        model.addAttribute("employees", service.findAll());
        return "employee-list";
    }
}

このように、JPAのエンティティクラスはSpringアプリケーション内でRepositoryとServiceを通じて活用されます。Controllerでは@ModelAttributeなどを使ってHTMLテンプレートと連携する形になります。

9. 初心者がつまづきやすいポイントと対策

最後に、JPAエンティティマッピングにおいて初心者がよくつまづくポイントと、その対策を紹介します。

アノテーションの付け忘れ

@Entityや@Idを付け忘れると、エンティティとして認識されません。特に@Idがないとエラーになりますので注意が必要です。

命名規則の違い

Javaのフィールド名とデータベースのカラム名が一致しないとき、@Columnで明示的にマッピングを指定する必要があります。特にアンダースコア（_）などが使われるケースでは注意が必要です。

getter/setterの未実装

getterがないと、SpringやThymeleafなどでデータを取り出す際に問題が発生することがあります。開発中に「値が表示されない」「データが反映されない」といったトラブルが起きたら、まずgetter/setterを確認しましょう。

パッケージの分け方

エンティティクラス、リポジトリ、サービス、コントローラーはそれぞれ別のパッケージに整理しておくと、可読性が高まり、今後の拡張もやりやすくなります。

これらのポイントを意識しておくことで、「JPAのエンティティ設計」や「エンティティクラスの基本」がしっかりと理解でき、トラブルの少ない開発が可能になります。

まとめ

JPAのエンティティマッピングの基本を振り返ろう

ここまで、JPAにおけるエンティティマッピングの基本について、@Entityを中心に丁寧に解説してきました。 JPAのエンティティとは、単なるJavaクラスではなく、データベースのテーブルと対応付けられた「永続化対象のオブジェクト」です。エンティティを正しく定義することで、SQLを意識せずにJavaのコードだけでデータの保存や取得、更新、削除といった操作が可能になります。これは、Spring BootやSpring MVCを使ったWebアプリケーション開発において、開発効率と保守性を大きく向上させる重要な仕組みです。

特に初心者が最初につまずきやすいのが、@Entityと@Idの役割です。 @Entityは「このクラスはJPAで管理する対象ですよ」と宣言するためのアノテーションであり、 @Idはテーブルの主キーに対応するフィールドを示します。さらに@GeneratedValueを組み合わせることで、データベース側のオートインクリメントを使ったID自動生成も簡単に実現できました。これらはJPAエンティティ設計の土台となる考え方なので、しっかり理解しておくことが大切です。

カラム設定や補助アノテーションの重要性

エンティティマッピングでは、フィールドとカラムの対応関係を細かく制御することも重要でした。 @Columnを使えば、カラム名の指定、文字数制限、NULL制約、ユニーク制約などをJavaコード上で明示できます。これにより、データベース設計とアプリケーションコードの意図を一致させやすくなり、後からコードを読む人にも「この項目はどういう制約を持つのか」が伝わりやすくなります。

また、@Tableによるテーブル名指定や、@Transientによる非永続化フィールドの扱いなど、実務でよく使われる補助的なアノテーションについても学びました。これらを知っているかどうかで、JPAエンティティを柔軟に設計できるかが大きく変わってきます。単に動くコードを書くのではなく、「どういうデータを、どう管理したいのか」を意識してエンティティを設計することが重要です。

エンティティ設計で意識すべき基本ルール

エンティティクラスを作成する際には、いくつかの基本ルールがありました。代表的なものが、引数なしのデフォルトコンストラクタを必ず用意すること、そして必要に応じてgetterとsetterを実装することです。 JPAは内部でリフレクションを使ってエンティティを生成・操作するため、これらが欠けていると実行時エラーや意図しない動作につながる可能性があります。

また、エンティティはRepository、Service、Controllerと連携して使われる存在であり、アプリケーション全体の設計の中心に位置します。そのため、パッケージ構成を整理し、責務を分けた設計を意識することで、規模が大きくなっても保守しやすいSpringアプリケーションを構築できます。 JPAのエンティティ設計は、単なる文法知識ではなく、アプリ全体の品質に直結する重要な要素なのです。

まとめとしてのサンプルエンティティ

最後に、この記事で学んだポイントを踏まえた、シンプルで基本に忠実なエンティティ例を確認してみましょう。 JPAエンティティの基本形として、何度も見返せる形になっています。


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

@Entity
public class SampleEntity {

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

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

    public SampleEntity() {}

    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; }
}

このような基本構成をしっかり押さえておけば、JPAのエンティティマッピングで大きく迷うことはなくなります。まずはシンプルなエンティティから始め、徐々にアノテーションや設計の幅を広げていくのがおすすめです。

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

生徒

「JPAのエンティティって、ただのクラスだと思っていましたけど、データベースと直接つながる大事な存在なんですね。」

先生

「そうだね。エンティティは、Javaとデータベースをつなぐ橋渡し役なんだ。設計がしっかりしていると、後の開発がとても楽になるよ。」

生徒

「@Entityや@Idの意味が分かってきたら、 RepositoryやServiceのコードも読みやすくなりました。」

先生

「それは良い変化だね。エンティティを理解できると、 SpringとJPAの全体像が一気につながってくるんだ。」

生徒

「これからは、とりあえず動くクラスじゃなくて、データの意味を考えながらエンティティを作ってみます。」