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

新人

「Springでデータベースから情報を取り出す方法って、難しいんですか？」

先輩

「Spring Data JPAを使えば、クエリメソッドという仕組みで、簡単にデータ取得ができるんだよ。」

新人

「それって、自分でSQLを書かなくてもいいんですか？」

先輩

「そう！メソッド名をあるルールに従って書くだけで、Springが自動でSQLを作ってくれるんだ。今日はその基本を一緒に学ぼう。」

1. クエリメソッドとは？

クエリメソッドとは、Spring Data JPAでデータベースから情報を取得するための仕組みで、特別なSQL文を書くことなく、メソッド名のルールに従って定義するだけでデータ取得ができる便利な機能です。

例えば、ユーザー情報を名前で検索したい場合、findByNameという名前のメソッドを定義するだけで、Springが自動的に「名前に一致するユーザーを探すSQL」を作ってくれます。

このように、クエリメソッドは初心者でも簡単に使えるデータ取得方法として、Spring BootやSpring MVCと組み合わせて非常によく使われています。

2. Spring Data JPAでクエリメソッドが使われる理由

Spring Data JPAは、Javaアプリケーションとデータベースをつなぐための仕組み（JPA）を、より簡単に扱えるようにしてくれるライブラリです。

その中でもクエリメソッドは、以下のような理由からよく使われています：

SQLを自分で書かなくてもよい（開発が早くなる）
読みやすく保守しやすいコードになる
簡単な取得処理ならメソッド名だけで完結する

特に初心者にとっては、「SQLの文法」や「DBの細かい知識」がなくてもクエリメソッドでスムーズにデータ取得できるのは大きなメリットです。

3. リポジトリインターフェースの基本的な書き方

クエリメソッドを使うには、まずリポジトリインターフェースを定義します。これは、JpaRepositoryを継承するだけで使えます。

以下は、名前でユーザーを検索するfindByNameというクエリメソッドの基本例です。


import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {
    // 名前でユーザーを検索するクエリメソッド
    List<User> findByName(String name);
}

このfindByNameというメソッド名だけで、Spring Data JPAは「nameというカラムで検索するSQL文」を自動で作ってくれます。

なお、実際にこのリポジトリを使うときには、Springが自動で中身を実装してくれるため、自分でSQLや実装を書く必要はありません。

続いての記事では、クエリメソッドの命名規則や、@Controllerでの使い方について解説していきます。

4. よく使うクエリメソッドの命名規則

クエリメソッドを定義する際には、Spring Data JPAが認識できる決まった命名ルールに従う必要があります。このルールを守ることで、SQLを書かずに自動でデータベースから情報を取得できます。

以下に代表的な命名規則を紹介します：

findBy：指定した条件でデータを検索
countBy：指定した条件に合う件数を取得
existsBy：条件に一致するデータが存在するかどうかを判定
deleteBy：条件に一致するデータを削除

たとえば、ユーザーのメールアドレスで検索したい場合は、次のようなメソッドになります。


List<User> findByEmail(String email);

条件を複数指定したい場合は、AndやOrなどを使って、以下のように書くことができます。


List<User> findByNameAndAge(String name, int age);
List<User> findByStatusOrRole(String status, String role);

このように、クエリメソッドの命名規則を理解しておけば、複雑なSQL文を自分で書かなくても、Springが自動的に最適な処理を実行してくれます。

5. サンプル：名前でデータを取得するクエリメソッド

ここでは、実際にfindByNameというクエリメソッドを使って、名前でデータを取得する具体例を見てみましょう。まず、対象のエンティティであるUserクラスを定義します。


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

@Entity
public class User {
    @Id
    private Long id;
    private String name;
    private int age;

    // getterとsetter（省略可能）
}

次に、リポジトリインターフェースを作成します。


import org.springframework.data.jpa.repository.JpaRepository;
import java.util.List;

public interface UserRepository extends JpaRepository<User, Long> {
    List<User> findByName(String name);
}

このfindByNameを使えば、「特定の名前を持つユーザー」を簡単に取得できます。Spring Data JPAがnameカラムに対応するSQLを自動で作ってくれます。

6. @Controllerを使ってデータを画面に表示する処理の書き方

ここでは、@Controllerを使って、取得したユーザーの情報をHTML画面に一覧表示する方法を解説します。Spring MVCの仕組みを使って、リポジトリから取得したデータをビュー（テンプレート）に渡す流れです。

まず、ユーザー一覧を表示するコントローラクラスを作成します。


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 java.util.List;

@Controller
public class UserController {

    @Autowired
    private UserRepository userRepository;

    @GetMapping("/users")
    public String getUsers(Model model) {
        List<User> users = userRepository.findByName("佐藤");
        model.addAttribute("users", users);
        return "user-list";
    }
}

