夜間のファイル連携で「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をダウンロード GitHubでコード全文と実行手順を見る
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
- 整数へ変換
"250"→250ここで停止
abcは整数にできない - 制約を検証 必須、1〜500件
ここで停止未指定・0・501
- 起動が完了
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を読んでいる」ときは、どの設定元が優先されたかを確認します。
反対に、0を渡しても起動が止まらないときは、範囲のアノテーションを増やす前に3点を見ます。設定クラスに @Validated があるか。起動クラスから設定クラスが登録されているか。検証スターターが実行時の依存に入っているか。ローカルで直したソースと、検証環境で実際に動かしたJARが同じ版かも照合すると、設定の誤りと反映漏れを分けられます。
JUnitで1と500が通り、欠落・0・501・abcで止まることを確かめる
ApplicationContextRunner は、各テストで新しいSpringコンテキストを作ります。ExportApplication を読み込むので、起動例と同じ設定クラスの登録経路を通ります。成功ケースでは起動できたことに加え、Beanから取得した値が入力と同じことを確認します。失敗ケースでは、起動を止めた理由をフィールドと制約コードまで照合します。
| 入力 | 起動 | 確認する結果 |
|---|---|---|
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入門
Spring Bootを、動くWebアプリを作りながら覚える。
Controller、画面、DB連携などを一つのアプリとして実装できます。Java基礎からSpringの現場へ進む橋渡しに向く一冊です。
- Spring Bootを手を動かして学びたい
- Webアプリ開発の流れをつかみたい
当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。
この記事とあわせて読みたい
夜間処理に渡す値は、起動時に確認する
設定した件数が使えるかは、文字列を整数に変換した後に決まります。今回の修正では、@ConfigurationProperties に必須と範囲の条件を置き、@Validated で起動時に確認しました。手元の設定でも、受理する境界値と拒む値を1組ずつ選び、実際の起動結果とエラーの理由を確かめてください。



