はじめに
Spring Boot の設定を扱っていると、
@ConfigurationProperties というアノテーションを目にすることがあります。
「yml の値をどうやって Java に渡すの？」
「@Value との違いは？」
「設定が増えてくると管理がつらい…」
そんな悩みを解決してくれるのが
@ConfigurationProperties です。
この記事では、この仕組みを
やさしく・実務で役立つ形 で整理していきます。
まずはコードを見て、そこから少しずつ理解していきましょう。
まずはコードを確認
application.yml
app:
title: My Application
version: 1.0設定クラス
@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
private String title;
private String version;
// getter / setter
}このように、
yml の値を Java のクラスにまとめてバインドできる
のが @ConfigurationProperties の特徴です。
コードのしくみを解説
@ConfigurationProperties とは
一言でいうと、
「設定ファイルの値を、Java のクラスにまとめて読み込む仕組み」
です。
- yml / properties の値を
- prefix（接頭辞）でまとめて
- 自動でフィールドにセットしてくれる
という便利な機能です。
なぜ必要なのか
理由は大きく 3 つあります。
設定が増えても管理しやすい
@Value を使うと、設定が増えるほどコードが散らばります。
@Value("${app.title}")
private String title;これが 10 個、20 個になると大変です。
@ConfigurationProperties なら
設定を 1 つのクラスにまとめて管理 できます。
型安全に扱える
数値・真偽値・リストなど、型に合わせて自動変換してくれます。
テストがしやすい
設定クラスをモック化したり、
テスト用の設定を注入したりしやすくなります。
よく使う書き方をやさしく整理
prefix を使ってまとめる
@ConfigurationProperties(prefix = "app")List や Map も扱える
app:
servers:
- api.example.com
- api2.example.comprivate List<String> servers;ネストした設定も OK
app:
mail:
host: smtp.example.com
port: 587private Mail mail;
public static class Mail {
private String host;
private int port;
}あわせて知っておきたいポイント
@EnableConfigurationProperties が必要な場合
Spring Boot 2.2 以降は
@Component を付ければ自動で有効になります。
設定クラスを Bean として登録したくない場合は
@EnableConfigurationProperties を使います。
@Value との違い
| 項目 | @Value | @ConfigurationProperties |
|---|---|---|
| 用途 | 単発の値を読みたい | 設定をまとめて扱いたい |
| 型変換 | 基本的 | 豊富 |
| 管理性 | 散らばりやすい | 1 クラスにまとまる |
バリデーションもできる
@Validated
@ConfigurationProperties(prefix = "app")
public class AppProperties {
@NotBlank
private String title;
}設定ファイルの値に対してもチェックできます。
使うときに気をつけたいこと
フィールド名と yml のキーを揃える
app.title → title app.mail.host → mail.host
setter が必要
@ConfigurationProperties は setter を使って値を注入します。
Lombok の @Setter を使うと楽です。
prefix をわかりやすく
app, external.api, security.jwt など、
意味が伝わる名前にすると管理しやすくなります。
まとめ
@ConfigurationProperties は、
「設定ファイルの値を Java のクラスにまとめて読み込む仕組み」 です。
- 設定を 1 クラスにまとめられる
- 型安全に扱える
- List や Map も扱える
- バリデーションも可能
難しく聞こえますが、
「設定をきれいに整理するための仕組み」
と理解できれば十分です。
@ConfigurationProperties を使いこなすと、
設定が増えてもコードが散らばらず、
アプリ全体の見通しがぐっと良くなります。
あなたの開発が、今日より少しだけ楽になりますように。
設定をひとまとめに抱きしめてくれるなんて…やさしいね。
コメント