芭蕾舞女演员中的配置管理

这篇文章是对我之前关于config API的文章的一种全面的过期跟进:https://medium.com/@pubuduf/ballerina-config-api-f6a9c455267b。 config API对Ballerina 0.970.0版本进行了重大重构。 对于0.970.0版本引入的新型系统,使用当时的API检索配置变得很麻烦。 在某些情况下,必须编写5-10个行函数才能读取所需数据类型中的单个配置值(例如,将端口号检索为整数)。 为了解决这个问题,引入了一个新的综合API。 除了更改API外,还进行了以下更改:

  • 采用TOML作为配置文件格式。
  • 添加了一种机制,用于安全地在配置文件中存储敏感数据/从配置文件中读取敏感数据。
  • 改进了配置解析。

TOML配置

芭蕾舞女演员包管理工具使用TOML进行配置。 为了使Ballerina的各个方面保持一致,并且由于配置文件格式已经非常接近TOML,因此我们也选择将TOML用作config API。 但是,当前不支持某些功能(例如,数组,内联表)。

让我们通过使用config API配置简单的回显服务来查看更改。

新的配置文件格式

我们将使用以下配置文件来配置echo服务。

可以看出,旧格式和新采用的TOML格式之间没有太大区别。 最显着的区别是在基于TOML的配置中如何处理配置值。 以前,所有配置值都被视为字符串。 因此,不需要将字符串值括在引号中。 但是,在TOML中,值可以是以下类型:字符串,整数,浮点数,布尔值,日期时间,数组或内联表。 但是,配置API仅支持以下值类型:字符串,整数,浮点型和布尔型。 如果值是字符串,那么现在必须将值用引号引起来。

配置解析

在Ballerina运行时开始时,已解析配置并将其存储在注册表中。 配置源优先级层次结构保持不变,并且按照优先级从高到低的顺序如下:

  1. 运行时参数(通过CLI使用-e标志提供给run命令)
    例如, $ ballerina run -e b7a.log.level=DEBUG foo.bal
  2. 环境变量
    由于环境变量中不允许使用句点,因此在查找环境变量时,配置键中的句点将用下划线替换。 因此,如果您要设置环境变量以覆盖使用配置文件或默认配置提供的配置,则应在配置密钥中使用下划线代替句点(如果有)。
  3. 配置文件
  4. 默认配置(硬编码配置,例如日志级别)

给定程序的配置可以是上述4种配置源的混合。 如果多个源中存在相同的配置密钥,则优先级最高的源。

新API

以下API供用户使用:

  • public function contains(string key) returns boolean
    这可用于检查配置注册表中是否存在特定配置。 如果需要区分从getAsXXX()函数返回的默认值和不存在配置,这很有用,因为默认值也是在不存在配置的情况下返回的。
  • public function getAsBoolean(string key, boolean default = false) returns boolean
    boolean值返回指定键的配置值。 如果注册表中存在该配置,则将其返回。 如果您尝试检索的值是一个字符串,它将尝试将其解析为boolean 。 如果值为“ true”(忽略大小写),它将返回true。
  • public function getAsFloat(string key, float default = 0.0) returns float
    float返回指定键的配置值。 如果实际值不是floatint或可解析为floatstring ,则将导致恐慌。
  • public function getAsInt(string key, int default = 0) returns int
    int返回指定键的配置值。 如果实际值既不是int也不是可解析为intstring ,则将导致恐慌。
  • public function getAsMap(string key) returns map
    返回一组相关的配置(以TOML术语表)作为映射。 例如,调用config:getAsMap("echo")将返回具有表“ echo”中所有配置的映射。 如果没有这样的表或它是一个空表,则将返回一个空映射。
  • public function getAsString(string key, string default = "") returns string
    string返回指定键的配置值。
  • public function setConfig(string key, string|int|float|boolean value)
    可用于将配置添加到Ballerina代码中的注册表中。

请注意,getAsXXX()函数中的可选参数default (getAsMap()中的参数除外)。 如果在注册表中找不到指定的配置键,则返回此值。 如果在运行时缺少必需的配置,这很有用,但是您仍然想尝试使用默认值运行它。
例如, config:getAsString("host", default = "localhost")

以下简单的回显服务演示了此新API的用法。

可以看出,这种方法比以前的方法更友好,因为以前的方法是将值转换为适当的类型以供用户执行。

