config

config

概括

config可帮助您以简单可用的方式轻松管理特定环境设置。

特征

• 简单的yaml config文件
• config文件支持ERB
• config文件支持继承和多个环境
• 通过方便的对象成员表示法访问config信息
• 支持多级设置（ Settings.group.subgroup.setting ）
• 委托代码时忽略了本地开发人员设置

兼容性

当前版本支持并对以下解释器和框架进行了测试：

• 口译员
  • Ruby >= 2.6
  • jruby >= 9.2
  • Truffleruby >= 19.3
• 应用框架
  • 导轨>= 5.2
  • 帕德里诺
  • 辛纳屈

对于Ruby 2.0至2.3或Rails 3至4.1使用此宝石的1.x版本。对于较旧版本的导轨或Ruby使用应用程序config 。

对于Ruby 2.4或2.5或Rails 4.2或5.1 5.0此宝石的3.x版本。

安装

安装在导轨上

将gem ' config '添加到您的Gemfile并运行bundle install以安装它。然后运行

 rails g config :install

将生成自定义的config文件config /initializers/ config .rb和默认设置文件集：

config/settings.yml
config /settings.local.yml
config /settings/development.yml
config /settings/production.yml
config /settings/test.yml\”>

 config /settings.yml
config /settings.local.yml
config /settings/development.yml
config /settings/production.yml
config /settings/test.yml

您现在可以编辑它们以适应您的需求。

注意：默认情况下， config环境将与Rails环境（ Rails.env ）匹配。可以通过设置config .environment来更改。

安装在Padrino上

将宝石添加到您的Gemfile并运行bundle install以安装它。然后编辑app.rb并注册config

 register config

安装在Sinatra上

将宝石添加到您的Gemfile并运行bundle install以安装它。之后，需要在您的应用中注册config并将其赋予根，以便它可以找到config文件。

 set :root , File . dirname ( __FILE__ )
register config

安装其他红宝石项目

将宝石添加到您的Gemfile并运行bundle install以安装它。然后在您的config ure块中手动初始化config 。

