先生と生徒の会話形式で理解しよう

生徒

「Springで数値の範囲を制限してチェックする方法はありますか？」

先生

「はい、@Rangeアノテーションを使えば、最小値や最大値を簡単に指定して入力値を検証できますよ。」

生徒

「例えば年齢が0以上120以下じゃないといけない、というチェックもできますか？」

先生

「もちろん可能です。実際のコードを見ながら一緒に学んでいきましょう。」

1. @Rangeアノテーションとは？

@Rangeアノテーションは、Hibernate Validatorが提供する数値バリデーションのためのアノテーションです。JavaのSpringアプリケーションでフォーム入力やリクエストパラメータを検証するときによく使われ、整数値や小数値が指定された範囲内に収まっているかを自動的にチェックしてくれます。例えば年齢、価格、数量などの制御に最適です。

2. @Rangeアノテーションの基本的な使い方

SpringのDTOやエンティティクラスでフィールドに@Rangeを付与するだけで数値チェックが可能です。以下は年齢を検証する例です。


import org.hibernate.validator.constraints.Range;

public class UserForm {

    @Range(min = 0, max = 120, message = "年齢は0以上120以下で入力してください")
    private int age;

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

この例では年齢が0未満または120を超えるとエラーとなり、ユーザーにエラーメッセージを返すことができます。

3. Spring MVCでのバリデーション処理

Spring MVCでは@ValidとBindingResultを使うことで@Rangeによる数値チェックを自動的に行えます。以下はコントローラでの利用例です。


import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import jakarta.validation.Valid;

@Controller
public class UserController {

    @GetMapping("/age")
    public String showForm(UserForm userForm) {
        return "ageForm";
    }

    @PostMapping("/age")
    public String submitForm(@Valid UserForm userForm, BindingResult bindingResult, Model model) {
        if (bindingResult.hasErrors()) {
            return "ageForm";
        }
        model.addAttribute("age", userForm.getAge());
        return "success";
    }
}

これにより、フォーム入力の数値が範囲外なら自動的にエラーメッセージを表示できます。

4. @Rangeと@Min/@Maxの違い

数値バリデーションには@Minと@Maxもありますが、@Rangeは1つのアノテーションで最小値と最大値の両方を指定できます。コードが簡潔になり、可読性も高まるのが利点です。


@Min(0)
@Max(120)
private int age;

このように書く代わりに、@Rangeを使えば1行で表現できます。

5. エラーメッセージのカスタマイズ

初心者が混乱しないように、エラーメッセージは具体的に書くのがポイントです。例えば価格のチェックなら以下のように設定できます。


@Range(min = 100, max = 10000, message = "価格は100円以上10000円以下で入力してください")
private int price;

こうすることでユーザーが何を修正すれば良いか明確に理解できます。

6. 入力チェックの実用例

@Rangeアノテーションは年齢や価格以外にも、在庫数や数量制限など幅広い場面で使えます。例えば商品数量の入力チェックに適用できます。


@Range(min = 1, max = 100, message = "数量は1以上100以下で入力してください")
private int quantity;

7. HTMLフォームとの組み合わせ

フロントエンドのHTMLフォームで入力タイプをnumberにすれば、ブラウザ側でも数値入力の制御が可能です。Springの@Rangeと併用することで二重のバリデーションを実現できます。


<form action="/age" method="post">
    <label for="age">年齢</label>
    <input type="number" id="age" name="age" min="0" max="120" required />
    <button type="submit">送信</button>
</form>