[17.0.0.3 以及更新版本]

MicroProfile 配置 API

「MicroProfile 配置 API」可供應用程式當成單一 API 使用,以用來擷取不同來源中的配置資訊。

在您使用「MicroProfile 配置 API」時:
  • 可以將多個配置來源合併成單一配置,且透過單一 API 就能存取。
  • 可以用指定成具有較高優先順序之配置來源中的值,置換配置內容值。
  • 可以將值儲存在指名的內容檔、系統環境變數或 Java™ 系統內容中。
  • ConfigSource 資源是以 Java ClassLoader 來載入,可以是應用程式的現行環境定義 ClassLoader 或是使用者提供的 ClassLoader
  • 可以藉由登錄使用者的 ConfigSource 介面實作,來提供值。
  • 可以利用內建或自訂類型「轉換器」,以「字串」或特定 Java 類別的類型化物件,來擷取值。
  • 可以透過 Java ServiceLoader 型樣,探索 ConfigSourceConverter 實作。
  • 可以利用 Java CDI(環境定義和相依關係注入),直接注入配置內容值(不論是初始類型、標準類型,或使用者提供的類型)。

配置注入

「MicroProfile 配置 API」會收集預設配置來源,以及 Java ServiceLoader configsources 所載入的配置來源(會在這個主題後續中討論)。透過 Java CDI(環境定義和相依關係注入),就能將配置物件直接注入至應用程式。

@Inject
Config config;
String appName = config.getValue("APP_NAME", String.class);

此外,也可以注入單一配置內容值。

@Inject
@ConfigProperty
String PROPERTY_NAME1;

如同標準 Java 內容,這些內容以「字串」原始形式表示。系統會使用配置來源的預設值,並從 classname 的名稱取得配置內容的名稱,其中,第一個字母是小寫,後面附加變數名稱,且分隔字元是句點。比方說,如果前一個 Snippet 位於稱為 ClassA 的類別中,解析後的內容名稱會是 classA.PROPERTY_NAME1

@Inject
@ConfigProperty(name="PROPERTY_NAME2")
String propertyTwo;

此程式碼 Snippet 會查閱配置來源中的必要內容 PROPERTY_NAME2。如果該內容不存在,會擲出 DeploymentException。

如果內容不存在於所配置的任何 configsources 中,請使用 defaultValue 參數來指派預設值。
@inject
@ConfigProperty(name="myName", defaultValue="Bob")
String name;
此程式碼 Snippet 會查閱所配置之 configsources 中的 myName 內容。如果未定義該內容,會將值 Bob 指派給 name 變數。

以程式設計方式來查閱配置

「MicroProfile 配置 API」還提供介面,可藉由方法呼叫來擷取配置內容。這種擷取有兩種方式來完成,一種是好用的配置提供者類別(使用預設值),一種是可完全自訂的配置建置器類別。

ConfigProvider 類別

最簡單的配置用法是在 ConfigProvider 類別上使用靜態方法。此 API 會收集預設配置來源,以及 Java® ServiceLoader configsources 載入的配置來源。

Config config = ConfigProvider.getConfig();
String appName = config.getValue("APP_NAME", String.class);

ConfigBuilder 類別

如果使用者想採較為自訂的方式來建立配置,可以在產生配置之前,使用配置建置器 API 來設定各種選項。本例使用建置器型樣,來建置等同於上述範例的配置。

ConfigBuilder builder = ConfigProviderResolver.getBuilder();
builder.addDefaultSources();
Config config = builder.build();

呼叫 builder.addDefaultSources() 時,會新增 ConfigProvider 用來建置配置的同一組預設來源。也會新增其他的配置來源。

配置來源

配置內容可以來自許多位置,包括:內容檔,以及應用程式所登錄或透過 Java ServiceLoader 型樣所載入的使用者類別。

預設來源

不同於 ConfigProvider 介面,ConfigBuilder 介面一開始的配置內容來源集是空的。新增預設來源會有下列結果:

  1. 配置中會包含程序環境變數。Liberty 會顯示主機程序環境變數給 Java System.getenv() 方法,還會新增伺服器 server.env 檔中的內容。之後,這些變數即可供「MicroProfile 配置 API」使用。
  2. 配置中會包含藉由 System.getProperties() 提供的「Java 系統內容」。Liberty 會將伺服器 bootstrap.propertiesjvm.options 檔中的內容新增至「Java 系統內容」。
  3. 從應用程式 ThreadContextClassLoader 類別路徑載入的檔案,且其 resourceNameMETA-INF/microprofile-config.properties。在這些內容檔中,會使用標準 Java 內容檔所使用的相同語法,來儲存內容。對於 Liberty 應用程式,META-INF 目錄位置可能是一個子目錄,它位於 JAR 或 WAR 檔 WEB-INF\classes\META-INF\ 目錄的根目錄,或 EAR lib 目錄的 JAR 中,或伺服器層次共用程式庫 JAR 中。可以利用建置器的 forClassLoader 方法,來變更使用的 ClassLoader(因而包括類別路徑)。

使用者提供的 ConfigSource

實作 org.eclipse.microprofile.config.spi.ConfigSource 的使用者類別可以向 ConfigBuilder 登錄。如此一來,這個使用者類別之後就會包含在建置器產生的配置中。

MySource source = new MySource();
builder.withSources(source);

透過 Java ServiceLoader 載入 ConfigSource

Java ServiceLoader 型樣也可以用來尋找自訂配置來源物件。對於實作 ConfigSource 介面的使用者類別,如果其完整套件的完整類別名稱列在 ${CLASSPATH}/META-INF/services/org.eclipse.microprofile.config.spi.ConfigSource 格式的檔案中,則會載入該使用者類別。

