閱讀(1.2k) 書(shū)簽贊(0) 我要糾錯(cuò)

Micronaut 使用 PropertySources 的外部化配置

2023-03-01 14:24 更新

在初始化 ApplicationContext 之前，可以將其他 PropertySource 實(shí)例添加到環(huán)境中。

初始化環(huán)境

Java Groovy Kotlin

ApplicationContext applicationContext = ApplicationContext.run(
        PropertySource.of(
                "test",
                CollectionUtils.mapOf(
                    "micronaut.server.host", "foo",
                    "micronaut.server.port", 8080
                )
        ),
        "test", "android");
Environment environment = applicationContext.getEnvironment();

assertEquals(
        "foo",
        environment.getProperty("micronaut.server.host", String.class).orElse("localhost")
);

when:
ApplicationContext applicationContext = ApplicationContext.run(
        PropertySource.of(
                "test",
                [
                    "micronaut.server.host": "foo",
                    "micronaut.server.port": 8080
                ]
        ),
        "test", "android")
Environment environment = applicationContext.getEnvironment()

then:
"foo" == environment.getProperty("micronaut.server.host", String.class).orElse("localhost")

val applicationContext = ApplicationContext.run(
    PropertySource.of(
        "test",
        mapOf(
            "micronaut.server.host" to "foo",
            "micronaut.server.port" to 8080
        )
    ),
    "test", "android"
)
val environment = applicationContext.environment

assertEquals(
    "foo",
    environment.getProperty("micronaut.server.host", String::class.java).orElse("localhost")
)

PropertySource.of 方法可用于從值映射創(chuàng)建 PropertySource。

或者，可以通過(guò)創(chuàng)建包含對(duì) PropertySourceLoader 類(lèi)名的引用的 META-INF/services/io.micronaut.context.env.PropertySourceLoader 文件來(lái)注冊(cè) PropertySourceLoader。

包含的 PropertySource 加載器

默認(rèn)情況下，Micronaut 包含從給定位置和優(yōu)先級(jí)加載屬性的 PropertySourceLoader 實(shí)現(xiàn)：

命令行參數(shù)
來(lái)自 SPRING_APPLICATION_JSON 的屬性（為了與 Spring 兼容）
來(lái)自 MICRONAUT_APPLICATION_JSON 的屬性
Java 系統(tǒng)屬性
操作系統(tǒng)環(huán)境變量
配置文件從系統(tǒng)屬性“micronaut.config.files”或環(huán)境變量 MICRONAUT_CONFIG_FILES 中按順序加載。該值可以是以逗號(hào)分隔的路徑列表，最后一個(gè)文件具有優(yōu)先權(quán)。這些文件可以作為路徑從文件系統(tǒng)中引用，或者作為帶有 classpath: 前綴的類(lèi)路徑引用。
來(lái)自 application-{environment}.{extension} 的環(huán)境特定屬性
來(lái)自 application.{extension} 的特定于應(yīng)用程序的屬性

開(kāi)箱即用地支持 .properties、.json、.yml。對(duì)于 Groovy 用戶(hù)，也支持 .groovy。

請(qǐng)注意，如果您想完全控制應(yīng)用程序從何處加載配置，您可以通過(guò)在啟動(dòng)應(yīng)用程序時(shí)調(diào)用 ApplicationContextBuilder 接口的 enableDefaultPropertySources(false) 方法來(lái)禁用上面列出的默認(rèn) PropertySourceLoader 實(shí)現(xiàn)。

在這種情況下，只會(huì)使用您通過(guò) ApplicationContextBuilder 接口的 propertySources(..) 方法添加的顯式 PropertySource 實(shí)例。

通過(guò)命令行提供配置

可以使用 Gradle 或我們的 Maven 插件在命令行中提供配置。例如：

Gradle

$ ./gradlew run --args="-endpoints.health.enabled=true -config.property=test"

Maven

$ ./mvnw mn:run -Dmn.appArgs="-endpoints.health.enabled=true -config.property=test"

為了使配置成為上下文的一部分，必須將 main 方法中的參數(shù)傳遞給上下文構(gòu)建器。例如：

import io.micronaut.runtime.Micronaut;

public class Application {

    public static void main(String[] args) {
        Micronaut.run(Application.class, args); // passing args
    }
}

秘密和敏感配置

