JavaのSpringで使う@Maxアノテーションを完全ガイド！初心者でもわかる数値バリデーション入門

Springの@Maxアノテーション

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

生徒

「Springで入力チェックをするときに、数値の最大値を決める方法ってありますか？」

先生

「はい、ありますよ。@Maxアノテーションを使えば、数値が指定した最大値以下であることを簡単に検証できます。」

生徒

「例えば、年齢が120歳以下でなければならない、みたいな条件もできますか？」

先生

「もちろんできますよ。それでは@Maxアノテーションの基本的な使い方から見ていきましょう。」

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

@MaxアノテーションはJavaのBean Validation仕様に含まれる標準的なバリデーション機能で、指定した最大値を超えていないかを検証します。Spring Bootでも簡単に利用でき、年齢や点数、商品の数量や価格などの「上限を設けたい」ケースでよく使われます。

例えば「年齢は120歳以下」「商品数は100個以下」といった現実的な制約を簡単に実装できます。

2. 基本的な使い方

最大値を指定するには、対象のフィールドに@Maxを付与して数値を設定します。


import jakarta.validation.constraints.Max;

public class UserForm {

    @Max(120)
    private int age;

    // getter setter 略
}

この場合、ageフィールドに121以上の値を入力するとバリデーションエラーになります。

3. 実行例を確認しよう

Spring Bootアプリケーションで実行すると、条件を超える値が入力された際にエラーメッセージが表示されます。


ageが150の場合：
→ エラー：must be less than or equal to 120

このように、指定された最大値を超える入力は自動的にエラーと判定されます。

4. エラーメッセージをカスタマイズする

@Maxにはmessage属性を指定でき、よりわかりやすい日本語のエラーメッセージをユーザーに提示できます。


public class UserForm {

    @Max(value = 120, message = "年齢は120歳以下で入力してください")
    private int age;

}

このようにすると、ユーザーにとって理解しやすいエラーメッセージになります。

5. 数量や価格のチェックに活用

@Maxは年齢だけでなく、数量や価格といった値にも利用できます。例えば「数量は100個まで」「価格は10000円以下」といった制約を簡単に書けます。


public class ProductForm {

    @Max(value = 100, message = "商品の数量は100以下で入力してください")
    private int quantity;

    @Max(value = 10000, message = "価格は10000円以下にしてください")
    private int price;

}

これにより、ユーザーが非現実的な数値を入力するのを防げます。

6. Spring Bootのコントローラでの利用

Spring Bootでは、コントローラで@Validを指定するだけで、@Maxによるバリデーションを自動で実行できます。


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

@Controller
public class UserController {

    @PostMapping("/register")
    public String register(@Valid UserForm form, BindingResult result) {
        if (result.hasErrors()) {
            return "registerForm";
        }
        return "success";
    }
}

これにより、最大値を超える入力があれば自動でエラーが検出され、エラーページに戻す処理が実行されます。

7. @Maxと@NotNullの併用

@Maxは数値がnullである場合にはチェックされません。そのため必須入力も同時に求めるなら@NotNullや@NotBlankを併用するのが一般的です。


import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Max;

public class PaymentForm {

    @NotNull(message = "金額は必須です")
    @Max(value = 50000, message = "金額は50000円以下で入力してください")
    private Integer amount;

}

このように設定すると、必須チェックと最大値チェックを同時に行えます。