@ConfigurationPropertiesの使い方を徹底解説！Springで設定値をまとめて読み込む方法

クラス単位で設定値をまとめて読み込む（@ConfigurationProperties）

新人と先輩の会話形式で理解しよう

新人

「先輩、Springでプロパティファイルから設定値を読み込むとき、毎回@Valueを使ってるんですけど……数が多いとちょっと面倒ですね。」

先輩

「確かにね。複数のプロパティをまとめて管理したいときは、@ConfigurationPropertiesを使うと便利だよ。」

新人

「それってどうやって使うんですか？@Valueより簡単ですか？」

先輩

「うん、特に設定項目が多いときに役立つよ。まずは@Valueの課題から整理してみようか。」

1. プロパティ設定の基本と@Valueの課題

Spring 設定読み込みの方法として、よく使われるのが@Valueアノテーションです。これは単一のプロパティを読み込むには便利ですが、設定項目が多くなるとコードが煩雑になります。

例えば、次のように1つずつ設定値を注入しなければなりません。


@Component
public class AppConfig {

    @Value("${app.name}")
    private String name;

    @Value("${app.version}")
    private String version;

    @Value("${app.author}")
    private String author;
}

このようにプロパティが増えるたびに@Valueを追加する必要があり、管理が大変です。また、キーのタイプミスがあってもIDEの補完が効かないため、実行時まで気づかないこともあります。

さらに、同じプレフィックスの設定をまとめて扱いたい場合、個別の@Valueでは非効率で、メンテナンス性も悪くなります。

2. @ConfigurationPropertiesとは何か

そんなときに便利なのが、@ConfigurationPropertiesとは、プロパティファイルの設定値をクラス単位でまとめて読み込める仕組みです。これにより、特定のプレフィックスを持つ設定を一括でバインドでき、管理が一気に楽になります。

たとえば、次のようなapplication.ymlを用意したとします。


app:
  name: SampleApp
  version: 1.0.0
  author: Tanaka

これらの値を、1つのJavaクラスにバインドするには以下のように記述します。


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

    private String name;
    private String version;
    private String author;

    // getterとsetterを忘れずに定義
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }

    public String getVersion() {
        return version;
    }
    public void setVersion(String version) {
        this.version = version;
    }

    public String getAuthor() {
        return author;
    }
    public void setAuthor(String author) {
        this.author = author;
    }
}

このようにしておけば、AppPropertiesクラスがapp.nameなどの設定値を自動的に受け取ってくれます。

@ConfigurationPropertiesの大きな利点は、以下の通りです。

設定値を1つのクラスでまとめて扱える
IDEによる補完や型チェックが効く
設定のグループ化が明確になる

これはSpring Bootが提供する非常に便利な機能で、初心者が設定値を適切に扱うためのベストプラクティスとも言えるでしょう。

特に、複数の設定を使う@Controllerや@Serviceなどのクラスでは、この方法が非常に役立ちます。設定の修正・確認・テストが一気に楽になります。

次回は、application.ymlの構造と、@ConfigurationPropertiesの具体的な使い方を詳しく見ていきます。

3. application.ymlの構造と設定例

Spring application.yml 読み込みを正しく行うには、まずapplication.ymlの構造を理解することが重要です。Spring Bootでは、プロパティファイルに定義したキーと値を、Javaクラスへマッピングできます。

たとえば、アプリケーションに関する情報を定義したい場合、以下のようにapplication.ymlを構成します。


app:
  name: SampleApp
  version: 1.0.0
  author: Tanaka
  description: サンプルアプリケーションです

この例では、すべてappというプレフィックスにまとめられており、設定の整理が非常にしやすくなっています。プレフィックスを使ってグルーピングすることで、設定クラス作成方法とあわせてコードの見通しもよくなります。

複数のプロパティを1つの塊として扱う場合は、このような構造が非常に便利です。特に本番環境やテスト環境ごとに異なる設定を用意する場合も、構造が一貫しているとメンテナンスが容易になります。

4. プロパティクラスの定義方法（@ConfigurationPropertiesの使い方）

@ConfigurationPropertiesを活用して設定値をクラスにマッピングするには、プロパティクラスを作成します。このクラスには、プレフィックスに対応するフィールドと、それぞれのgetter・setterを定義します。

以下は、前述のapplication.ymlに対応するプロパティクラスの定義例です。


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

    private String name;
    private String version;
    private String author;
    private String description;

    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }

    public String getVersion() {
        return version;
    }
    public void setVersion(String version) {
        this.version = version;
    }

    public String getAuthor() {
        return author;
    }
    public void setAuthor(String author) {
        this.author = author;
    }

    public String getDescription() {
        return description;
    }
    public void setDescription(String description) {
        this.description = description;
    }
}

このように定義することで、Spring Bootは自動的にapp.nameやapp.versionといった設定値をJavaクラスにバインドします。

また、型が一致していれば、List型やMap型といった複雑な構造も受け取れます。以下はその一例です。


app:
  servers:
    - host: localhost
      port: 8080
    - host: testserver
      port: 9090


public static class Server {
    private String host;
    private int port;
    // getter/setter省略
}

private List<Server> servers;

このように、Springでは複数の設定項目をクラス構造で整理しながら取り扱えるため、コードがとても読みやすくなります。

5. コンポーネントとして有効化する方法（@Componentや@EnableConfigurationProperties）

