MicroProfile Config 3.0へのキャッチアップ

Helidon 3.0がリリースされMicroProfile5.0準拠となり、ついにHelidonでもMicroProfile Config 3.0(MP Config 3.0)の機能が使えるようになりました。そこで今回は前回紹介できなかった2.0から3.0までに取り入れられた便利な機能をその差分として紹介します。このため、今回の記事は以前紹介した「お手軽便利MicroProfile Config」の理解を前提にしています。まだの方はそちらから読んでいただければと思います。

記事はコードの抜粋を記載します。全体を見たい場合や動作を確認したい場合は以下のGitHubリポジトリを参照ください。

• https://github.com/extact-io/contrarian-microprofile-sample/tree/main/05-config_3.0

MP Config 2.0から3.0までに取り入れられた便利な機能として今回紹介するのは次の2つとなります。

• 設定データの集約
• Config Profile

いずれもMP Config 2.0で取り込まれた便利な目玉的機能となります。

意味的にまとまった設定値があっても、MP Config 1.4では設定値を粒々1つずつ取得するしかありませんでした。これがMP Config 2.0で導入された設定データの集約機能を使うと、アプリケーションで定義した任意のデータクラスに設定値を直接バインドしてもらうことができるようになります。

例えば次のようなDBの接続情報に関する3つの設定があったとします。

sample.db.url=jdbc:h2:tcp://localhost/~/sample
sample.db.id=sample
sample.db.password=sample

意味的にまとまったデータをアプリケーションで扱う場合、データの意味を表すクラスを定義し、関連する情報を1つのインスタンスにまとめて管理したくなります。このようなことをMP Config 1.4で行う場合、Configインスタンスから個別に設定値を取得し、その値をインスタンスに格納する処理を自分で実装する必要があり面倒でした。

MP Config2.0から導入された設定データの集約機能を使うことで、次のように設定値をデータクラスにまとめて取得できるようになります。

@ConfigProperties(prefix = "sample.db") // 1.
@Dependent // 2.
public class DbInfo {
    private String url;
    @ConfigProperty(name = "id") // 3.
    private String user;
    private String password;
}

1. 設定値をバインドするデータクラスには@ConfigPropertiesを付け、name属性にバインドする設定キーのプレフィクスを定義します。これを定義するだけでフィールドにはprefixで指定したキー名.フィールド名の設定値がバインドされるようになります。
   なお、MP Configランタイムは可視性に関係なくフィールドに直接アクセスするため、setterは必要ありません。
2. 設定値をバインドするオブジェクトはCDI Beanとする必要があります。このため、なんらかのCDIスコープアノテーションを付与します。
3. 1.で説明したとおりデフォルトではフィールド名が設定キー名の一部となりますが、設定キー名とバインドさせたいフィールド名が異なる場合は@ConfigPropertyのname属性にマッピングを定義することができます。

次にこの@ConfigPropertiesを付けたデータクラスで設定値を受け取る方法ですが、これには２つあります。１つはCDIクラスから動的に取得する方法、もう一つは@Injectのインジェクションによる取得する方法です。それでは具体的な方法を見ていきます。

まずCDIクラスからの取得は次のようになります。

DbInfo sampleDbInfo = CDI.current()
        .select(DbInfo.class, ConfigProperties.Literal.NO_PREFIX)
        .get();

データクラスのインスタンスが1つしかない場合でもCDI#select()の第2引数のQualifierの指定は必要となります。@ConfigPropertiesの中身を見れば分かりますが、その実体はQualifierです。Qualifier指定が必要なのはMP Configランタイムが@ConfigProperties指定されたCDI Beanを設定値のバインドが必要な特別なBeanとして扱うためと思われます。

次にもう一つのインジェクションによる取得は次のようになります。

@ApplicationScoped
public class ConfigBean {
    @Inject
    @ConfigProperties
    private DbInfo sampleDbInfo;
    ...
}

CDIクラスからの取得と同様に@Injectで取得する場合も@ConfigProperties指定が必要となります。

ここまでが基本的な利用法となります。次からは細かい機能やルールなどを紹介してきます。