可以使用以下配置文件运行以上服务:
$ ballerina run -c echo.conf echo_service.bal
$ ballerina run --config echo.conf echo_service.bal

确保敏感的配置值

您可能已经注意到,在我们使用的上述配置文件中,密钥存储区密码以纯文本格式存储。 使用Ballerina 0.970.0,使用用于加密敏感值的加密工具进一步增强了配置API。

要加密一个值,可以使用ballerina encrypt命令。 使用此工具对密钥存储区密码进行加密后,这就是终端中的外观。 值“芭蕾舞女演员”使用密码“ 1234”加密。

  $芭蕾舞女演员加密 
输入值:
 输入密码: 
 重新输入密码以验证: 
 将以下内容添加到运行时配置中: 
@encrypted:{92XujbVRx + rXspbI / 8sbdpdrmBmMF1PBDnuVUJKdK / 0 =}
 或添加到运行时命令行: 
-e = @加密的:{92XujbVRx + rXspbI / 8sbdpdrmBmMF1PBDnuVUJKdK / 0 =}

以下是更新的配置文件,纯文本密码已替换为其加密版本。

现在,让我们尝试使用此更新的配置文件运行回显服务。

  $芭蕾舞演员运行-c secure-echo.conf echo_service.bal 
芭蕾舞女演员:为配置值解密输入密码:
 在“ echo_service.bal”中启动服务 
[ballerina / http]已启动HTTPS / WSS端点0.0.0.0:9095
[ballerina / http]已启动HTTP / WS端点0.0.0.0:9090

如果运行时在提供给它的配置中检测到任何加密的值,它将提示用户输入密码(加密值时使用的密码)。 提供不正确的机密将导致恐慌。

运行程序时使用的所有加密配置值都应使用相同的机密进行加密。

另外,您可以将密码放置在文件中,并使用-e b7a.config.secret标志指向该-e b7a.config.secret 。 设置此标志后,运行时将从文件中读取机密并删除文件。 在这种情况下,不会提示用户输入密码。 这是将秘密提供给config API的更实际的方法。

让我们尝试一下。 创建一个文件(例如, secret.txt )并将其放入其中(在本例中为1234)。

  $ ls 
echo_service.bal secret.txt secure-echo.conf

现在,在设置了b7a.config.secret标志的情况下运行该程序。

  $芭蕾舞演员运行-c secure-echo.conf -e b7a.config.secret = secret.txt echo_service.bal 
在“ echo_service.bal”中启动服务
[ballerina / http]已启动HTTPS / WSS端点0.0.0.0:9095
[ballerina / http]已启动HTTP / WS端点0.0.0.0:9090

可以看到,没有提示用户。 现在,如果再次运行ls ,我们可以看到secret.txt文件已删除。

  $ ls 
echo_service.bal secure-echo.conf

从代码的角度来看,普通配置和加密配置的访问方式之间没有区别:您可以使用密钥来检索它。 在内部,加密值以其加密形式存储在注册表中,而纯文本值按原样存储在注册表中。 使用运行时开始时提供的密钥按需解密加密的配置。

从环境中读取配置

一个共同的要求是通过环境变量为程序提供配置。 因此,我们也来看看它。 有两种情况需要考虑:

  1. 从环境中读取配置
  2. 使用环境变量覆盖配置文件中的配置

在这两种情况下,我们都只需要设置环境变量,然后可以使用键简单地检索它。 但是,在当前的实现中,情况1和2之间的行为略有不同。 在第一种情况下,它将仅查找环境变量并返回其当前值 。 在第二种情况下,在解析配置时,它将在环境变量中查找键,如果存在此类变量,则将其值存储在config注册表中。 因此,此类覆盖的配置在运行时启动时将始终具有相应环境变量的值。

让我们举一个使用先前考虑的配置文件的修改版本的示例。 我们将覆盖httpPort配置并使用环境变量设置httpsPort配置。

在Linux中设置环境变量:

  $ export echo_httpPort = 8080 
$ export echo_httpsPort = 8085

请注意,在设置变量时以句号_代替时,如何使用配置的标准键。 现在,让我们运行它并验证是否正确应用了配置。

  $芭蕾舞演员运行-c echo2.conf echo_service.bal 
在“ echo_service.bal”中启动服务
[ballerina / http]已启动HTTPS / WSS端点0.0.0.0:8085
[ballerina / http]已启动HTTP / WS端点0.0.0.0:8080

现在,侦听器分别位于端口8080和8085上,而不是9090和9095上。