プロファイル
プロファイルとは、アプリケーションが動く状況に付けた名前です。dev、test、prod、eu などです。プロファイルを有効にすると、追加の設定ファイルとドキュメントが読まれ、その状況のための Bean が生成されます。それ以外の構成は共有されたままです。
使う理由
環境の違いは、1 つや 2 つの値にとどまらないことがよくあります。別のデータベース、開発中の偽の決済サービス、地域ごとの別の URL などです。プロファイルは、こうした違いを起動時に選ぶ一つの名前のもとにまとめるため、コードが「本番環境か?」と尋ねることはありません。
例
# lib/resources/application.yml
shop:
payment: fake
url: http://localhost:8080
spring:
profiles:
group:
prod: [eu, monitoring] # prod は eu と monitoring も有効にする
# lib/resources/application-prod.yml
shop:
payment: stripe
url: https://neon.books
# lib/resources/application-eu.yml
shop:
currency: EUR
dart run bin/main.dart --spring.profiles.active=prod
SPRING_PROFILES_ACTIVE=prod dart run bin/main.dart
flutter run --dart-define=SPRING_PROFILES_ACTIVE=prod
起動時に The following 3 profiles are active: "prod", "eu", "monitoring" がログに出され、shop.payment は stripe になります。
// prod プロファイルのときだけ存在する Bean。
@Service()
@Profile(['prod'])
class StripePayments implements Payments { ... }
プロファイルを有効にする
| キー | 型 | 意味 |
|---|---|---|
spring.profiles.active |
カンマ区切りのリストまたは YAML のリスト | 有効なプロファイル。キーを持つ最初のソースが優先されるため、コマンドラインはファイルに勝つ |
spring.profiles.include |
カンマ区切りのリストまたは YAML のリスト | 有効なプロファイルに追加されるプロファイル。すべてのソースから |
spring.profiles.default |
カンマ区切りのリスト | 有効なプロファイルがない間に使われるプロファイル。設定されていなければ default |
spring.profiles.group.<name> |
リスト | <name> を有効にすると、これらも有効になる。グループはグループを含められる。<name> は完全一致で照合される (group.Prod は prod のグループではない) |
spring.profiles.validate |
bool、デフォルト true |
名前をチェックする: 英字、数字、-_.+@。英字か数字で始まり、終わる |
コードでは:
SpringApplication(additionalProfiles: ['mobile'])は、毎回の実行で、設定されたものより前にプロファイルを有効にします (そのため、それらのファイルはプロファイルのファイルの中で最も優先度が低くなります)。run(args, additionalProfiles: [...])は、一回の起動にプロファイルを追加します。springBootTest(profiles: ['test'])は、テストでspring.profiles.activeを置き換えます。
有効化の順序: まず additionalProfiles、次にコードで設定したプロファイル、次に spring.profiles.active、次に include。それぞれの後にそのグループが続きます。複数のプロファイルが有効な場合、最後のもののファイルが優先されます。
プロファイルのファイル
有効なプロファイルごとに、application-{profile}.yml (または .yaml、.properties) がすべてのロケーションで通常のファイルの後に読まれるため、その値が優先されます。有効なプロファイルがない間は、default プロファイル (または spring.profiles.default のもの) がファイルを選びます。そのときは application-default.yml が読まれます。
インポートされたファイルにもプロファイル版があります。application.yml が local.yml をインポートすると、dev では local-dev.yml が読まれ、application-dev.yml より優先されます。インポート を参照してください。
一部のプロファイルやプラットフォーム用のドキュメント
別のファイルの代わりに、ファイル内のドキュメントを限定できます。
| キー | 意味 |
|---|---|
spring.config.activate.on-profile |
このプロファイル式が一致するとドキュメントが適用される。カンマ区切りのリストは「いずれか」を意味する。空の値は条件なし |
spring.config.activate.on-cloud-platform |
このプラットフォームでドキュメントが適用される: kubernetes、heroku、cloud-foundry、azure-app-service、amazon-ecs、nomad、sap、または none (プラットフォームなし) |
shop:
region: local
---
spring:
config:
activate:
on-profile: "prod & !us"
shop:
region: eu
---
spring:
config:
activate:
on-cloud-platform: kubernetes
shop:
region: cluster
shop.region=local
#---
spring.config.activate.on-profile=prod & !us
shop.region=eu
#---
spring.config.activate.on-cloud-platform=kubernetes
shop.region=cluster
2.4 より前のキー spring.profiles (ドキュメントの条件として) は拒否されます。spring.config.activate.on-profile と書いてください。
プロファイル式
| 式 | 一致する条件 |
|---|---|
prod |
prod が有効 |
!prod |
prod が有効でない |
prod & eu |
両方が有効 |
prod | staging |
どちらかが有効 |
prod & (eu | us) |
括弧でまとめる。括弧なしで & と | を混ぜることはできない |
prod, staging |
カンマ区切りのリスト: いずれか |
同じ式は @Profile でも使えます。不正な式 ((dev、a &、a b) は Malformed profile expression で起動を失敗させます。Spring はその一部を受け入れます。
クラウドプラットフォーム
プラットフォームは、Spring Boot と同じく、環境変数から検出されます。
| プラットフォーム | 検出される条件 (設定されている変数) |
|---|---|
kubernetes |
KUBERNETES_SERVICE_HOST と KUBERNETES_SERVICE_PORT |
heroku |
DYNO |
cloud-foundry |
VCAP_APPLICATION または VCAP_SERVICES |
azure-app-service |
WEBSITE_SITE_NAME、WEBSITE_INSTANCE_ID、WEBSITE_RESOURCE_GROUP、WEBSITE_SKU |
amazon-ecs |
ECS_CONTAINER_METADATA_URI または ECS_CONTAINER_METADATA_URI_V4 |
nomad |
NOMAD_ALLOC_ID |
sap |
HC_LANDSCAPE |
spring.main.cloud-platform はプラットフォームを強制するか、none で検出を無効にします。Bean は @ConditionalOnCloudPlatform を使います (条件 を参照)。リストの形式 (on-cloud-platform[0]) は、Spring Boot と同じく無視されます。
プロファイルを安定させるルール
Spring Boot と同じく、プロファイルはプロファイルのファイルが読まれる前に決まるため、それらのファイルがプロファイルを変えることはできません。
- プロファイルのファイル (
application-dev.yml、またはインポートされたlocal.ymlに対するlocal-dev.yml) はspring.profiles.active、.default、.includeを設定できません。設定するとInvalidConfigDataPropertyExceptionで起動が失敗します。そのspring.profiles.group.*は無視されます。 - プロファイルが決まる前に読まれるファイル (
application.ymlとそれがインポートするもの) の中の、プロファイルに限定されたドキュメントは、4 つのキーのどれも設定できません。そのドキュメントが適用されると起動が失敗します。 - プロファイルが決まった後に読まれるファイル (プロファイルのファイルや
on-profileのドキュメントがインポートしたもの) では、4 つのキーは無視されます。
これらのキーは、緩い名前が許すどの綴りでも検出されます。プロファイルのファイルの spring.profiles.Active も失敗します。
Flutter アプリのプロファイル
spring_boot_starter_flutter では、プラットフォームもプロファイルになります: android、ios、web、macos、windows、linux と、mobile (Android、iOS) または desktop (macOS、Windows、Linux)。ビルドモードも、プラットフォームの後にプロファイルになります: release、profile、debug。そのため application-ios.yml や application-release.yml は、何も設定せずに読まれます。
# lib/resources/application-release.yml: リリースでは警告だけをログに出す
logging:
level:
root: warn
Spring (Java) との対応
キー、ファイル、式は Spring Boot 2.4 以降と同じです。違い:
- プロファイルに限定されたドキュメントの
spring.profiles.active、.default、.group.*は、そのドキュメントが適用されると起動を失敗させ、適用されなければ無視されます (Spring Boot 4.1 はそれらを読みます)。 on-profileのプレースホルダーは、最初のパスではなく、プロファイルが決まった時点で解決されます。- 抜けのあるリストとして書かれたプロファイルグループは、失敗する代わりに抜けのところまで読まれます。
- プロファイル式はより厳密です。