轉換器

「MicroProfile 配置 API」也可以利用一般化方法(採用所要的內容物件類型),以 Java 物件類型形式來擷取內容。只要類型具有內建或使用者提供的轉換器,此方法都適用。例如,上述範例中的程式碼可以依下列所示,撰寫成使用內建「字串」轉換器:

appName = config.getOptionalValue(“APP_NAME”, String.class).orElse(“MicroDemo”);

內建轉換器

「MicroProfile 配置 API」包含下列類型的內建轉換器:booleanBooleanintIntegerlongLongfloatFloatdoubleDoubleDurationLocalTime LocalDateLocalDateTimeOffsetDateTimeOffsetTimeInstant,以及 URL

上述任何類型的變數都可以直接注入,或者利用一般化 getValue 呼叫來擷取。但前提是可以使用相關的 valueofparse 或建構子方法(採用單一「字串」參數),順利將內容的字串值轉換成類型。

自訂轉換器

利用 ConfigBuilder API,就可以登錄實作 org.eclipse.microprofile.config.spi.Converter<T> 介面的自訂轉換器,並且用於配置中。

ConfigBuilder builder = ConfigProviderResolver.getBuilder();
builder.addDefaultSources();
Converter<CustomProperty> converter = new MyConverter(); 
builder.withConverters(converter);
Config config = builder.build();
Optional<CustomProperty> opt = config.getOptionalValue(“PROPOBJ”, CustomProperty.class);
withConverters 方法使用反射,來判斷轉換器用於哪種類型。Java Lambda 程式碼目前並未提供具體足夠的類型資訊給反射 API,因此對於自訂轉換器,需要明確實作 Converter<T> 介面的程式碼。

轉換器優先順序

如果相同的類型有多個轉換器,可以利用 @Priority 註釋來控制所使用的轉換器。以應用程式生命週期來說,此方法容許在之後置換「轉換器」實作。轉換器會置換用於相同類型且優先順序較低的其他任何轉換器。

import javax.annotation.Priority;
import org.eclipse.microprofile.config.spi.Converter;
@Priority(200)
publicclass StringPrefixConverter implements Converter<String> {
    @Override
    public String convert(String value) throws IllegalArgumentException {
        return"Converted:" + value;
    }
}

如果未使用 @Priority 註釋,則轉換器的預設優先順序是 100。

Java ServiceLoader 支援轉換器

只要自訂轉換器的套件完整類別名稱出現在 ${CLASSPATH}/META-INF/services/org.eclipse.microprofile.config.spi.Converter 格式的服務檔中,也可以使用 Java ServiceLoader 型樣來尋找該自訂轉換器。

「MicroProfile 配置 API」實作中包含的預設轉換器,以及透過 Java ServiceLoader 型樣探索的轉換器,都可供所有配置使用。

置換內容值

當使用多個配置來源時,會將所有來源中的內容收集在一起,並供應用程式當成單一集合來存取。會為每一個配置來源指派一個序數值。若有內容出現在多個來源中,則會優先採用序數最高之來源中的內容值,並傳回給應用程式。預設序數值如下:

  • 系統內容 - 400
  • 環境變數 - 300
  • /META-INF/microprofile-config.properties - 100
  • 自訂 ConfigSource 物件 - ConfigSourcegetOrdinal 結果
註: 可以使用 config_ordinal 內容來置換所列出的前三個序數值,這個內容位於套用它的配置來源中。

如果提供相同內容的兩個 ConfigSources 具有相同的序數,則會根據字串比較規則,使用 ConfigSources ID 來比較。

在開發生命週期中通常較早設定的來源,其序數與優先順序較低。這是為了在應用程式生命週期中,之後能夠置換現有的內容值,例如:在應用程式組合或安裝期間。

動態內容值

儘管設計得宜的微服務應用程式能透過個別應用程式的重新啟動來維護可用性,更好的作法是,應用程式不需重新啟動,就可以使用配置值的變更。已登錄之 ConfigSource 物件在配置中所提供的內容值,可以使用 ConfigSources 提供的任何已更新值來重新整理。查詢 ConfigSources 的頻率以及任何要重新整理的值,由 microprofile.config.refresh.rate Java 系統內容來控制。使用的單位是毫秒,預設值是 500,這表示依預設,ConfigSources 所提供的值約半秒就會輸送至他們所參與的任何「配置」。

在起始配置建構之後,不會動態重讀非程式化的配置來源,例如 microprofile-config.properties 檔。

如果希望在注入內容之後,能夠看到值中的更新,可以使用 ConfigValue 物件。對於配置內容值和配置內容值的 Optional<T>,此物件都具有 getter,每當呼叫 getter 時,就會傳回現行值。例如:

@Inject
@ConfigProperty(name="propertyName3") 
Provider<MyClass> propertyName3;
MyClass mc = propertyName3.get();

您也會看到 ConfigValue 類別已一般化,並可用來擷取特定類型的內容(如果存在合適的「轉換器」)。

配置快取

為了提升效率,ConfigProvider 會快取其 getConfig 方法針對其 ClassLoader 所識別之特定應用程式(或模組),所傳回的配置。如果配置是利用 ConfigBuilder 產生,就不會快取配置物件。不過,org.eclipse.microprofile.config.spi 套件中的 ConfigProviderResolver 具有 registerConfig 方法,可用來快取「配置」物件,以及具有 releaseConfig 方法,可用來釋放「配置」物件。

如需在 Liberty 中實作 MicroProfile 配置的相關資訊,請參閱 MicroProfile 配置專案網站


指示主題類型的圖示 概念主題

檔名:cwlp_microprofile_overview.html