今までの例は設定キーのレベルがすべて同じでしたが、次のようにレベルが深い設定キーがあった場合、どうすればいいでしょうか。

sample.db.url=jdbc:h2:tcp://localhost/~/sample
sample.db.id=sample
sample.db.password=sample
### ↓↓ キーのレベルが深くなる設定
sample.db.option.prop1=sample-option1
sample.db.option.prop2=sample-option1

このような場合も１つのデータクラスにバインドさせることができます。レベルが深くなる設定キーがある場合は次のように@ConfigPropertyのname属性にキー名の後続部分を明示することで該当する設定値をバインドさせることができます。

@ConfigProperties(prefix = "sample.db")
@Dependent
public class DbInfo {
    private String url;
    ...
    @ConfigProperty(name = "option.prop1")
    private Optional<String> prop1;
    @ConfigProperty(name = "option.prop2")
    private Optional<String> prop2;
}

例の補足として、フィールドの型をOptionalにしているのは設定なしも許容する任意設定の項目を想定しているからで、これはMP Configの仕様とは関係ありません。

@ConfigProperties(prefix = "sample.db")
@Dependent
public class DbInfo {
    private String url;
    ...
    @ConfigProperty(name = "option")
    private Options option;
    // ネストクラス
    static class Options {
        private Optional<String> prop1;
        private Optional<String> prop2;
    }
}

今までの例は1つのデータクラスに対してバインドする設定値(の塊)は1つでしたが、今度は次ように接続先が2つあった場合の例を見ていきます。

sample.db.url=jdbc:h2:tcp://localhost/~/sample
sample.db.id=sample
...
test.db.url=jdbc:h2:tcp://localhost/~/test
test.db.id=test
test.db.password=test

設定値が異なるだけで、両者とも構造は全く同じなのでどちらもDbInfoクラスで取得したいですよね？そんな時はデータクラスに指定した@ConfigPropertiesのprefix属性を次のように外側からオーバーライドすることができます。

• CDIクラスからの取得

DbInfo testDbInfo = CDI.current()
        .select(DbInfo.class, ConfigProperties.Literal.of("test.db"))
        .get();

ConfigProperties.Literal.of("test.db")は動的に@ConfigProperties(prefix = "test.db")を生成しているのと等価になります。

• インジェクションによる取得

@ApplicationScoped
public class ConfigBean {
    @Inject
    @ConfigProperties
    private DbInfo sampleDbInfo;
    @Inject
    @ConfigProperties(prefix = "test.db")
    private DbInfo testDbInfo;
}

データクラスに指定した@ConfigPropertiesのprefix属性はあくまでもそのデータクラスにバインドする設定キーのデフォルト値的な扱いになります。ですので、それ以外の設定キーをバインドしたい場合は今回の例のようにprefix指定を外側（利用者側）から上書き指定します。

設定データの集約機能の説明はこれで終わりとなります。次からはもう1つの紹介機能のConfig Profileを説明していきます。

設定ファイルを使って定義する典型的な情報として環境依存に関するものがあります。これまでの例で使っていたDBの接続情報ですが、ローカル環境、IT環境、本番環境で異なるのが普通です。では環境による設定情報の切り替えはどのようにすればよいでしょうか？と言いうお題に対してMP Config2.0から用意されたのが、今から説明するConfig Profileになります。

この機能は見た方が早いと思うので、まずは接続情報が環境ごとに異なる場合の設定例から見てもらいます。

# ローカル環境の設定
%dev.sample.db.url=jdbc:h2:tcp://localhost/~/dev
%dev.sample.db.id=dev
%dev.sample.db.password=dev
%dev.sample.db.option.prop2=dev-option1
# IT環境の設定
%it.sample.db.url=jdbc:h2:tcp://localhost/~/it
%it.sample.db.id=it
%it.sample.db.password=it
# 本番環境の設定
%prod.sample.db.url=jdbc:h2:tcp://localhost/~/prod
%prod.sample.db.id=prod
%prod.sample.db.password=prod

