Spring Bootの設定値を起動時に検証。設定カードが検査ゲートへ入るイラスト

実装・エラー解決

Spring Bootの@ConfigurationPropertiesを起動時に検証する|必須・範囲・型エラーの見分け方

夜間のファイル連携で「1回に何件出すか」を設定ファイルに移しました。検証環境ではアプリが起動したのに、設定した件数は 0。出力処理を始める夜まで誰も気づかなければ、翌朝には連携結果が届きません。

0 は整数に変換できます。そこで、Spring Bootが設定を読み込む時点で「この連携先へ一度に渡せるのは1〜500件」という条件も確かめます。@ConfigurationProperties と @Validated を使い、同じ 0 で起動できる版と停止する版を比べます。

この記事でわかること

  • 設定値の指定漏れ、範囲外、文字列から整数への変換エラーをログから見分ける。
  • 設定クラスへ条件を置き、実際の起動と6つのJUnitテストで確かめる。

記事と同じコードをダウンロードする

JDK 17とMaven 3.9系を用意し、ZIPを展開します。pom.xml のある場所で mvn package を実行すると、JUnitの6件を確認して実行用JARを作ります。

ZIPには起動クラス、設定クラス、JUnitテスト、Maven設定、実行手順が入っています。

0件で起動できてしまうのは、整数への変換を通るから

連携先の仕様は「1回に1〜500件」です。設定キーを export.batch-size とし、既定値は置きません。環境ごとの設定漏れを起動時に見つける運用だからです。正常な設定を指定し、まず動く状態を手元で確認します。

正常な設定で起動

mvn package
java -jar target/export-config-validation-1.0.0.jar --export.batch-size=250

正常版の出力から抜粋

EXPORT_READY batchSize=250

次に、サンプルを別の作業フォルダーに用意し、ExportProperties.java の @Validated の行だけを外します。制約アノテーションと設定クラスの登録は残します。mvn -DskipTests package で故障版のJARを作り、下のコマンドを実行します。この操作は故障時の挙動を観察するためのもので、修正版は通常どおりテストを含めてビルドします。

0件で起動するコマンド

java -jar target/export-config-validation-1.0.0.jar --export.batch-size=0

故障版の出力から抜粋

EXPORT_READY batchSize=0

故障版の終了コードは0です。Springは文字列の 0 を Integer の0へ変換でき、件数として使えるかは検証されていません。設定クラスが登録されていることと、設定に付けた制約が検証されることを、ここで分けて見ます。

設定クラスで必須と1〜500の条件を検証する

修正版の ExportProperties は、Integer で未指定の null と指定された0を区別します。未指定には @NotNull、0には @Min(1)、501には @Max(500) が対応します。@Validated を設定クラスに付けて、Spring Bootによるバインド時にこれらの制約を確かめます。

ExportProperties.java(全文)

package info.syachiku.export;

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotNull;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

@ConfigurationProperties("export")
@Validated
public record ExportProperties(
        @NotNull @Min(1) @Max(500) Integer batchSize) {
}
どの段階で起動を止めるか

外部設定export.batch-size

  1. 整数へ変換 "250" → 250

    ここで停止abc は整数にできない

  2. 制約を検証 必須、1〜500件

    ここで停止未指定・0・501

  3. 起動が完了 250 を使える状態になる

制約が効く前提は、Springにこの設定クラスが登録されていることです。サンプルでは ExportApplication に @EnableConfigurationProperties(ExportProperties.class) を置きます。POMに spring-boot-starter-validation を追加し、Jakarta Validationの実装をクラスパスに入れます。EXPORT_READY はSpringの起動が成功し、登録した設定を取得できた後にだけ表示されます。

ExportApplication.java(全文)

package info.syachiku.export;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;

@SpringBootApplication
@EnableConfigurationProperties(ExportProperties.class)
public class ExportApplication {

    public static void main(String[] args) {
        try (var context = SpringApplication.run(ExportApplication.class, args)) {
            var settings = context.getBean(ExportProperties.class);
            System.out.printf("EXPORT_READY batchSize=%d%n", settings.batchSize());
        }
    }
}
pom.xml(全文)
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.16</version>
        <relativePath/>
    </parent>
    <groupId>info.syachiku</groupId>
    <artifactId>export-config-validation</artifactId>
    <version>1.0.0</version>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

この例はJava 17、Spring Boot 3.5.16の構成です。new ExportProperties(0) を直接呼ぶだけでは、この起動時の検証経路を通りません。既存案件で設定クラスを登録するときは、明示登録と設定クラスのスキャンのうち、プロジェクトで使っている方式に揃えます。Spring Boot公式の設定プロパティ検証