@ConfigurationPropertiesを使った設定クラスを有効にするには、いくつかの方法があります。もっとも基本的なのは、先ほどの例のように@Componentを付けることです。これにより、Springが自動的にBeanとして登録し、DI対象として使用できます。


@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
  // フィールドとgetter/setter
}

ただし、@Componentを使わずに、明示的に@EnableConfigurationPropertiesで読み込む方法もあります。これは主に設定クラスを明確に管理したい場合や、外部ライブラリなどに適用するときに使います。

たとえば、設定用のクラスを複数登録する場合は、次のようにします。


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

@EnableConfigurationPropertiesは@Configurationと併用することが多く、明示的な構成管理が可能になります。

いずれの方法でも、設定クラスはSpringのDIコンテナで管理され、@Autowiredなどで注入して利用することができます。


@Controller
public class HomeController {

    private final AppProperties appProperties;

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

    @GetMapping("/")
    public String index(Model model) {
        model.addAttribute("appName", appProperties.getName());
        return "index";
    }
}

このように、@Controllerクラスからも設定値を簡単に利用できるため、開発効率が大きく向上します。

Spring 設定読み込みと@ConfigurationPropertiesを組み合わせることで、プロジェクト全体の構成がスッキリと整理され、保守性の高いアプリケーションを構築できます。

次回は、よくあるエラーやプロファイルとの組み合わせ方など、さらに実践的な活用方法を解説します。

6. よくあるエラーとその対処法（プロパティ名の不一致・バインド失敗）

@ConfigurationProperties エラー対処法で検索される代表的なトラブルとして、「プロパティ名がマッチしない」「バインドできない」「Bean登録されない」などが挙げられます。初心者がつまずきやすいので、順に確認していきましょう。

① プロパティ名の不一致

YAML側のキーとJavaクラスのフィールド名が一致していないと、正しくバインドされません。特にキャメルケースとハイフンの違いに注意が必要です。

YAMLではapp-nameのように書かれていても、JavaではappNameというプロパティ名で定義する必要があります。

② getter・setterの定義漏れ

@ConfigurationPropertiesでは、各プロパティに対応するgetterとsetterがないと、バインドに失敗します。フィールドを定義しただけでは読み込まれません。

③ @Componentの付け忘れ

プロパティクラスに@Componentを付けていないと、SpringがBeanとして認識せず、DIもバインドも機能しません。

④ spring-boot-configuration-processorの未導入

補完機能や型チェックを有効にするには、build.gradleに以下の依存関係が必要です。


dependencies {
    annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'
}

これがないと、IDEによる補完が効かず、手動での確認作業が増えてしまいます。

⑤ デバッグ方法

プロパティが正しくバインドされているかを確認したい場合は、@PostConstructを使って初期化時にログを出力してみましょう。


@PostConstruct
public void init() {
    System.out.println("App Name = " + name);
}

バインドに失敗している場合は、ログにnullが表示されたり、Caused by: java.lang.IllegalStateExceptionのような例外が出ることがあります。

7. 複数プロファイルとの連携（application-dev.ymlなどとの組み合わせ）

application.ymlには環境ごとの設定を分けるためにプロファイル設定読み込みという仕組みがあります。開発・本番・テストなど環境ごとにファイルを切り分けて、設定を上書きできます。

たとえば、次のようにapplication.ymlでプロファイルを定義します。


spring:
  profiles:
    active: dev

その上で、application-dev.ymlファイルに開発用の設定を記述します。


app:
  name: DevApp
  version: 1.0.0-dev
  author: DevUser

本番環境用にはapplication-prod.ymlを用意し、ビルド時にspring.profiles.activeを切り替えれば、設定を環境に応じて自動で切り替えることが可能です。

注意点

各プロファイルファイルは、基本のapplication.ymlを上書きする形式で構成する
共通設定はapplication.ymlに、差分はapplication-{profile}.ymlに記載する
application.ymlでspring.profiles.activeが定義されていないと、デフォルトしか読み込まれない

また、GradleやIDEでプロファイルを切り替えたい場合は、VMオプションに以下のように指定します。


-Dspring.profiles.active=prod

これにより、ビルドや起動時にapplication-prod.ymlが優先的に読み込まれるようになります。

8. 実際のControllerやServiceクラスでの活用例

最後に、実際の@Controllerや@Serviceクラスで@ConfigurationPropertiesをどう使うかを見てみましょう。ここでは、すでに作成済みのAppPropertiesを活用します。

Controllerでの利用例


@Controller
public class InfoController {

    private final AppProperties appProperties;

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

    @GetMapping("/info")
    public String info(Model model) {
        model.addAttribute("appName", appProperties.getName());
        model.addAttribute("version", appProperties.getVersion());
        model.addAttribute("author", appProperties.getAuthor());
        return "info";
    }
}

このように@Controllerで設定値を直接モデルに渡すことで、画面表示に利用できます。

Serviceでの利用例


@Service
public class NotificationService {

    private final AppProperties appProperties;

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

    public void notifyAdmin() {
        String message = "アプリ名：" + appProperties.getName() + 
                         "（バージョン：" + appProperties.getVersion() + "）";
        System.out.println(message);
    }
}

設定値をロジック内で利用することで、環境ごとに異なる処理を実現できます。

このように、@ConfigurationPropertiesは単に設定値をまとめるだけでなく、@Controllerや@Serviceなどアプリ全体にわたって再利用しやすい構造を提供してくれます。

しかも、IDEによる補完やバリデーションも効くため、設定ファイル読み込みミス防止にも大きく貢献します。