重要的是要注意，不建議將敏感配置（例如密碼和令牌）存儲(chǔ)在可能被檢入源代碼控制系統(tǒng)的配置文件中。

最好使用外部秘密管理器系統(tǒng)（這里有很多選項(xiàng)，許多由云提供商提供）或在應(yīng)用程序部署期間設(shè)置的環(huán)境變量，而不是從應(yīng)用程序代碼中完全外部化敏感配置。您還可以使用屬性占位符（請(qǐng)參閱下一節(jié)）來(lái)自定義要使用的環(huán)境變量的名稱(chēng)并提供默認(rèn)值：

使用屬性值占位符定義安全配置

Properties Yaml Toml Groovy Hocon JSON

datasources.default.url=${JDBC_URL:`jdbc:mysql://localhost:3306/db`}
datasources.default.username=${JDBC_USER:root}
datasources.default.password=${JDBC_PASSWORD:}
datasources.default.dialect=MYSQL
datasources.default.driverClassName=${JDBC_DRIVER:com.mysql.cj.jdbc.Driver}

datasources:
  default:
    url: ${JDBC_URL:`jdbc:mysql://localhost:3306/db`}
    username: ${JDBC_USER:root}
    password: ${JDBC_PASSWORD:}
    dialect: MYSQL
    driverClassName: ${JDBC_DRIVER:com.mysql.cj.jdbc.Driver}

[datasources]
  [datasources.default]
    url="${JDBC_URL:`jdbc:mysql://localhost:3306/db`}"
    username="${JDBC_USER:root}"
    password="${JDBC_PASSWORD:}"
    dialect="MYSQL"
    driverClassName="${JDBC_DRIVER:com.mysql.cj.jdbc.Driver}"

datasources {
  'default' {
    url = "${JDBC_URL:`jdbc:mysql://localhost:3306/db`}"
    username = "${JDBC_USER:root}"
    password = "${JDBC_PASSWORD:}"
    dialect = "MYSQL"
    driverClassName = "${JDBC_DRIVER:com.mysql.cj.jdbc.Driver}"
  }
}

{
  datasources {
    default {
      url = "${JDBC_URL:`jdbc:mysql://localhost:3306/db`}"
      username = "${JDBC_USER:root}"
      password = "${JDBC_PASSWORD:}"
      dialect = "MYSQL"
      driverClassName = "${JDBC_DRIVER:com.mysql.cj.jdbc.Driver}"
    }
  }
}

{
  "datasources": {
    "default": {
      "url": "${JDBC_URL:`jdbc:mysql://localhost:3306/db`}",
      "username": "${JDBC_USER:root}",
      "password": "${JDBC_PASSWORD:}",
      "dialect": "MYSQL",
      "driverClassName": "${JDBC_DRIVER:com.mysql.cj.jdbc.Driver}"
    }
  }
}

為了安全地將配置外部化，請(qǐng)考慮使用 Micronaut 支持的秘密管理器系統(tǒng)，例如：

AWS Secrets Manager.
Google Cloud Secrets Manager.
HashiCorp Vault.
Kubernetes Secrets.
Oracle Cloud Vault.

屬性值占位符

如前一節(jié)所述，Micronaut 包含一個(gè)屬性占位符語(yǔ)法，用于在配置值中和任何 Micronaut 注釋中引用配置屬性。

也可以通過(guò) PropertyPlaceholderResolver 接口以編程方式使用。

基本語(yǔ)法是將對(duì)屬性的引用包裝在 ${... } 中。例如：

定義屬性占位符

Properties Yaml Toml Groovy Hocom JSON

myapp.endpoint=http://${micronaut.server.host}:${micronaut.server.port}/foo

myapp:
  endpoint: http://${micronaut.server.host}:${micronaut.server.port}/foo

[myapp]
  endpoint="http://${micronaut.server.host}:${micronaut.server.port}/foo"

myapp {
  endpoint = "http://${micronaut.server.host}:${micronaut.server.port}/foo"
}

{
  myapp {
    endpoint = "http://${micronaut.server.host}:${micronaut.server.port}/foo"
  }
}

{
  "myapp": {
    "endpoint": "http://${micronaut.server.host}:${micronaut.server.port}/foo"
  }
}

上面的示例嵌入了對(duì) micronaut.server.host 和 micronaut.server.port 屬性的引用。

