18 設定
ほとんどのアプリケーションは何らかの設定が必要です。これは、使用する正しい外部リソース（データベース、他のサービスなど）を指定したり、パフォーマンスを調整したり、特定の環境の要件に合わせて調整するために使用できます。Ratpack は、Ratpack アプリケーションで設定情報にアクセスするための簡単で柔軟なメカニズムを提供します。
設定データには、Jackson を使用したオブジェクトバインディングを介してアクセスします。Ratpack によって提供される構成オブジェクトは、すぐに使用できるように設計されています。設定データは、YAML ファイル、JSON ファイル、プロパティファイル、環境変数、システムプロパティなど、複数のソースからロードできます。
1.18 クイックスタート
始めるには
RatpackServer定義関数内で、ConfigDataインスタンスを作成します (例については、クラスのドキュメントを参照してください)。- 設定データからバインドされた設定オブジェクトを取得します。
2.18 設定ソース
ConfigDataBuilder は、最も一般的なソースからデータを簡単にロードするためのメソッドを提供します。
一般的に使用されるファイル形式は、yaml、json、および props メソッドを使用して使用できます。提供されるシグネチャは、ローカルファイル (String または Path)、ネットワーク経由 (URL)、クラスパス (URL を取得するには、Resources.getResource(String) を使用)、または ByteSource として扱える任意の場所からデータをロードするために使用できます。さらに、Map/Properties オブジェクトなどのファイル以外のソースからデータをロードすることもできます (特にデフォルト値に便利です。例 を参照してください)。システムプロパティと環境変数も同様です。また、object メソッドを使用して既存のオブジェクトから構成データをロードすることもできます。さらに柔軟性が必要な場合は、独自の ConfigSource 実装を提供できます。
1.2.18 フラット設定ソース
環境変数、Properties、および Map はフラットなデータ構造ですが、Ratpack で使用されるバインディングモデルは階層型です。このギャップを埋めるために、これらの構成ソースの実装では、フラットなキーと値のペアが便利なデータに変換されるように規約が適用されます。
1.1.2.18 環境変数
デフォルトの環境変数構成ソースでは、次の規則が使用されます。
- 指定されたプレフィックス (デフォルトでは
RATPACK_) に一致する環境変数のみが考慮されます。このプレフィックスは、それ以上の処理の前に削除されます。 - 環境変数名は、二重アンダースコアをオブジェクト境界として使用して、オブジェクトごとのセグメントに分割されます。
- セグメントは、単一アンダースコアを単語境界として使用して、キャメルケースのフィールド名に変換されます。
カスタム環境解析が必要な場合は、EnvironmentParser 実装を提供できます。
2.1.2.18 プロパティ/マップ
デフォルトの Properties/Map 設定ソースでは、次の規則が使用されます。
- システムプロパティからロードする場合、指定されたプレフィックス (デフォルトでは
ratpack.) に一致するキーのみが考慮されます。このプレフィックスは、それ以上の処理の前に削除されます。 - キーは、ドット (“.”) をオブジェクト境界として使用して、オブジェクトごとのセグメントに分割されます。
- 角かっこで囲まれた整数インデックスを使用して、リストを入力できます。
- これは、単純な値 (文字列) とオブジェクト (インデックスの後に追加のセグメントを持つ) の両方でサポートされています。
- この構文は、環境変数ではサポートされていません。
3.18 使い方
1.3.18 順序
複数の設定ソースがある場合は、重要度が低い順にビルダに追加します。たとえば、システムプロパティを使用してオーバーライドできるようにしたい設定ファイルがある場合は、最初に設定ファイルソースを追加し、次にシステムプロパティソースを追加します。同様に、環境変数を使用してオーバーライドできるようにしたいデフォルト設定がある場合は、最初にデフォルト設定ソース (おそらく props を介して) を追加し、次に環境変数ソースを追加します。
2.3.18 エラー処理
ConfigDataBuilder のドキュメント に示すように、onError を使用して、設定ソースからデータをロード中にエラーが発生した場合の動作をカスタマイズできます。最も一般的には、ロード例外を無視して構成ソースをオプションにするために使用されます。
3.3.18 オブジェクトマッパー
Ratpack は、設定オブジェクトのバインディングに Jackson を使用します。使用されるデフォルトの ObjectMapper は、一般的に使用される Jackson モジュールが事前にロードされ、クォートされていないフィールド名を許可し、単一引用符を許可し、不明なフィールド名を無視するように設定されています。これは、すぐに使えるようにすることを目的としています。ただし、Jackson の設定を変更したり、Jackson モジュールを追加したりする必要がある場合があります。その場合は、ConfigData.of(...) のさまざまなシグネチャを使用するか、ConfigDataBuilder.configureObjectMapper(...) を使用して実現できます。
4.3.18 バインディング
ConfigData インスタンスを構築したら、データを構成オブジェクトにバインドできます。最も簡単なオプションは、アプリケーションの構成全体を表すクラスを定義し、ConfigData.get(Class) を使用して一度にすべてをバインドすることです。または、ConfigData.get(String, Class) を使用して、データ内の指定されたパスでオブジェクトを一度に 1 つずつバインドすることもできます。ServerConfig オブジェクトにバインドする一般的なケースでは、便宜上 ConfigData.getServerConfig(...) シグネチャが提供されています。