起動ログのPropertyとReasonから、直すキーと値を決める

修正版のJARで設定の未指定・0・abc を試します。すべて終了コード1で、EXPORT_READY は出力されません。未指定を再現する前に、起動フォルダーの設定ファイル、環境変数、JVMオプションから件数を別途渡していないか確認します。

修正版で失敗する3つのコマンド

java -jar target/export-config-validation-1.0.0.jar
java -jar target/export-config-validation-1.0.0.jar --export.batch-size=0
java -jar target/export-config-validation-1.0.0.jar --export.batch-size=abc

未指定の場合は NotNull の検証で止まります。Property には Javaのフィールド名に沿って export.batchSize と表示されました。直すキーは export.batch-size です。想定の環境でそのキーが設定されているかを確かめます。

未指定の起動ログから抜粋

Property: export.batchSize
Value: "null"
Reason: null は許可されていません

0の場合は整数に変換できています。Value が0、Reason が下限を示すため、設定元にある0を連携先が受理する値に変更します。上限超過の501なら、同じキーで上限の制約が失敗します。

0件の起動ログから抜粋

Property: export.batchSize
Value: "0"
Reason: 1 以上の値にしてください

abc の場合は整数へ変換できず、範囲を確かめるところまで進みません。ログには export.batch-size と設定キーの形で表示されました。ここで読むのは末尾の NumberFormatException と入力値です。たとえば設定に件数の単位を付けているなら、数値だけの指定へ直します。

abcの起動ログから抜粋

Property: export.batch-size
Value: "abc"
Reason: failed to convert java.lang.String to @jakarta.validation.constraints.NotNull @jakarta.validation.constraints.Min @jakarta.validation.constraints.Max java.lang.Integer (caused by java.lang.NumberFormatException: For input string: "abc")

上は実行ログの抜粋です。エラーメッセージの言語が異なっても、どの Property に何を渡し、どの段階で失敗したかを見れば切り分けられます。「ファイルには250を書いたのに、実際は0を読んでいる」ときは、どの設定元が優先されたかを確認します。

関連記事Spring Bootでapplication.propertiesを外部化する方法|環境変数とProfileの優先順位 ファイルに書いた件数と実際に読まれた件数が違う場合に、環境変数・Profile・コマンドラインの優先順位を確認できます。 記事を読む

反対に、0を渡しても起動が止まらないときは、範囲のアノテーションを増やす前に3点を見ます。設定クラスに @Validated があるか。起動クラスから設定クラスが登録されているか。検証スターターが実行時の依存に入っているか。ローカルで直したソースと、検証環境で実際に動かしたJARが同じ版かも照合すると、設定の誤りと反映漏れを分けられます。

JUnitで1と500が通り、欠落・0・501・abcで止まることを確かめる

ApplicationContextRunner は、各テストで新しいSpringコンテキストを作ります。ExportApplication を読み込むので、起動例と同じ設定クラスの登録経路を通ります。成功ケースでは起動できたことに加え、Beanから取得した値が入力と同じことを確認します。失敗ケースでは、起動を止めた理由をフィールドと制約コードまで照合します。

設定の入力と、JUnitで確認する結果
入力起動確認する結果
1成功Beanに1が入る
500成功Beanに500が入る
未指定失敗batchSize の NotNull
0失敗batchSize の Min
501失敗batchSize の Max
abc失敗原因に ConversionFailedException がある
ExportPropertiesTest.java(全文)
package info.syachiku.export;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import org.junit.jupiter.params.provider.ValueSource;
import org.springframework.boot.context.properties.bind.validation.BindValidationException;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import org.springframework.core.convert.ConversionFailedException;
import org.springframework.validation.FieldError;

import static org.assertj.core.api.Assertions.assertThat;

class ExportPropertiesTest {

    private final ApplicationContextRunner contextRunner =
            new ApplicationContextRunner().withUserConfiguration(ExportApplication.class);

    @ParameterizedTest
    @ValueSource(ints = {1, 500})
    void acceptsBothBoundaries(int size) {
        contextRunner.withPropertyValues("export.batch-size=" + size).run(context -> {
            assertThat(context).hasNotFailed();
            assertThat(context.getBean(ExportProperties.class).batchSize()).isEqualTo(size);
        });
    }

    @Test
    void missingSizeFailsTheRequiredConstraint() {
        contextRunner.run(context ->
                assertBatchSizeViolation(context.getStartupFailure(), "NotNull"));
    }

