Spring Bootの@ConfigurationProperties入門！初心者でもわかる型安全バインドとバリデーション

1. ConfigurationPropertiesとは？

1. ConfigurationPropertiesとは？

@ConfigurationPropertiesは、Spring Bootで設定ファイル（application.propertiesやapplication.yml）の値をJavaクラスにマッピングするためのアノテーションです。

例えば、接続設定や認証情報、APIの設定など、複数のプロパティをひとつのクラスにまとめて管理したいときに非常に役立ちます。

@Valueのように個別に読み込むのではなく、一括でバインドできるのがポイントです。

2. 基本的な使い方

2. 基本的な使い方

まずは、application.ymlに以下のような設定を書きます。

app:
  name: MySpringApp
  version: 1.0.0
  admin:
    email: admin@example.com
    enabled: true

次に、対応するJavaクラスを作成します。

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {

    private String name;
    private String version;
    private Admin admin;

    public static class Admin {
        private String email;
        private boolean enabled;

        // getter/setter
    }

    // getter/setter
}

このように、prefixを使ってプロパティ名を指定し、対応するフィールドに自動で値がバインドされます。

3. @EnableConfigurationPropertiesの必要性

3. @EnableConfigurationPropertiesの必要性

Spring Boot 2.2以降では、@Componentを付ければ@ConfigurationPropertiesは自動で登録されますが、明示的に使用する場合は@EnableConfigurationPropertiesを使います。

たとえば、設定専用クラスとして登録したいときは次のようにします。

@Configuration
@EnableConfigurationProperties(AppProperties.class)
public class AppConfig {
}

このようにすれば、Beanとして自動的に読み込まれ、他のクラスでも@Autowiredで利用できます。

4. @Valueとの違い

4. @Valueとの違い

@Valueと@ConfigurationPropertiesはどちらも設定値を読み込む方法ですが、以下のような違いがあります。

• @Value：単一の値を簡単に読み込むのに適している
• @ConfigurationProperties：複数のプロパティをまとめて管理したいときに便利

大規模な設定やネストしたプロパティ構造では、@ConfigurationPropertiesの方が圧倒的に使いやすいです。

5. バリデーションの追加

5. バリデーションの追加

@ConfigurationPropertiesでは、設定値の妥当性をチェックするためにバリデーションも行えます。

バリデーションを行うには、以下の手順を踏みます。

@Component
@ConfigurationProperties(prefix = "app")
@Validated
public class AppProperties {

    @NotBlank
    private String name;

    @Pattern(regexp = "\\d+\\.\\d+\\.\\d+")
    private String version;

    @Valid
    private Admin admin;

    public static class Admin {
        @Email
        private String email;

        private boolean enabled;

        // getter/setter
    }

    // getter/setter
}

このように、javax.validationのアノテーションを使えば、プロパティ値の形式チェックができます。

6. プロパティのリストやMapも扱える

6. プロパティのリストやMapも扱える

@ConfigurationPropertiesでは、ListやMapなどのコレクション型の設定も扱えます。

例：

app:
  servers:
    - dev.example.com
    - test.example.com

private List<String> servers;

また、Map型を使えば、キーと値の組み合わせで設定を扱うこともできます。

7. アプリケーションからプロパティを使う方法

7. アプリケーションからプロパティを使う方法

バインドされたプロパティは、通常のBeanと同じように@Autowiredして利用できます。

@RestController
public class InfoController {

    private final AppProperties appProperties;

    public InfoController(AppProperties appProperties) {
        this.appProperties = appProperties;
    }

    @GetMapping("/info")
    public String info() {
        return appProperties.getName() + " - " + appProperties.getVersion();
    }
}

このようにすれば、設定ファイルの内容を簡単にアプリケーション内で使うことができます。

8. 設定ファイルの変更と反映について

8. 設定ファイルの変更と反映について

プロパティファイルの値を変更しても、通常のSpring Bootアプリケーションでは再起動しない限り反映されません。

ただし、Spring Cloud Configなどを導入すれば、設定の動的リロードも可能になります。

初心者のうちは、まずはアプリ再起動で反映される基本的な仕組みを理解しましょう。

9. ConfigurationPropertiesでよく使うアノテーション一覧

9. ConfigurationPropertiesでよく使うアノテーション一覧

設定のバリデーションや構造化のために、次のアノテーションをよく使います。

• @NotBlank：空白禁止
• @Email：メール形式
• @Pattern：正規表現マッチ
• @Min / @Max：数値範囲の指定
• @Valid：ネストしたオブジェクトの検証
• @Validated：クラス全体にバリデーションを有効化

これらを使いこなすことで、設定ファイルのエラーを防ぎ、より堅牢なアプリケーションを作ることができます。