您可以通過(guò)在 : 字符后定義一個(gè)值來(lái)指定默認(rèn)值。例如：

使用默認(rèn)值

Properties Yaml Toml Groovy Hocom JSON

myapp.endpoint=http://${micronaut.server.host:localhost}:${micronaut.server.port:8080}/foo

myapp:
  endpoint: http://${micronaut.server.host:localhost}:${micronaut.server.port:8080}/foo

[myapp]
  endpoint="http://${micronaut.server.host:localhost}:${micronaut.server.port:8080}/foo"

myapp {
  endpoint = "http://${micronaut.server.host:localhost}:${micronaut.server.port:8080}/foo"
}

{
  myapp {
    endpoint = "http://${micronaut.server.host:localhost}:${micronaut.server.port:8080}/foo"
  }
}

{
  "myapp": {
    "endpoint": "http://${micronaut.server.host:localhost}:${micronaut.server.port:8080}/foo"
  }
}

如果沒(méi)有找到值（而不是拋出異常），上面的示例默認(rèn)為 localhost 和端口 8080。請(qǐng)注意，如果默認(rèn)值包含 : 字符，則必須使用反引號(hào)對(duì)其進(jìn)行轉(zhuǎn)義：

使用反引號(hào)

Properties Yaml Toml Groovy Hocom JSON

myapp.endpoint=${server.address:`http://localhost:8080`}/foo

myapp:
  endpoint: ${server.address:`http://localhost:8080`}/foo

[myapp]
  endpoint="${server.address:`http://localhost:8080`}/foo"

myapp {
  endpoint = "${server.address:`http://localhost:8080`}/foo"
}

{
  myapp {
    endpoint = "${server.address:`http://localhost:8080`}/foo"
  }
}

{
  "myapp": {
    "endpoint": "${server.address:`http://localhost:8080`}/foo"
  }
}

上面的示例查找 server.address 屬性并默認(rèn)為 http://localhost:8080。這個(gè)默認(rèn)值用反引號(hào)轉(zhuǎn)義，因?yàn)樗幸粋€(gè) : 字符。

屬性值綁定

請(qǐng)注意，在代碼或占位符值中放置引用時(shí)，這些屬性引用應(yīng)采用 kebab 大小寫(xiě)（小寫(xiě)和連字符分隔）。例如，使用 micronaut.server.default-charset 而不是 micronaut.server.defaultCharset。

Micronaut 仍然允許在配置中指定后者，但將屬性規(guī)范化為 kebab case 形式，以?xún)?yōu)化內(nèi)存消耗并降低解析屬性時(shí)的復(fù)雜性。下表總結(jié)了如何從不同來(lái)源規(guī)范化屬性：

表 1. 屬性值規(guī)范化
配置值	結(jié)果屬性	屬性來(lái)源
`myApp.myStuff`	`my-app.my-stuff`	Properties, YAML etc.
`my-app.myStuff`	`my-app.my-stuff`	Properties, YAML etc.
`myApp.my-stuff`	`my-app.my-stuff`	Properties, YAML etc.
`MYAPP_MYSTUFF`	`myapp.mystuff`, `myapp-mystuff`	Environment Variable
`MY_APP_MY_STUFF`	`my.app.my.stuff`, `my.app.my-stuff`, `my.app-my.stuff`, `my.app-my-stuff`, `my-app.my.stuff`, `my-app.my-stuff`, `my-app-my.stuff`, `my-app-my-stuff`	Environment Variable

環(huán)境變量經(jīng)過(guò)特殊處理以提供更大的靈活性。請(qǐng)注意，無(wú)法使用駝峰式大小寫(xiě)來(lái)引用環(huán)境變量。

由于生成的屬性數(shù)量根據(jù)環(huán)境變量中_字符的數(shù)量呈指數(shù)增長(zhǎng)，因此如果具有多個(gè)下劃線(xiàn)的環(huán)境變量數(shù)量較多，建議細(xì)化配置中包含的環(huán)境變量（如果有）。

要控制環(huán)境屬性如何參與配置，請(qǐng)?jiān)?nbsp;Micronaut 構(gòu)建器上調(diào)用相應(yīng)的方法。

應(yīng)用類(lèi)

Java Groovy Kotlin

import io.micronaut.runtime.Micronaut;

public class Application {

