Spring プロファイルの使い方を解説！application.ymlで環境ごとの設定を自動切り替え

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

新人

「先輩、Spring Bootのプロジェクトって、環境によって設定変えたりしますか？」

先輩

「もちろんだよ。Springにはプロファイルという機能があって、開発・テスト・本番などの環境ごとに設定を切り替えられるんだ。」

新人

「どうやって切り替えるんですか？毎回書き直すとか……？」

先輩

「そんな面倒なことはしないよ。application.ymlでプロファイルを定義しておけば、自動で環境に合った設定に切り替わる仕組みがあるんだ。順番に説明するね。」

1. Springのプロファイルとは

Spring プロファイルは、Spring Frameworkで環境ごとにBeanの定義や設定を切り替えるための仕組みです。たとえば、開発用の設定と本番用の設定を分けたい場合に使われます。

通常は、application.ymlでプロファイル名を定義し、環境に応じて切り替えられるようにしておきます。

設定ファイルの一例は以下の通りです。


spring:
  profiles:
    active: dev

この設定では、Spring Bootがapplication-dev.ymlを自動的に読み込みます。

2. なぜプロファイルの切り替えが必要なのか

プロジェクトを開発していると、環境ごとに異なる設定を使いたくなる場面が多々あります。たとえば、次のようなケースです。

開発環境：ローカルのデータベースやダミーAPIを使う
テスト環境：検証用の専用DBを使う
本番環境：商用の安定したDBや外部連携サービスと接続

これらをすべて1つの設定ファイルに詰め込んでしまうと、間違って本番用設定でローカルテストしてしまうといったミスの原因になります。

Spring プロファイルを活用すれば、各環境に適した設定をapplication-dev.ymlやapplication-prod.ymlに分けて定義できます。

また、Gradleプロジェクトでは、以下のようにコマンドでプロファイルを切り替えることも可能です。


./gradlew bootRun --args='--spring.profiles.active=prod'

このようにすれば、ビルドや実行時に使用する設定を柔軟に選べるため、開発・テスト・本番の環境ごとのミスを防ぐことができます。

3. application.ymlでプロファイルごとの設定を書く方法

Spring プロファイル切り替えを行う方法として、ひとつのapplication.ymlファイル内に複数のプロファイルごとの設定を記述することも可能です。この方法では---（ハイフン3つ）で区切りながら、プロファイルごとに設定を定義していきます。

この書き方はファイルを分割せずに済むため、すべてのプロファイル設定を1ファイルに集約したい場合に便利です。


spring:
  profiles:
    active: dev

---

spring:
  config:
    activate:
      on-profile: dev
  datasource:
    url: jdbc:mysql://localhost:3306/devdb
    username: devuser
    password: devpass
    driver-class-name: com.mysql.cj.jdbc.Driver

---

spring:
  config:
    activate:
      on-profile: prod
  datasource:
    url: jdbc:mysql://prod-db:3306/proddb
    username: produser
    password: prodpass
    driver-class-name: com.mysql.cj.jdbc.Driver

このようにapplication.yml 使用例としてプロファイルごとの設定を記述しておくことで、実行時に指定したプロファイルに応じて、自動でその設定が有効になります。

注意点として、上部でspring.profiles.activeをdevに指定すれば、on-profile: devのブロックが有効になり、開発環境用の設定が読み込まれる仕組みです。

4. 複数のプロファイルを定義し、適用する方法（application-dev.ymlなどの使用方法）

設定ファイルを分割する場合は、application.ymlとプロファイルごとのYAMLファイルを併用します。たとえばapplication-dev.yml、application-test.yml、application-prod.ymlのように用意しておくことで、それぞれの環境での設定を管理しやすくなります。

まずは共通設定としてのapplication.ymlに、現在有効にするプロファイルを記述します。


spring:
  profiles:
    active: dev

そして、環境別の設定ファイルをsrc/main/resourcesに配置します。以下は開発用のapplication-dev.ymlの例です。


spring:
  datasource:
    url: jdbc:mysql://localhost:3306/devdb
    username: devuser
    password: devpass
    driver-class-name: com.mysql.cj.jdbc.Driver

server:
  port: 8081

本番用にはapplication-prod.ymlを次のように定義できます。


spring:
  datasource:
    url: jdbc:mysql://prod-db:3306/proddb
    username: produser
    password: prodpass
    driver-class-name: com.mysql.cj.jdbc.Driver

server:
  port: 80

application.yml 使用例としてこのようにファイルを分けて記述すれば、コードの可読性が高まり、メンテナンスもしやすくなります。プロファイルの指定を変更するだけで、読み込まれる設定が切り替わるため、環境に応じた動作確認が簡単になります。

5. @Profileアノテーションを使ったコンポーネントの切り替え方法

Spring プロファイル切り替えは設定ファイルだけでなく、Javaコードにも反映できます。特定のプロファイルでのみ読み込まれるBeanや@Controllerを作成したいときは、@Profileアノテーションを活用します。

