Spring Bootアプリケーションを開発していると、データベース接続情報やサーバーポート、ログレベルなど、さまざまな設定を管理する必要があります。これらの設定を管理するのがapplication.propertiesやapplication.ymlといった設定ファイルです。

しかし、初学者にとっては「どちらのファイル形式を使えばいいのか」「環境変数はどうやって読み込むのか」「@Valueと@ConfigurationPropertiesはどう使い分けるのか」といった疑問が尽きません。

この記事では、設定ファイルの基本から実務での使い分けまで、実践的に解説していきます。

設定ファイルの基本 - propertiesとyml

Spring Bootの設定ファイルは、データベース接続情報やサーバーポートなどを外部化して管理します。src/main/resourcesディレクトリに配置すれば自動的に読み込まれます。

主な形式はapplication.properties(キー=値形式)とapplication.yml(YAML形式)の2つです。

# application.properties
server.port=8080
spring.datasource.url=jdbc:mysql://localhost:3306/mydb
# application.yml
server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb

シンプルな設定ならproperties、階層が深い設定ならymlが読みやすいですが、既存プロジェクトの形式に合わせるのが最重要です。両方ある場合はpropertiesが優先されます。

@Valueで単一の設定値を読み込む

設定ファイルの値をJavaコードで使うには、@Valueアノテーションが最もシンプルです。

# application.properties
app.name=MySpringBootApp
app.timeout=30
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class AppConfig {
    @Value("${app.name}")
    private String appName;

    @Value("${app.timeout:30}")  // 未定義なら30を使用
    private int timeout;
}

@Valueは単一の設定値を読み込むには便利ですが、関連する設定が多い場合は次の@ConfigurationPropertiesの方が適しています。

@ConfigurationPropertiesで関連する設定をまとめる

関連するプロパティが複数ある場合は、@ConfigurationPropertiesでグループ化すると型安全で管理しやすくなります。

# application.yml
app:
  database:
    host: localhost
    port: 3306
@ConfigurationProperties(prefix = "app.database")
public record DatabaseProperties(String host, int port) {}

メインクラスで有効化して使います。

@SpringBootApplication
@EnableConfigurationProperties(DatabaseProperties.class)
public class MyApplication { ... }

@Service
public class DatabaseService {
    private final DatabaseProperties props;
    // コンストラクタで注入して使える
}

単一の設定値なら@Valueで十分ですが、関連する設定のグループなら@ConfigurationPropertiesが適切です。

環境変数で本番環境の設定を上書きする

パスワードなどの機密情報は環境変数で管理します。プロパティ名のドット・ハイフンをアンダースコアに、小文字を大文字に変換すれば自動的に読み込まれます。

例えばspring.datasource.passwordは環境変数SPRING_DATASOURCE_PASSWORDで上書きできます。

spring:
  datasource:
    password: ${DB_PASSWORD:defaultpassword}
export DB_PASSWORD=super-secure-password
java -jar myapp.jar

プレースホルダで設定値を再利用する

プレースホルダ${}で他のプロパティ値を参照できます。

app.base-url=https://api.example.com
app.endpoint.users=${app.base-url}/users

# 環境変数が未定義ならデフォルト値を使用
server.port=${SERVER_PORT:8080}

プロパティの優先順位を理解する

複数のソースから設定を読み込む場合、優先順位は以下の通りです(上にあるほど優先)。

  1. コマンドライン引数
  2. OS環境変数
  3. application-{profile}.properties/yml
  4. application.properties/yml

環境ごとに設定を切り替えるには、Profilesを使います。

java -jar myapp.jar --spring.profiles.active=prod

Profilesの詳細は「Spring BootのProfileを使って環境によって違う設定を安全に切り替える方法」をご覧ください。

よくあるハマりどころ

設定ファイルで遭遇しやすいエラーをいくつか紹介します。

プロパティが読み込めない

@Valueで${key}がそのまま表示される場合、キー名のタイポか、クラスに@Componentが付いていない可能性があります。設定ファイルがsrc/main/resourcesにあるかも確認しましょう。

YAMLのインデントエラー

YAMLはタブ文字が使えません。インデントは2スペースで統一しましょう。IDEのYAMLサポートを使えばエラーを事前に検出できます。

環境変数が反映されない

環境変数名はspring.datasource.passwordではなくSPRING_DATASOURCE_PASSWORDのように、ドット・ハイフンをアンダースコアに、小文字を大文字に変換する必要があります。

まとめ

Spring Bootの設定管理は、propertiesやymlファイルに設定を外部化し、@Valueや@ConfigurationPropertiesで読み込むというシンプルな仕組みです。

本番環境ではパスワードなどの機密情報を環境変数で上書きし、Profilesを使って環境ごとの設定を切り替えます。プロパティの優先順位を理解しておけば、意図しない設定の上書きを防げます。

実務では以下を意識しましょう。

  • 機密情報は設定ファイルに書かず環境変数で管理
  • 関連する設定は@ConfigurationPropertiesでグルーピング
  • チーム内で設定ファイル形式を統一

設定管理の基本を押さえておくと、環境の違いに柔軟に対応できるアプリケーションを作れるようになります。