    public static void main(String[] args) {
        Micronaut.build(args)
                .mainClass(Application.class)
                .environmentPropertySource(false)
                //or
                .environmentVariableIncludes("THIS_ENV_ONLY")
                //or
                .environmentVariableExcludes("EXCLUDED_ENV")
                .start();
    }
}

import io.micronaut.runtime.Micronaut

class Application {

    static void main(String[] args) {
        Micronaut.build()
                .mainClass(Application)
                .environmentPropertySource(false)
                //or
                .environmentVariableIncludes("THIS_ENV_ONLY")
                //or
                .environmentVariableExcludes("EXCLUDED_ENV")
                .start()
    }
}

import io.micronaut.runtime.Micronaut

object Application {

    @JvmStatic
    fun main(args: Array<String>) {
        Micronaut.build(null)
                .mainClass(Application::class.java)
                .environmentPropertySource(false)
                //or
                .environmentVariableIncludes("THIS_ENV_ONLY")
                //or
                .environmentVariableExcludes("EXCLUDED_ENV")
                .start()
    }
}

上面的配置對(duì)屬性占位符沒(méi)有任何影響。無(wú)論是否禁用環(huán)境配置，或者即使明確排除特定屬性，仍然可以在占位符中引用環(huán)境變量。

使用隨機(jī)屬性

您可以通過(guò)使用以下屬性來(lái)使用隨機(jī)值。這些可以在配置文件中用作變量，如下所示。

Properties Yaml Toml Groovy Hocon JSON

micronaut.application.name=myapplication
micronaut.application.instance.id=${random.shortuuid}

micronaut:
  application:
    name: myapplication
    instance:
      id: ${random.shortuuid}

[micronaut]
  [micronaut.application]
    name="myapplication"
    [micronaut.application.instance]
      id="${random.shortuuid}"

micronaut {
  application {
    name = "myapplication"
    instance {
      id = "${random.shortuuid}"
    }
  }
}

{
  micronaut {
    application {
      name = "myapplication"
      instance {
        id = "${random.shortuuid}"
      }
    }
  }
}

{
  "micronaut": {
    "application": {
      "name": "myapplication",
      "instance": {
        "id": "${random.shortuuid}"
      }
    }
  }
}

表 2. 隨機(jī)值
屬性	值
random.port	一個(gè)可用的隨機(jī)端口號(hào)
random.int	隨機(jī)整數(shù)
random.integer	隨機(jī)整數(shù)
random.long	隨機(jī)長(zhǎng)整數(shù)
random.float	隨機(jī)浮點(diǎn)數(shù)
random.shortuuid	長(zhǎng)度僅為 10 個(gè)字符的隨機(jī) UUID（注意：由于這不是完整的 UUID，可能會(huì)發(fā)生沖突）
random.uuid	帶破折號(hào)的隨機(jī) UUID
random.uuid2	沒(méi)有破折號(hào)的隨機(jī) UUID

random.int、random.integer、random.long 和 random.float 屬性支持范圍后綴，其語(yǔ)法為以下之一：

(max) 其中 max 是一個(gè)獨(dú)占值
[min,max] 其中 min 是包容性的，max 是獨(dú)占的。

Properties Yaml Toml Groovy Hocon JSON

instance.id=${random.int[5,10]}
instance.count=${random.int(5)}

instance:
  id: ${random.int[5,10]}
  count: ${random.int(5)}

[instance]
  id="${random.int[5,10]}"
  count="${random.int(5)}"

instance {
  id = "${random.int[5,10]}"
  count = "${random.int(5)}"
}

{
  instance {
    id = "${random.int[5,10]}"
    count = "${random.int(5)}"
  }
}

{
  "instance": {
    "id": "${random.int[5,10]}",
    "count": "${random.int(5)}"
  }
}

該范圍也可以從負(fù)到正變化。

快速失敗屬性注入

對(duì)于注入所需屬性的 bean，在請(qǐng)求 bean 之前不會(huì)發(fā)生注入和潛在的失敗。要在啟動(dòng)時(shí)驗(yàn)證屬性是否存在并且可以注入，可以使用 @Context 對(duì) bean 進(jìn)行注釋。上下文范圍的 beans 在啟動(dòng)時(shí)注入，如果缺少任何必需的屬性或無(wú)法轉(zhuǎn)換為所需的類(lèi)型，則啟動(dòng)將失敗。