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

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

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

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

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

2. 基本的な使い方

2. 基本的な使い方

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

import jakarta.validation.constraints.Max;

public class UserForm {

    @Max(120)
    private int age;

    // getter setter 略
}

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

3. 実行例を確認しよう

3. 実行例を確認しよう

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

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

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

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

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

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

public class UserForm {

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

}

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

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

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のコントローラでの利用

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の併用

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;

}

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

8. BigDecimalを使う場合の注意点

8. BigDecimalを使う場合の注意点

@Maxはlong型を基準に評価するため、小数を扱う場合には@DecimalMaxを使うのが適しています。例えば価格をBigDecimalで管理するケースでは@DecimalMaxを使うことで誤判定を避けられます。

整数だけを扱う場合は@Max、小数や金額を扱う場合は@DecimalMaxを選ぶようにしましょう。

9. よくある注意点

9. よくある注意点

@Maxを使うときは、アプリケーション側だけでなくデータベースの制約と一致させることが大切です。例えばデータベースのカラムに制約がなければ不正な値が保存される可能性があります。また、フロントエンドでも入力制御を行い、ユーザーが入力段階で上限を超えないようにする工夫が望ましいです。

さらに、ビジネスロジック層でも二重にチェックを行うことで、より安全なアプリケーション設計が可能になります。