以下は、開発環境でのみ動作するDevMessageServiceの例です。


@Service
@Profile("dev")
public class DevMessageService implements MessageService {

    @Override
    public String getMessage() {
        return "開発モード用メッセージです";
    }
}

本番環境専用のサービスも同様に作成できます。


@Service
@Profile("prod")
public class ProdMessageService implements MessageService {

    @Override
    public String getMessage() {
        return "本番モード用メッセージです";
    }
}

上記のクラスは共通のインターフェースMessageServiceを実装しています。プロファイルに応じて適切な実装が選ばれ、自動的にDI（依存性注入）されます。


public interface MessageService {
    String getMessage();
}

この仕組みにより、環境ごとに異なるロジックを用意しても、他のクラスの記述を変更することなく、プロファイルで自動的に制御できます。

たとえば、@Controllerクラスでも@Profileを使うことができます。以下は開発環境だけで使用されるコントローラの例です。


@Controller
@Profile("dev")
public class DevOnlyController {

    @GetMapping("/dev-info")
    public String devInfo() {
        return "この画面は開発モードでのみ表示されます";
    }
}

このようにすれば、環境ごとのロジックや画面の切り替えを柔軟に制御できます。特に、本番環境では表示したくない管理画面や開発用ツールなどを安全に管理する手段として有効です。

プロファイルを使った構成は、テストコードの切り替えやロギング設定の制御など、さまざまな場面で役立ちます。初心者のうちからSpring プロファイルを意識して設計できると、実務でもトラブルを未然に防げるようになります。

6. 実行時にアクティブなプロファイルを切り替える方法（application.ymlでのspring.profiles.active指定）

Spring プロファイル設定方法の基本として、application.yml内のspring.profiles.activeを直接書き換えることで、実行時に有効なプロファイルを切り替えることができます。

たとえば、開発環境と本番環境を切り替えたい場合は、次のように設定ファイルを書き換えます。


spring:
  profiles:
    active: prod

このように記述すると、application-prod.ymlが読み込まれ、@Profile("prod")が付いたBeanが有効になります。

ただし、ここでの注意点として、毎回application.ymlを手動で変更するのは手間です。また、複数人で開発しているプロジェクトでは、意図せずに他人のプロファイル設定が反映されてしまうミスも起きがちです。

そのため、実際の現場では、次に説明するように「起動時の引数で指定」する方法がよく使われます。

7. 起動オプション（VM引数やGradleの引数）でプロファイルを切り替える方法

Spring プロファイル切り替えで最も柔軟な方法が、起動時にプロファイルを指定するやり方です。application.ymlを変更することなく、動的にプロファイルを選べるため、開発・テスト・本番の切り替えがとても簡単になります。

たとえば、Pleiades＋Gradleの環境では、次のようにコマンドを実行します。


./gradlew bootRun --args='--spring.profiles.active=dev'

このコマンドで実行すれば、application-dev.ymlが読み込まれます。同様に、テスト環境や本番環境も切り替え可能です。


./gradlew bootRun --args='--spring.profiles.active=prod'

また、Eclipse（Pleiades）でGUIから起動設定を変更することも可能です。

パッケージエクスプローラーでプロジェクトを右クリック
[実行] → [実行構成] を選択
引数タブで --spring.profiles.active=test を指定

この方法で実行すれば、プロファイル切り替えのミスを減らし、毎回設定ファイルを変更する必要もなくなります。

8. よくある失敗例と対処法（プロファイル名の誤記、適用優先度など）

最後に、Spring プロファイル設定方法を学ぶうえで初心者がよくつまずくポイントを解説します。

① プロファイル名の誤記

もっとも多いのが、プロファイル名のスペルミスです。たとえば、devではなくdeevと書いてしまうと、Springは該当するプロファイルがないと判断し、設定が正しく反映されません。

実行時には以下のようなメッセージが出ることがあります。


No active profile set, falling back to default profiles: default

この場合、指定したプロファイルが存在しないため、Springはdefaultプロファイルで起動しています。スペルミスがないかをまず確認しましょう。

② プロファイル優先度の誤解

複数の方法でプロファイルを指定している場合、どれが有効になるかが分かりづらいことがあります。優先順位は以下の通りです。

コマンドライン引数（最優先）
環境変数
application.yml

つまり、application.ymlにdevを指定していても、コマンドラインでprodを指定すれば、prodが優先されます。

③ ファイルの配置場所ミス

application-dev.ymlなどの設定ファイルを、src/main/resources以外に置いてしまうと読み込まれません。

初心者のうちは、設定ファイルを誤ってsrc直下やmainフォルダに配置してしまうことがあるので注意が必要です。

④ @Profileアノテーションの指定ミス

BeanやControllerに@Profile("dev")と書いても、プロファイルが一致していないと読み込まれません。

そのため、実行時のプロファイル設定と、アノテーションの中身が一致しているかをしっかり確認しましょう。

このような切り替えエラー対処の知識を持っておくことで、Springプロジェクトをより安全・確実に運用できるようになります。