anyway-config-coder

Anyway 配置编码器

切勿直接使用 ENV 或 Rails 凭据。 将所有配置封装在类型化的 anyway_config 类中。

# WRONG
api_key = ENV["GEMINI_API_KEY"]

# RIGHT
class GeminiConfig < Anyway::Config
  attr_config :api_key, timeout: 30
  required :api_key
end
GeminiConfig.new.api_key

配置类模式

# config/configs/gemini_config.rb
class GeminiConfig < Anyway::Config
  attr_config :api_key, model: "gemini-pro", timeout: 30, max_retries: 3
  required :api_key

  def configured? = api_key.present?
end

ENV 自动映射：GeminiConfig -> GEMINI_API_KEY、GEMINI_MODEL 等。使用 config_name :payment 覆盖前缀。

嵌套配置使用哈希默认值，并通过点号表示法访问：AppConfig.new.database.host。

单例模式（推荐）

class GeminiConfig < Anyway::Config
  attr_config :api_key, :model

  class << self
    def instance = @instance ||= new
  end
end

GeminiConfig.instance.api_key

目录结构

config/
├── configs/          # Ruby config classes
│   ├── gemini_config.rb
│   └── stripe_config.rb
└── settings/         # YAML overrides (optional)
    └── gemini.yml

YAML 文件使用 default: &default，并通过环境特定的配置覆盖（development:、test:、production:）。

验证

class StorageConfig < Anyway::Config
  attr_config :bucket, :region, :access_key_id, :secret_access_key
  required :bucket, :region
  required :access_key_id, :secret_access_key, env: :production  # Conditional

  def validate!
    super
    raise_validation_error("Invalid region") unless %w[us-east-1 us-west-2 eu-west-1].include?(region)
  end
end

类型强制转换

class ApiConfig < Anyway::Config
  # Automatic coercion
  attr_config timeout: 30       # Integer
  attr_config enabled: true     # Boolean
  attr_config rate: 1.5         # Float

  # Coerce arrays from comma-separated strings
  coerce_types allowed_origins: {
    type: :string,
    array: true
  }
  # ALLOWED_ORIGINS="example.com,other.com" => ["example.com", "other.com"]
end

测试配置

测试默认值、必填项验证和计算方法。使用 with_env 在测试中覆盖配置：

RSpec.describe GeminiConfig do
  it "requires api_key" do
    expect { described_class.new(api_key: nil) }.to raise_error(Anyway::Config::ValidationError)
  end
end

# spec/support/anyway_config.rb - global override
RSpec.configure do |config|
  config.around(:each) do |example|
    with_env("GEMINI_API_KEY" => "test-key") { example.run }
  end
end

常见模式

API 客户端配置

添加 client_options 辅助方法来构建连接哈希：

class OpenAIConfig < Anyway::Config
  attr_config :api_key, :organization_id, model: "gpt-4", max_tokens: 1000
  required :api_key

  def client_options = { access_token: api_key, organization_id: }.compact
end

多提供商配置

使用谓词方法和 case 处理特定提供商的选项：

class StorageConfig < Anyway::Config
  attr_config provider: "local", bucket: nil, endpoint: nil

  def s3? = provider == "s3"
  def local? = provider == "local"
  def service_options = case provider when "s3" then s3_options else local_options end
end

反模式

反模式	问题	解决方案
直接使用 ENV["KEY"]	没有类型安全，配置分散	配置类
到处使用 ENV.fetch	重复，没有验证	集中式配置
Rails 凭据	复杂，难以测试	anyway_config 类
硬编码密钥	安全风险	环境变量
魔法字符串	容易拼写错误，IDE 不支持	配置常量

详细参考

• references/advanced-patterns.md - 动态配置、回调、继承