    @ParameterizedTest
    @CsvSource({"0, Min", "501, Max"})
    void outOfRangeSizeFailsItsConstraint(String value, String constraint) {
        contextRunner.withPropertyValues("export.batch-size=" + value).run(context ->
                assertBatchSizeViolation(context.getStartupFailure(), constraint));
    }

    @Test
    void nonNumericValueFailsDuringConversion() {
        contextRunner.withPropertyValues("export.batch-size=abc").run(context -> {
            Throwable failure = context.getStartupFailure();
            assertThat(failure).isNotNull();
            assertThat(findCause(failure, ConversionFailedException.class)).isNotNull();
            assertThat(findCause(failure, BindValidationException.class)).isNull();
        });
    }

    private static void assertBatchSizeViolation(Throwable failure, String constraint) {
        assertThat(failure).as("Spring context startup failure").isNotNull();
        var violation = findCause(failure, BindValidationException.class);
        assertThat(violation).isNotNull();
        assertThat(violation.getValidationErrors().getAllErrors()).anySatisfy(error -> {
            assertThat(error).isInstanceOf(FieldError.class);
            assertThat(((FieldError) error).getField()).isEqualTo("batchSize");
            assertThat(error.getCode()).isEqualTo(constraint);
        });
    }

    private static <T extends Throwable> T findCause(Throwable failure, Class<T> type) {
        for (Throwable cause = failure; cause != null; cause = cause.getCause()) {
            if (type.isInstance(cause)) {
                return type.cast(cause);
            }
        }
        return null;
    }
}

mvn test で6件が成功します。故障版をテストすると、未指定と0・501を拒む3件が失敗します。abc を拒む1件は成功します。型に変換できることと、連携先が受け取れる値であることは、別々のテストで確かめられます。Spring Boot公式のApplicationContextRunnerの使い方

ここで確かめたのは、設定読込からSpringの起動成否までです。実際の夜間実行を確認する場合は、ジョブが起動した時刻、1回の出力件数、連携先の受領結果を別の試験で照合します。

レビューで、設定ミスがどの時点で見つかるかを説明する

今の構成だと0件でも起動します。夜間ジョブまで待たずに気づけるよう、起動時の設定クラスに1〜500件の条件を置きましょう。未指定と下限・上限の前後を、起動テストで確かめてください。

返答では、どの条件に合わせて値を決めたかと、実際にどこで止まるかを示します。「連携先の取り込み上限が500件です。0・501と設定漏れは起動時に拒否し、1・500で起動できることをテストしました。運用手順にも export.batch-size の単位と範囲を追記しました。」ここまであれば、設定を変える担当者も値を選べます。

  • 件数・秒・ミリ秒など、設定の単位と許容範囲を運用手順へ書いたか。
  • 設定漏れを拒む運用か、全環境で同じ既定値を許すかを決めたか。
  • 設定クラスをSpringに登録し、実行したときに制約の評価まで進むか。
  • 正常な境界値と、その一つ外の値をセットで確認したか。
  • ログから直すキーと値を特定し、設定を変更した後に起動を再確認したか。

設定をどこで読み込み、アプリの各処理へどう渡すかを一つのWebアプリで学ぶなら、『作って学ぶ Spring Boot入門』が入口になります。

書籍「作って学ぶ Spring Boot入門」の表紙
商品画像:Amazon.co.jp
PR Java新人・若手向け

作って学ぶ Spring Boot入門

多田 真敏 (著)

Spring Bootを、動くWebアプリを作りながら覚える。

Controller、画面、DB連携などを一つのアプリとして実装できます。Java基礎からSpringの現場へ進む橋渡しに向く一冊です。

  • Spring Bootを手を動かして学びたい
  • Webアプリ開発の流れをつかみたい

当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。

関連記事Spring Boot初心者におすすめの本3冊|現場で必要な力を身につける 設定の読込を確認できたら、アプリのHTTP応答やDBに残った結果をどう確かめるかへ進めます。 記事を読む 関連記事Spring Bootで400 Bad Requestになる原因|Controllerに値が入らない時の確認順 アプリが起動した後、HTTP入力の変換や検証で400が返る場合は、Controllerとリクエストのどこを確認するかを実行例で追えます。 記事を読む

夜間処理に渡す値は、起動時に確認する

設定した件数が使えるかは、文字列を整数に変換した後に決まります。今回の修正では、@ConfigurationProperties に必須と範囲の条件を置き、@Validated で起動時に確認しました。手元の設定でも、受理する境界値と拒む値を1組ずつ選び、実際の起動結果とエラーの理由を確かめてください。

-実装・エラー解決
-, ,