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

生徒

「Springで入力された数値をチェックしたいのですが、@Digitsアノテーションって何ですか？」

先生

「@Digitsアノテーションは、数値の整数部分と小数部分の桁数を制御するためのバリデーションです。例えば、金額や割合を入力するフォームで使われることが多いです。」

生徒

「なるほど！具体的にどのように使うのか知りたいです。」

先生

「それでは、@Digitsアノテーションの基本から使い方まで順番に解説していきましょう。」

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

JavaのSpringフレームワークにおける@Digitsアノテーションは、入力された数値が指定した桁数の範囲に収まっているかどうかを検証するためのバリデーションです。特にフォーム入力やリクエストパラメータで、桁数制限を設けたいときに活躍します。

例えば、整数部分は最大5桁、小数部分は2桁までといった制約を簡単に設定できます。これにより、不正な数値の入力を防ぎ、システムの信頼性を高めることができます。

2. 基本的な使い方

@Digitsは主にエンティティクラスやDTOクラスのフィールドに付与して使います。属性としては以下の2つが必須です。

integer：整数部分の最大桁数
fraction：小数部分の最大桁数

以下はサンプルコードです。


import jakarta.validation.constraints.Digits;

public class ProductForm {

    @Digits(integer = 5, fraction = 2)
    private BigDecimal price;

    // getter と setter
    public BigDecimal getPrice() {
        return price;
    }

    public void setPrice(BigDecimal price) {
        this.price = price;
    }
}

この例では、整数部分が最大5桁、小数部分が最大2桁までの数値だけを許容します。例えば「12345.67」はOKですが、「123456.78」や「123.456」はバリデーションエラーとなります。

3. 実際の入力例とエラーメッセージ

Spring Bootのバリデーション機能と組み合わせると、エラーが発生した際にメッセージを返すことができます。


import jakarta.validation.constraints.Digits;

public class OrderForm {

    @Digits(integer = 4, fraction = 1, message = "金額は整数4桁、小数1桁以内で入力してください")
    private BigDecimal amount;

    // getter と setter
}


入力値: 1234.5 → OK
入力値: 12345.6 → エラー (整数部分が5桁で制約違反)
入力値: 12.34 → エラー (小数部分が2桁で制約違反)

このようにして、ユーザーに分かりやすいエラーメッセージを提示できます。特に金額や割合の入力では有効に使われます。

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

Spring Framework超入門をAmazonで見る

※ Amazon広告リンク

4. @Digitsと他のアノテーションの組み合わせ

@Digitsは数値の桁数に関する制約を設定しますが、現実的なシステムではこれだけで不十分な場合もあります。そのため、@DecimalMinや@DecimalMaxと組み合わせることがよくあります。


import jakarta.validation.constraints.DecimalMin;
import jakarta.validation.constraints.DecimalMax;
import jakarta.validation.constraints.Digits;

public class SalaryForm {

    @DecimalMin(value = "1000.0", message = "給与は1000以上で入力してください")
    @DecimalMax(value = "99999.9", message = "給与は99999.9以下で入力してください")
    @Digits(integer = 5, fraction = 1, message = "整数5桁、小数1桁以内で入力してください")
    private BigDecimal salary;

    // getter と setter
}

このように組み合わせることで「範囲チェック」と「桁数チェック」を両立させることができます。業務システムではこうした複合的なバリデーションが重要になります。