Config Profileでは%をつけた任意のプロファイル名をキーに付加できるようになっています。この例ではローカル環境は%dev、IT環境は%it、そして本番環境は%prodとしてプロファイルキーを付加して、それぞれの設定値を定義しています。

この設定でやりたいことは、ローカル環境(devプロファイル)ならsample.db.urlの設定としてjdbc:h2:tcp://localhost/~/devを返してもらうことですが、このMP Configランタイムに対するプロファイルの指定はシステムプロパティのmp.config.profileで行います。

それではプロファイルを指定して設定ファイルを取得した実行結果を見ていきましょう（コンソールにはDbInfoクラスのオブジェクト内容を出力するようにオーバーライドしたtoStringメソッドの結果を出力しています）

• ローカル環境(devプロファイル)を指定して実行

java -Dmp.config.profile=dev -jar target/config3-sample.jar
sample.db=>DbInfo [url=jdbc:h2:tcp://localhost/~/dev, user=dev, password=dev, prop1=Optional.empty, prop2=Optional[dev-option1]]

• IT環境(itプロファイル)を指定して実行

java -Dmp.config.profile=it -jar target/config3-sample.jar
sample.db=>DbInfo [url=jdbc:h2:tcp://localhost/~/it, user=it, password=it, prop1=Optional.empty, prop2=Optional.empty]

• 本番環境(prodプロファイル)を指定して実行

java -Dmp.config.profile=prod -jar target/config3-sample.jar
sample.db=>DbInfo [url=jdbc:h2:tcp://localhost/~/prod, user=prod, password=prod, prop1=Optional.empty, prop2=Optional.empty]

• プロファイルを指定せずに実行

java -jar target/config3-sample.jar
Exception in thread "main" java.lang.ExceptionInInitializerError

実行結果から分かるように、MP Configはmp.config.profileでプロファイルが指定されている場合、プログラムで指定されているキー名に%profileを付加して設定を検索します。これによりプログラムで指定するキー名は変えず、プロファイルに応じた設定値を取得することができるようになります。

ただ、この設定ではプロファイルを指定しなかった場合、実行時にエラーとなってしまいます。プロファイルが指定されない場合、ケースにもよりますが、エラーではなく、デフォルト的な設定を返すようにしたい場合もあると思います。このような場合は次のようにプロファイルキーを含まない設定を付けておきます。

%dev.sample.db.url=jdbc:h2:tcp://localhost/~/dev
...
%it.sample.db.url=jdbc:h2:tcp://localhost/~/it
...
%prod.sample.db.url=jdbc:h2:tcp://localhost/~/prod
...
sample.db.url=jdbc:h2:tcp://localhost/~/sample
sample.db.id=sample
sample.db.password=sample
sample.db.option.prop1=sample-option1
sample.db.option.prop2=sample-option1

MP Configはプロファイルが指定されている場合、そのプロフィルキーが付いた設定を優先的に検索しますが、該当がない場合はプロフィルキーなしの設定にフォールバックして検索を行います。

1つの設定ファイル内の設定をプロファイルで切り替える例を見てきましたが、Config Profileは設定ファイルごとまるごと切り替えることもできます。

上で見てきた例を設定ファイル単位で切り替える場合は、以下のようにファイル名をmicroprofile-config-<profile>.propertiesとしたプロファイルごとの設定を用意します。なお、設定ファイル内の切り替えと違いを分かりやすくするためプロファイル名はdev-env, it-env, prod-envと後ろに-envが付いたプロファイル名に変えています。

• ファイルの配置と一覧

META-INF
 |-- microprofile-config-dev-env.properties
 |-- microprofile-config-it-env.properties
 |-- microprofile-config-prod-env.properties
 `-- microprofile-config.properties

• META-INF/microprofile-config-dev-env.properties(devプロファイル)

sample.db.url=jdbc:h2:tcp://localhost/~/dev-env
sample.db.id=dev-env
sample.db.password=dev-env
sample.db.option.prop2=dev-env-option1

• META-INF/microprofile-config-it-env.properties(itプロファイル)

sample.db.url=jdbc:h2:tcp://localhost/~/it-env
sample.db.id=it-env
sample.db.password=it-env

• META-INF/microprofile-config-prod-env.properties(prodプロファイル)

sample.db.url=jdbc:h2:tcp://localhost/~/prod-env
sample.db.id=prod-env
sample.db.password=prod-env

• META-INF/microprofile-config.properties(デフォルト)

sample.db.url=jdbc:h2:tcp://localhost/~/sample
sample.db.id=sample
sample.db.password=sample
sample.db.option.prop1=sample-option1
sample.db.option.prop2=sample-option1

プロファイルごとの設定ファイルを用意した場合はプロファイルで指定された設定ファイルだけが読み込まれるようになります。また、先ほどと同様に指定されたプロファイルに該当する設定ファイルがない場合はプロファイル名なしの設定ファイル読み込みにフォールバックします。

1つの設定ファイル内に複数のプロファイル設定をする設定値の切り替えでは問題となりませんが、設定ファイルごとの切り替え方式は、親となる無印の設定ファイル(microprofile-config.properties)だけを見てもどの設定がプロファイルにより変わる項目かが分かりません。

また、これは1つの設定ファイル内に複数のプロファイル設定をする場合も同じですが、同じ設定キーを繰り返して定義するため、設定キーが変更された場合、広範に渡って影響を受けます。自アプリが定義した設定項目だけであれば「変えなければよい」という話ですが、他のアプリやライブラリに依存した設定項目の場合、そうはいかず、外部要因の変更影響をモロに受けます。

このため、プロファイルで切り替える設定項目は、以下の要件を満たすべきです。

• プロファイルで切り替わる設定項目であることを分かりやすくする
• 外部要因による設定キーの変更箇所を局所化する

これを満たすために、値を直接設定するのではなく、MP Configのプロパティ式（置換変数）で定義する方法があります。

Config Profileによる設定ファイルの切り替えで使った例をプロパティ式を使って書き換えた場合、次のようになります。

• META-INF/microprofile-config.properties(デフォルト)

# プロファイルの切り替え項目
url=jdbc:h2:tcp://localhost/~/sample
id=sample
password=sample
# プロフラムからアクセスされる設定
sample.db.url=${url}
sample.db.id=${id}
sample.db.password=${password}
sample.db.option.prop1=sample-option1
sample.db.option.prop2=sample-option1

• META-INF/microprofile-config-dev-env.properties(devプロファイル)

url=jdbc:h2:tcp://localhost/~/dev-env
...

• META-INF/microprofile-config-it-env.properties(itプロファイル)

url=jdbc:h2:tcp://localhost/~/it-env
...

• META-INF/microprofile-config-prod-env.properties(prodプロファイル)

url=jdbc:h2:tcp://localhost/~/prod-env
...

アプリケーションからアクセスされる設定キー(sample.db.*)を定義するのは親となる無印の設定ファイルだけとなり、そこにはプロパティ式で値を設定するようにします。プロパティ式の値はプロファイルごとの設定ファイルに定義されているため、Config Profile機能で使用される設定ファイルが切り替わることでプロパティ式の値が変わるようになります。

server.url=http://${server.host:example.org}:${server.port}/${server.endpoint}
server.port=8080
server.endpoint=${server.endpoint.path.${server.endpoint.path.bar}}
server.endpoint.path.foo=foo
server.endpoint.path.bar=foo

MP Config 2.0では今回紹介した設定データの集約とConfig Profileの2つの大きな機能が追加されました。

Config Profileは一見便利に見えますが対象とする実行環境に不要な設定がランタイムに含まれるようになります。本質的に常に存在すべき設定であれば、jarの再作成(リビルド)なしに設定を切り替えることができるようになるため非常に便利な機能となりますが、例で説明したような環境ごとの切り替えに利用する場合、ランタイムに不要な設定情報を含むことになるため、その利用の是非^[2]はあるかと思います。

また、設定データの集約は配列などの繰り返し項目やデータクラスのネスト構造は扱えないため、実用観点では今一歩だったりします。

しかしながら、仕様が着実に進化し、できることの選択肢が増えることは歓迎すべきことではないでしょうか。