Settingslogic 技术文档

1. 安装指南

安装方式

Settingslogic 是一个简单的配置/设置解决方案，使用 ERB 启用的 YAML 文件。它适用于 Rails、Sinatra 或任何 Ruby 项目。

要安装 Settingslogic，请在终端中运行以下命令：

gem install settingslogic

2. 项目的使用说明

1. 定义你的类

首先，你需要在你的应用程序中创建一个类来定义设置。你可以将这个类命名为 Settings、Config 或其他你喜欢的名称。以下是一个示例：

class Settings < Settingslogic
  source "#{Rails.root}/config/application.yml"
  namespace Rails.env
end

这个类定义了一个 Settings 类，它从 config/application.yml 文件中加载配置，并根据当前环境（如 development、test、production）使用命名空间。

2. 创建你的设置

接下来，你需要创建一个 YAML 文件来存储你的设置。在上面的示例中，我们指定了 config/application.yml 文件。这个文件的结构如下：

defaults: &defaults
  cool:
    saweet: nested settings
  neat_setting: 24
  awesome_setting: <%= "Did you know 5 + 5 = #{5 + 5}?" %>

development:
  <<: *defaults
  neat_setting: 800

test:
  <<: *defaults

production:
  <<: *defaults

在这个文件中，defaults 部分定义了默认设置，而 development、test 和 production 部分则根据环境覆盖了某些设置。

3. 访问你的设置

你可以通过类名 Settings 来访问这些设置。例如：

>> Rails.env
=> "development"

>> Settings.cool
=> "#<Settingslogic::Settings ... >"

>> Settings.cool.saweet
=> "nested settings"

>> Settings.neat_setting
=> 800

>> Settings.awesome_setting
=> "Did you know 5 + 5 = 10?"

你可以在任何地方使用这些设置，例如在模型中：

class Post < ActiveRecord::Base
  self.per_page = Settings.pagination.posts_per_page
end

4. 可选/动态设置

有时，你可能希望在应用程序逻辑中处理默认值，以减少 YAML 文件中的设置数量。你可以通过哈希符号访问可选设置：

>> Settings.messaging.queue_name
=> Exception: Missing setting 'queue_name' in 'message' section in 'application.yml'

>> Settings.messaging['queue_name']
=> nil

>> Settings.messaging['queue_name'] ||= 'user_mail'
=> "user_mail"

>> Settings.messaging.queue_name
=> "user_mail"

在模型中使用时：

class Post < ActiveRecord::Base
  self.per_page = Settings.posts['per_page'] || Settings.pagination.per_page
end

5. 条件性抑制异常

在生产环境中，你可能希望抑制由于缺少设置而引发的异常，并返回 nil。你可以在 Settings 类中添加 suppress_errors 方法来实现这一点：

class Settings < Settingslogic
  source "#{Rails.root}/config/application.yml"
  namespace Rails.env
  suppress_errors Rails.env.production?
end

>> Settings.non_existent_key
=> nil

3. 项目API使用文档

1. Settingslogic 类

• source(path): 指定配置文件的路径。
• namespace(env): 指定环境命名空间。
• suppress_errors(condition): 根据条件抑制异常。
• load!: 强制加载设置。
• reload!: 重新加载设置。

2. 访问设置

• Settings.setting_name: 访问设置。
• Settings.setting_name ||= default_value: 设置默认值。

4. 项目安装方式

通过以下命令安装 Settingslogic：

gem install settingslogic

安装完成后，你可以在你的 Ruby 项目中使用它来管理配置。