@GetMapping("/users")は、「/users」というURLにアクセスがあったときに呼び出されます。この中でuserRepository.findByName("佐藤")を使って、名前が「佐藤」のユーザー一覧を取得しています。

取得したデータはModelを使って「user-list」というビューに渡されます。ビュー側では、Thymeleafなどのテンプレートエンジンでループ処理して表示します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>ユーザー一覧</title>
</head>
<body>
    <h2>ユーザー一覧</h2>
    <ul>
        <li th:each="user : ${users}">
            名前：<span th:text="${user.name}"></span>、
            年齢：<span th:text="${user.age}"></span>
        </li>
    </ul>
</body>
</html>

このように、@Controllerで処理を記述し、リポジトリから取得したデータをモデルに渡すだけで、簡単にデータ表示が可能です。

Spring BootとSpring Data JPAを使えば、HTMLテンプレートと連携した画面表示の仕組みも非常にシンプルに構築できます。

次の記事では、複数条件でのクエリメソッドの使い方や注意点について、さらに深掘りしていきます。

7. 条件を複数組み合わせたクエリメソッドの使い方

Spring Data JPAでは、ひとつの条件だけでなく、複数の条件を組み合わせた検索も簡単に行えます。メソッド名にAndやOrを使うことで、条件を複合的に指定することができます。

たとえば、「名前が佐藤で、年齢が30歳のユーザー」を検索したい場合、次のようにfindByNameAndAgeと命名します。


List<User> findByNameAndAge(String name, int age);

このメソッドを呼び出すと、Spring Data JPAが自動でnameとageの両方に一致するデータを検索するSQLを生成してくれます。

また、「ステータスが有効か、または年齢が18歳以上のユーザー」を取得したい場合は、次のように書けます。


List<User> findByStatusOrAgeGreaterThan(String status, int age);

このように、クエリメソッドでは「And」「Or」「GreaterThan」「LessThan」「Like」など、いくつもの演算子を組み合わせて柔軟な検索が可能です。

SQLの構文に詳しくない初心者でも、メソッド名だけで必要な条件検索が実現できる点が、クエリメソッドの大きな魅力です。

8. クエリメソッド使用時の注意点

クエリメソッドは便利ですが、いくつかの注意点もあります。特に初心者がつまずきやすいポイントを紹介します。

メソッド名のスペルミス

クエリメソッドでは、メソッド名の単語やプロパティ名のスペルが重要です。たとえば、エンティティのプロパティ名がnameなのに、findByNamesと書いてしまうと、Springが対応するカラムを見つけられず、エラーになります。

スペルミスを防ぐためには、Pleiadesでコード補完を活用したり、実装前にエンティティのフィールド名を確認しておくとよいでしょう。

戻り値の型に注意

データを1件だけ取得したい場合には、戻り値の型をOptional<User>やUserと指定することができます。複数件を取得したい場合は、List<User>などのコレクション型にする必要があります。


User findByEmail(String email); // 単一結果
List<User> findByAgeGreaterThan(int age); // 複数結果

条件によっては、1件もデータが見つからないこともあるため、Optionalを使うとnullを避けやすくなります。

複雑すぎるメソッド名

条件を多く組み合わせすぎると、メソッド名が非常に長くなってしまいます。その場合は、クエリメソッドではなく、@Queryアノテーションを使ってJPQLやネイティブSQLを指定した方が読みやすくなるケースもあります。

クエリメソッドは便利ですが、シンプルな条件にとどめて使うのが初心者にはおすすめです。

9. 初心者におすすめの学び方と、次に学ぶべきステップ

クエリメソッドは、Spring Data JPAで最初に覚えておきたい基本的な機能です。SQLを知らなくてもデータを取得できるという点で、特に初心者にとっては大きな助けになります。

これから学ぶ人におすすめしたいのは、まず「エンティティの作成」「リポジトリの作成」「コントローラでの表示」といった一連の流れを自分の手で繰り返し書いてみることです。

また、クエリメソッドの命名ルールは奥が深いので、実際にいろいろなパターンで試してみると理解が深まります。公式ドキュメントの命名規則表も参考になります。

そして、クエリメソッドに慣れてきたら、次は@Queryアノテーションを使ったJPQLの記述や、ネイティブSQLの活用にも挑戦してみましょう。より柔軟で細かいデータ操作ができるようになります。

さらに、ページング機能（Pageable）や、ソート機能（Sort）なども、クエリメソッドと組み合わせて使えるので、少しずつステップアップして学ぶと良いでしょう。

クエリメソッドは、JavaとSpringの連携によるデータ取得の第一歩です。この知識をしっかり身につければ、より実践的なWebアプリケーションの構築にも自信が持てるようになります。

この記事を読んだ人からの質問

クエリメソッドを使った簡単なデータ取得