設定ファイル

アプリケーションは設定を lib/resources/ の application.yml、application.yaml、application.properties に置きます。このフォルダーは Spring がクラスパスと呼ぶもので、resources: プレフィックスはその中を指します。有効な プロファイル ごとに application-{profile}.* も読まれ、その値は通常のファイルより優先されます。

pubspec.yaml に宣言するものは何もありません。ジェネレーターは lib/resources/ のすべてのファイルを生成コードに埋め込むため、ファイルは Dart VM でも、AOT の実行ファイルでも、Flutter でも、Web でも同じように動きます。1 MB を超えるファイルは埋め込まれません (ビルドが警告します)。Flutter のアセットとして、またはプログラムの隣のファイルとして配布してください。

使う理由

アプリケーションごとに一つのファイルと、プロファイルごとに一つのファイルにすれば、デフォルトは一か所にまとまり、差分は小さく保てます。プログラムの隣のファイル (./application.yml、./config/) を使えば、運用担当者は新しいビルドなしでサーバーやデスクトップアプリの設定を変えられます。Spring Boot と同じく、それらはパッケージに含まれたものより優先されます。

例

lib/
  main.dart
  resources/
    application.yml               # 常に読まれる
    application-dev.yml           # dev プロファイルで読まれる
    application-prod.properties   # prod で読まれる (形式は混在できる)
    config/
      application.yml             # これもパッケージに含まれ、resources:/ より優先される

2 つの形式は同じことを表します。

# lib/resources/application.yml
spring:
  application:
    name: shop
shop:
  title: NEON Books
  url: http://localhost:8080
  max-basket-size: 20
# lib/resources/application.properties
spring.application.name=shop
shop.title=NEON Books
shop.url=http://localhost:8080
shop.max-basket-size=20

好きな方を使うか、両方を使ってください。一つのロケーションに両方がある場合、.properties が .yml より、.yml が .yaml より優先されます。

値の形

どちらの形式も、最終的には同じフラットなキーと値のリストになります。

形 YAML .properties
ネストしたキー shop: / payment: / provider: stripe shop.payment.provider=stripe
リスト hosts: / - eu.neon.books / - us.neon.books、または hosts: [eu, us] shop.hosts[0]=eu.neon.books、shop.hosts=eu,us、または shop.hosts[]=eu, us
オブジェクトのリスト servers: / - name: eu / url: https://eu.neon.books shop.servers[0].name=eu
マップ prices: / book: 12 / e-book: 8 shop.prices.book=12
ドットを含むマップのキー "[X-Shop.Id]": neon (引用符付き) shop.headers[X-Shop.Id]=neon
空の値 banner:、motto: ~、または null shop.banner=

一つのファイル内の複数のドキュメント

一つのファイルに複数のドキュメントを入れられます。YAML は --- で、.properties は #--- (または !---) の行で区切ります。後のドキュメントが前のドキュメントを上書きします。ドキュメントは一部のプロファイルやクラウドプラットフォームに限定できるため、一つのファイルに開発用の値と本番用の上書きを入れられます。

shop:
  url: http://localhost:8080
---
spring:
  config:
    activate:
      on-profile: prod
shop:
  url: https://neon.books
shop.url=http://localhost:8080
#---
spring.config.activate.on-profile=prod
shop.url=https://neon.books

.properties の区切りは行全体です。行頭の #--- または !--- で、ハイフンはちょうど 3 つ、その後には空白かタブしか置けません。同じプレフィックスのコメントの直後では区切りとみなされません (空行を入れるか、!--- を使ってください)。前の行が \ で続いている場合も同様です。コメントは区切りの直後ではなく、on-profile の行の下に置いてください。Spring Boot はそうしたドキュメントを前のドキュメントに結合しますが、このローダーは結合しません。

on-profile の式と on-cloud-platform については プロファイル を参照してください。

.properties だけのもの

# キーと値の区切りは =、:、または空白。
shop.name=NEON
shop.city: Berlin
shop.country Germany

# \ で終わる行は続く。次の行の先頭の空白は取り除かれる。
shop.welcome=Welcome to NEON Books, \
             the shop of books.

