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

生徒

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

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

Spring FrameworkやThymeleafを使った Webアプリ開発の全体像をやさしく理解したい人には、この入門書が定番です。

Spring Framework超入門をAmazonで見る

※ Amazon広告リンク

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>

8. 初心者が理解しておきたいポイント

初心者がSpringの@Rangeアノテーションを使うときに覚えておきたいポイントは以下の通りです。

数値が範囲内かどうかを簡単に検証できる
@Minと@Maxをまとめて書けるので便利
エラーメッセージはわかりやすい日本語にする
年齢や価格、数量など様々な数値チェックに利用できる
HTMLのminやmaxと組み合わせるとより安心

これらを理解すれば、Springで安全でわかりやすい数値バリデーションを実装できるようになります。

まとめ

@Rangeアノテーションで学んだ数値バリデーションの基本

この記事では、JavaのSpringフレームワークで利用できる@Rangeアノテーションについて、初心者の方にも理解しやすい形で解説してきました。 Webアプリケーションでは、ユーザーが入力する数値をそのまま信用することはできません。年齢、価格、数量、在庫数などの数値入力は、必ず「正しい範囲」に収まっているかを確認する必要があります。その役割をシンプルに担ってくれるのが、Hibernate Validatorが提供する@Rangeアノテーションです。

@Rangeを使うことで、「最小値以上、最大値以下」という条件をひとつのアノテーションで表現でき、コードの見通しが良くなります。 @Minと@Maxを別々に書く方法と比べて、設定内容が一目で理解できる点も大きなメリットです。 Spring MVCやSpring Bootのフォームバリデーションにおいて、数値チェックの基本として覚えておきたいアノテーションのひとつと言えるでしょう。

Spring MVCと@Validを組み合わせた実践的な流れ

記事中で紹介したように、@Rangeアノテーションは単体で使うのではなく、 @ValidやBindingResultと組み合わせることで真価を発揮します。フォームから送信された数値は、コントローラに到達する前に自動的に検証され、範囲外の値が入力された場合はエラー情報としてまとめられます。

この仕組みにより、コントローラの中で数値チェックを書く必要がなくなり、ビジネスロジックに集中できるようになります。バリデーションの責務をアノテーションに任せることで、コードの可読性と保守性が大きく向上します。 Springでの開発では、この「役割分担」の考え方が非常に重要です。

HTMLフォームと組み合わせた安全な入力チェック

数値バリデーションは、サーバー側だけでなくフロントエンド側でも意識することが大切です。 HTMLのinput type="number"にminやmax属性を設定することで、ブラウザレベルでも入力制御が可能になります。これにSpringの@Rangeを組み合わせることで、ユーザー体験を損なわず、かつ安全性の高い入力チェックを実現できます。

フロントエンドとバックエンドの両方で数値の範囲を意識することは、実務でのWebアプリケーション開発において非常に重要な考え方です。どちらか一方に依存するのではなく、複数の層でチェックを行うことで、より堅牢なシステムを構築できます。

まとめとしてのサンプルプログラム

最後に、この記事で学んだ内容を振り返るためのサンプルプログラムを確認してみましょう。年齢と数量の両方に@Rangeを適用した、実務でもよく使われる例です。


import org.hibernate.validator.constraints.Range;

public class OrderForm {

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

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

    public int getAge() {
        return age;
    }

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

    public int getQuantity() {
        return quantity;
    }

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

このように@Rangeを設定しておくことで、数値入力に関するルールをクラス定義の時点で明確に表現できます。後からコードを読む人にとっても、「どの範囲の値を想定しているのか」がすぐに理解できる点は大きな利点です。

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

生徒

「@Rangeを使うだけで、年齢や数量のチェックがこんなに簡単になるとは思いませんでした。自分でif文を書かなくてもいいんですね。」

先生

「その通りです。Springでは、よくある入力チェックをアノテーションで宣言的に書けるようになっています。 @Rangeは数値バリデーションの基本なので、ぜひ覚えておきましょう。」

生徒

「HTMLのminやmaxと組み合わせると、ユーザーにも優しいフォームになりますね。」

先生

「そうですね。入力しやすさと安全性の両立が大切です。 @Rangeを正しく使えるようになると、 Springでのフォーム開発がぐっと楽になりますよ。」

生徒

「これからは数値入力があるフォームでは、まず@Rangeを使えるか考えてみます。」