
# プロファイル

プロファイルとは、アプリケーションが動く状況に付けた名前です。`dev`、`test`、`prod`、`eu` などです。プロファイルを有効にすると、追加の設定ファイルとドキュメントが読まれ、その状況のための Bean が生成されます。それ以外の構成は共有されたままです。

## 使う理由

環境の違いは、1 つや 2 つの値にとどまらないことがよくあります。別のデータベース、開発中の偽の決済サービス、地域ごとの別の URL などです。プロファイルは、こうした違いを起動時に選ぶ一つの名前のもとにまとめるため、コードが「本番環境か?」と尋ねることはありません。

## 例

```yaml
# lib/resources/application.yml
shop:
  payment: fake
  url: http://localhost:8080
spring:
  profiles:
    group:
      prod: [eu, monitoring]   # prod は eu と monitoring も有効にする
```

```yaml
# lib/resources/application-prod.yml
shop:
  payment: stripe
  url: https://neon.books
```

```yaml
# lib/resources/application-eu.yml
shop:
  currency: EUR
```

```bash
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` になります。

```dart
// 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` より優先されます。[インポート](imports.md) を参照してください。

## 一部のプロファイルやプラットフォーム用のドキュメント

別のファイルの代わりに、ファイル内のドキュメントを限定できます。

| キー | 意味 |
|---|---|
| `spring.config.activate.on-profile` | このプロファイル式が一致するとドキュメントが適用される。カンマ区切りのリストは「いずれか」を意味する。空の値は条件なし |
| `spring.config.activate.on-cloud-platform` | このプラットフォームでドキュメントが適用される: `kubernetes`、`heroku`、`cloud-foundry`、`azure-app-service`、`amazon-ecs`、`nomad`、`sap`、または `none` (プラットフォームなし) |

```yaml
shop:
  region: local
---
spring:
  config:
    activate:
      on-profile: "prod & !us"
shop:
  region: eu
---
spring:
  config:
    activate:
      on-cloud-platform: kubernetes
shop:
  region: cluster
```

```properties
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` を使います ([条件](../conditions.md) を参照)。リストの形式 (`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` は、何も設定せずに読まれます。

```yaml
# 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` のプレースホルダーは、最初のパスではなく、プロファイルが決まった時点で解決されます。
- 抜けのあるリストとして書かれたプロファイルグループは、失敗する代わりに抜けのところまで読まれます。
- プロファイル式はより厳密です。

## 関連項目

- [spring_core_dart のプロファイル](../../spring-core-dart/config/profiles.md)
- [@Profile](../../spring-core-dart/beans/profile.md)
- [設定ファイル](config-files.md)
- [インポート](imports.md)
- [条件](../conditions.md)