# エスケープ: \t \n \r \f \uXXXX。キーの中では \=、\:、"\ " がそれらの文字を保つ。
shop.key\=with\:colon=yes

# コメントは行頭の # または ! で始まる。途中の # は値の一部。
shop.color=#673AB7

YAML だけのもの

# アンカーはブロックを共有する。マッピング自身のキーは、マージされたキーより優先される。
defaults: &defaults
  timeout: 5s
  retries: 3
shop:
  eu:
    <<: *defaults
    url: https://eu.neon.books
  us:
    <<: *defaults
    retries: 5
  color: '#673AB7'   # 引用符付き: 空白の後の # はコメントを始める

YAML は YAML 1.2 として読まれます (Spring Boot の SnakeYAML は 1.1 で読みます)。

ファイルが検索される場所

ロケーションは 2 つのグループに分かれます。2 番目のグループは最初のグループを完全に上書きします。

グループ ロケーション (優先度の低い順) 内容
1、パッケージに含まれるもの resources:/、resources:/config/ lib/resources/ と lib/resources/config/。ジェネレーターが埋め込む
2、プログラムの隣 file:./、file:./config/、file:./config/*/ 作業ディレクトリ、./config/、そのサブディレクトリ (アルファベット順)

そのため、サーバーのバイナリの隣の ./application.properties は、パッケージに含まれた application-prod.properties より優先されます。グループの中では、後のロケーションが優先され、プロファイルのファイルが通常のファイルより優先され、最後に有効になったプロファイルが優先されます。デフォルトのロケーションはすべて任意です。

テスト (springBootTest) では、test/resources/ が lib/resources/ より前に来るため、test/resources/application-test.yml が見つかり、そこにあるファイルはパッケージ内の同じパスのファイルを置き換えます。

検索を変える

次のキーは、どのファイルを検索するかを変えます。これらは、ファイルが読まれる前から存在するソースからだけ読まれます: コマンドライン、--dart-define、環境変数、SPRING_APPLICATION_JSON、デフォルトプロパティ。設定ファイルでは設定できません。

キー 型 デフォルト 意味
spring.config.name カンマ区切りのリスト application ファイルのベース名。application,shop は application*.* と shop*.* を読む。後の名前が優先される
spring.config.location ロケーション 上記の 2 つのグループ デフォルトのロケーションを置き換える。, はグループを区切り、; はロケーションを一つのグループにまとめる
spring.config.additional-location ロケーション なし ロケーションの後に検索されるグループ。そのためそれらより優先される
spring.config.on-not-found fail / ignore fail ignore はすべてのロケーションを任意にする。それ以外の値は起動を失敗させる
# パッケージ内のファイルと、それより優先される /etc/shop/ だけ。
dart run bin/main.dart --spring.config.location=optional:resources:/,file:/etc/shop/

# 通常のロケーションに加えて、その上にもう一つのファイル。
dart run bin/main.dart --spring.config.additional-location=file:./override.yml

# application.yml の代わりに shop.yml を読む。
SPRING_CONFIG_NAME=shop dart run bin/main.dart

ここに書くロケーションには、インポート のすべての形式が使えます: optional:、/ で終わるディレクトリ、ワイルドカード、拡張子のヒント (file:./conf[.yml])、エンコーディングのヒント、configtree:。

ファイルがない場合

SpringApplication を使わずに

この作業を行うクラスは ConfigDataEnvironment です。spring_core_dart だけを使うプログラムやツールは、これを自分で実行します。

// lib/resources/application.yml、./application.properties、プロファイル、インポートを読む。
Future<void> main(List<String> args) async {
  final environment = StandardEnvironment()
    ..propertySources.addFirst(SimpleCommandLinePropertySource(args));
  await ConfigDataEnvironment(environment).processAndApply();
  print(environment.getProperty('shop.url'));
}

そのコンストラクターは、resourceLoader (アセットやメモリ上のファイル用)、loaders (形式。デフォルトは PropertiesPropertySourceLoader と YamlPropertySourceLoader。独自の PropertySourceLoader で形式を追加できます)、defaultLocations、additionalProfiles を受け取ります。processAndApplySync() は同期版です。

Spring (Java) との対応

ファイル名、ロケーション、ルールは Spring Boot と同じです。ただし:

関連項目