config .setting_files("/path/to/ config _root", "your_project_environment"))\”>

 config . load_and_set_settings ( config . setting_files ( \"/path/to/ config _root\" , \"your_project_environment\" ) )

如果您只想给出一些YML路径以从您的config块中手动初始化config 。

 config . load_and_set_settings ( \"/path/to/yaml1\" , \"/path/to/yaml2\" , ... ) 

访问设置对象

安装GEM后， Settings对象将在全球上可用，默认情况下将从下面列出的文件中编译。在列表中较低的文件中定义的设置更高。

config/settings.yml
config /settings/#{environment}.yml
config /environments/#{environment}.yml

config /settings.local.yml
config /settings/#{environment}.local.yml
config /environments/#{environment}.local.yml\”>

 config /settings.yml
config /settings/#{environment}.yml
config /environments/#{environment}.yml

config /settings.local.yml
config /settings/#{environment}.local.yml
config /environments/#{environment}.local.yml

可以通过对象成员表示法访问条目：

 Settings . my_ config _entry

支持嵌套条目：

 Settings . my_section . some_entry

另外，如果您不知道需要提前访问的确切设置，也可以使用[]操作员。

 # All the following are equivalent to Settings.my_section.some_entry
Settings . my_section [ :some_entry ]
Settings . my_section [ \'some_entry\' ]
Settings [ :my_section ] [ :some_entry ]

重新加载设置

您可以随时通过运行Settings.reload! 。

重新加载设置和config文件

您还可以在运行时从不同的config文件重新加载Settings对象。

例如，在测试中，如果要测试生产设置，则可以：

config", "settings.yml").to_s,
Rails.root.join(" config ", "settings", "#{Rails.env}.yml").to_s,
Rails.root.join(" config ", "environments", "#{Rails.env}.yml").to_s
)\”>

 Rails . env = \"production\"
Settings . reload_from_files (
  Rails . root . join ( \" config \" , \"settings.yml\" ) . to_s ,
  Rails . root . join ( \" config \" , \"settings\" , \" #{ Rails . env } .yml\" ) . to_s ,
  Rails . root . join ( \" config \" , \"environments\" , \" #{ Rails . env } .yml\" ) . to_s
)

环境特定的config文件

您可以具有特定环境的config文件。特定环境config条目优先于公共config条目。

示例开发环境config文件：

 #{Rails.root}/ config /environments/development.yml

示例生产环境config文件：

 #{Rails.root}/ config /environments/production.yml

额外的来源

您可以在初始化期间加载额外的来源，通过设置extra_sources config uration选项。

config |
config .extra_sources = [
\’path/to/extra_source.yml\’, # String: loads extra_source.yml
{ api_key: ENV[\’API_KEY\’] }, # Hash: direct hash source
MyCustomSource.new, # Object: custom source object that responds to `load`
]
end\”>

 config . setup do | config |
  config . extra_sources = [
    \'path/to/extra_source.yml\' ,          # String: loads extra_source.yml
    { api_key : ENV [ \'API_KEY\' ] } ,         # Hash: direct hash source
    MyCustomSource . new ,                  # Object: custom source object that responds to `load`
  ]
end

这也将覆盖主文件中相同的config条目。

开发人员特定的config文件

如果您想具有特定于计算机或开发环境的本地设置，则可以使用以下文件，这些文件自动是.gitignore ：

config", "settings.local.yml").to_s,
Rails.root.join(" config ", "settings", "#{Rails.env}.local.yml").to_s,
Rails.root.join(" config ", "environments", "#{Rails.env}.local.yml").to_s\”>

 Rails . root . join ( \" config \" , \"settings.local.yml\" ) . to_s ,
Rails . root . join ( \" config \" , \"settings\" , \" #{ Rails . env } .local.yml\" ) . to_s ,
Rails . root . join ( \" config \" , \"environments\" , \" #{ Rails . env } .local.yml\" ) . to_s

注意： file settings.local.yml不会加载在测试中，以防止本地config引起片状或非确定性测试。环境特定文件（例如settings/test.local.yml ）仍将加载以允许特定于测试的凭据。

在运行时添加资源

您可以在运行时添加新的YAML config文件。只是使用：

 Settings . add_source! ( \"/path/to/source.yml\" )
Settings . reload!

这将使用给定的源文件，并使用其设置来覆盖任何以前的文件。

另一方面，您可以将YML文件预先列入config文件列表：

 Settings . prepend_source! ( \"/path/to/source.yml\" )
Settings . reload!

这将与add_source相同，但是给定的YML文件将首先加载（而不是上一个），其设置将被任何其他config文件覆盖。如果要定义默认值，这特别有用。

我喜欢为Rails项目做的一件事是提供一个local.yml config文件。然后，我在config /initializers/add_local_ config .rb中创建一个新的initializer

config/settings/local.yml")
Settings.reload!\”>

 Settings . add_source! ( \" #{ Rails . root } / config /settings/local.yml\" )
Settings . reload!

注意：这是一个示例用法，只需使用默认的本地文件settings.local.yml ， settings/#{Rails.env}.local.yml和environments/#{Rails.env}.local.yml用于您的开发人员特定的设置。

您还可以选择添加RAW HASH作为来源。一种用例可能是将设置存储在数据库或覆盖YML文件中内容的环境变量中。

 Settings . add_source! ( { some_secret : ENV [ \'some_secret\' ] } )
Settings . reload!

您可以通过hash来prepend_source!也是如此。

嵌入红宝石（ERB）

在YAML config文件中允许嵌入Ruby。默认情况下，将在加载时间对ERB进行评估，并且当evaluate_erb_in_yaml config设置为true 。

考虑以下两个config文件。

• #{Rails.root}/ config /settings.yml

 size : 1
server : google.com

• #{Rails.root}/ config /environments/development.yml

 size : 2
computed : <%= 1 + 2 + 3 %>
section :
  size : 3
  servers : [ {name: yahoo.com}, {name: amazon.com} ]

请注意，环境特定的config条目覆盖了共同条目。

 Settings . size   # => 2
Settings . server # => google.com

注意嵌入式红宝石。

 Settings . computed # => 6

请注意，即使在嵌套条目中也保持对象成员表示法。

 Settings . section . size # => 3

注意数组表示法和对象成员表示法。

 Settings . section . servers [ 0 ] . name # => yahoo.com
Settings . section . servers [ 1 ] . name # => amazon.com 

config

有多个可用的config选项，但是您只能在应用程序初始化阶段进行config定义一次：

config |
config .const_name = \’Settings\’
# …
end\”>

 config . setup do | config |
  config . const_name = \'Settings\'
  # ...
end

在Rails中安装config后，您会发现自动生成的文件，其中包含位于config /initializers/ config .rb的默认config URATION。

一般的

• const_name持有设置的对象的名称。默认： 'Settings'
• evaluate_erb_in_yaml在YAML config文件中评估ERB。设置为False，如果config文件包含不应在加载时评估的ERB。默认值： true
• file_name文件的名称存储在所有环境中访问的通用密钥。默认值： 'settings' – 位于config /settings.yml上
• dir_name目录的名称存储特定于环境的文件。默认值： 'settings' – 位于config /settings/

合并定制

• overwrite_arrays在先前加载的设置文件中找到的覆盖阵列。默认值： true
• merge_hash_arrays从先前加载的设置文件中的数组内部的合并哈希。只有当overwrite_arrays = false时才有意义。默认值： false
• knockout_prefix能够删除在较早加载的设置文件中设置的数组的元素。只有当overwrite_arrays = false时才有意义，否则数组设置将被默认情况下覆盖。默认值： nil
• merge_nil_values合并config s时， nil值将覆盖现有值。默认值： true 。

config ::Options size=2, …>
c.size # => 2
c.merge!(size: nil) => #< config ::Options size=nil, …>
c.size # => nil\”>

 # merge_nil_values is true by default
c = config . load_files ( \"./spec/fixtures/development.yml\" ) # => #< config ::Options size=2, ...>
c . size # => 2
c . merge! ( size : nil ) => #< config ::Options size=nil, ...>
c . size # => nil 

config |
config .merge_nil_values = false
end

c = config .load_files("./spec/fixtures/development.yml") # => #< config ::Options size=2, …>
c.size # => 2
c.merge!(size: nil) => #< config ::Options size=nil, …>
c.size # => 2\”>

 # To reject nil values when merging settings:
config . setup do | config |
  config . merge_nil_values = false
end

c = config . load_files ( \"./spec/fixtures/development.yml\" ) # => #< config ::Options size=2, ...>
c . size # => 2
c . merge! ( size : nil ) => #< config ::Options size=nil, ...>
c . size # => 2

检查深入合并以获取更多详细信息。

验证

使用Ruby 2.1或更新的情况，您可以选择使用Dry -Rb来定义架构或合同（在config -2.1中添加）以验证特定config值的存在（和类型）。一般而言，合同允许描述更复杂的验证，并在字段之间使用下降。

如果您提供验证选项（或两者），则将自动用于验证您的config 。如果验证失败，它将引起config ::Validation::Error其中包含有关模式和您的config之间所有不匹配的信息。

下面的两个示例均展示了如何确保config具有可选的email和youtube结构，并填充了api_key字段。合同添加了附加规则。

合同

利用干燥验证，您可以使用参数模式和规则创建合同：

configContract < Dry::Validation::Contract
params do
optional(:email).maybe(:str?)

required(:youtube).schema do
required(:api_key).filled
end
end

rule(:email) do
unless /\\A[\\w+\\-.]+@[a-z\\d\\-]+(\\.[a-z\\d\\-]+)*\\.[a-z]+\\z/i.match?(value)
key.failure(\’has invalid format\’)
end
end
end

config .setup do | config |
config .validation_contract = config Contract.new
end\”>

 class config Contract < Dry :: Validation :: Contract
  params do
    optional ( :email ) . maybe ( :str? )

    required ( :youtube ) . schema do
      required ( :api_key ) . filled
    end
  end

  rule ( :email ) do
    unless / \\A [ \\w + \\- .]+@[a-z \\d \\- ]+( \\. [a-z \\d \\- ]+)* \\. [a-z]+ \\z /i . match? ( value )
      key . failure ( \'has invalid format\' )
    end
  end
end

config . setup do | config |
  config . validation_contract = config Contract . new
end

上面的示例添加了一个规则，以确保email通过将其与所提供的正则表达式匹配。

检查干燥验证以获取更多详细信息。

模式

您也可以使用干式式指定模式：

config |
# …
config .schema do
optional(:email).maybe(:str?)

required(:youtube).schema do
required(:api_key).filled
end
end
end\”>

 config . setup do | config |
  # ...
  config . schema do
    optional ( :email ) . maybe ( :str? )

    required ( :youtube ) . schema do
      required ( :api_key ) . filled
    end
  end
end

检查Dry-Schema以获取更多详细信息。

缺少钥匙

对于示例设置文件：

 size : 1
server : google.com

您可以使用key?及其别名has_key? ：

 Settings . key? ( :path )
# => false
Settings . key? ( :server )
# => true

默认情况下，访问丢失的密钥返回nil ：

 Settings . key? ( :path )
# => false
Settings . path
# => nil

这不是“错字安全”。要解决此问题，您可以config fail_on_missing选项：

config |
config .fail_on_missing = true
# …
end\”>

 config . setup do | config |
  config . fail_on_missing = true
  # ...
end

因此，在访问不存在的密钥时（类似于Hash#fetch行为），它将提出一个KeyError ：

 Settings . path
# => raises KeyError: key not found: :path

环境变量

有关更多详细信息，请参见下面的部分。

使用环境变量

要加载来自ENV对象的环境变量，该变量将覆盖文件中定义的任何设置，请将use_env设置为config /initializers/ config .rb文件中的true：

config |
config .const_name = \’Settings\’
config .use_env = true
end\”>

 config . setup do | config |
  config . const_name = \'Settings\'
  config . use_env = true
end

现在， config将从Env对象读取值到设置。对于上面的示例，它将寻找从Settings开始的键：

 ENV [ \'Settings.section.size\' ] = 1
ENV [ \'Settings.section.server\' ] = \'google.com\'

不过，它与数组无法使用。

使用环境变量同时为键分配“扁平”值和多级值。

 # Raises an error when settings are loaded
ENV [ \'BACKEND_DATABASE\' ] = \'development\'
ENV [ \'BACKEND_DATABASE_USER\' ] = \'postgres\'

相反，在环境变量名称中指定相等深度的键：

 ENV [ \'BACKEND_DATABASE_NAME\' ] = \'development\'
ENV [ \'BACKEND_DATABASE_USER\' ] = \'postgres\'

与Heroku合作

Heroku使用Env Object存储敏感设置。您无法将此类文件上传到Heroku，因为它的短暂文件系统会从每个实例刷新的git源中重新创建。与Heroku一起使用config只是将use_env var设置为true ，如上所述。

要将您的本地值上传到Heroku，您可以运行bundle exec rake config :heroku 。

微调

您可以自定义环境变量处理方式：

• env_prefix （默认值： const_name ） – 仅加载Env变量以此前缀开头（case -simentive）
• env_separator （默认值： '.' ） – 用作级别分离器的字符串 – 默认值的默认值.与Heroku合作良好，但是您可能需要将其更改为__的简易覆盖设置，其中可能不允许使用可变名称中的点（例如，bash）
• env_converter （默认值:downcase ） – 如何处理变量名称：
  • nil – 没有改变
  • :downcase – 转换为较低的外壳
• env_parse_values （默认值： true ） – 尝试将值解析为正确的类型（ Boolean ， Integer ， Float ， String ）

例如，给定以下环境：

SETTINGS__SECTION__SERVER_SIZE=1
SETTINGS__SECTION__SERVER=google.com
SETTINGS__SECTION__SSL_ENABLED=false

以及以下config量：

config |
config .use_env = true
config .env_prefix = \’SETTINGS\’
config .env_separator = \’__\’
config .env_converter = :downcase
config .env_parse_values = true
end\”>

 config . setup do | config |
  config . use_env = true
  config . env_prefix = \'SETTINGS\'
  config . env_separator = \'__\'
  config . env_converter = :downcase
  config . env_parse_values = true
end

以下设置将可用：

 Settings . section . server_size # => 1
Settings . section . server # => \'google.com\'
Settings . section . ssl_enabled # => false

与AWS Secrets Manager合作

可以通过使用config ::Sources::EnvSource来解析存储在AWS Secrets Manager秘密中的变量。

例如，明文秘密看起来像这样：

{
  \"Settings.foo\" : \" hello \" ,
  \"Settings.bar\" : \" world \" ,
}

为了加载这些设置，请从AWS Secrets Manager获取设置，将其授予JSON，将结果的Hash传递到新的EnvSource中，加载新来源和重新加载。

config
secret_source = config ::Sources::EnvSource.new(secrets)
Settings.add_source!(secret_source)
Settings.reload!\”>

 # fetch secrets from AWS
client = Aws :: SecretsManager :: Client . new
response = client . get_secret_value ( secret_id : \" #{ ENV [ \'ENVIRONMENT\' ] } /my_application\" )
secrets = JSON . parse ( response . secret_string )

# load secrets into config
secret_source = config :: Sources :: EnvSource . new ( secrets )
Settings . add_source! ( secret_source )
Settings . reload!

在这种情况下，将可用以下设置：

 Settings . foo # => \"hello\"
Settings . bar # => \"world\"

默认情况下， EnvSource将使用env_prefix ， env_separator ， env_converter和env_parse_values使用config URATION，但是这些中的任何一个都可以在构造函数中覆盖。

config::Sources::EnvSource.new(secrets,
prefix: \’My config \’,
separator: \’__\’,
converter: nil,
parse_values: false)\”>

 secret_source = config :: Sources :: EnvSource . new ( secrets ,
                                               prefix : \'My config \' ,
                                               separator : \'__\' ,
                                               converter : nil ,
                                               parse_values : false ) 

贡献

欢迎您的帮助。请遵循我们的贡献指南

据了解，以任何形式，过去或将来提供的所有捐款都完全同意并接受MIT许可证。

运行规格

设置

bundle install
bundle exec appraisal install

列表定义的评估：

bundle exec appraisal list

运行特定评估规格：

bundle exec appraisal rails-6.1 rspec

所有评估的运行规格：

bundle exec appraisal rspec

作者

• piotr kuczynski
• 弗雷德·吴
• 雅克·克罗克（Jacques Crocker）
• Christopher J. Bottaro从App config继承

贡献者

代码贡献者

该项目的存在得要归功于所有贡献的人，您非常欢迎您提供帮助。请遵循我们的贡献指南。

据了解，以任何形式，过去或将来提供的所有捐款都完全同意和接受MIT许可。

财务贡献者

成为支持者，并通过每月少量捐款来支持我们，以帮助我们继续我们的活动。谢谢你，如果你已经一个了！

赞助商

通过成为赞助商来支持这个项目。您的徽标将在此处显示您网站的链接。

执照

版权（C）Piotr Kuczynski。根据MIT许可发布。