Anyway Config 是 Rails 应用的配置管理方案。核心原则是:配置类是唯一知道某个值来自哪里的代码,应用代码依赖配置对象,不直接读取 ENV、credentials 或 YAML,也不依据 Rails.env 分支。本文档给出的是一套决策流程,细节分散在 references/organizing.md(类的位置、来源、启动集成、示例)、references/testing.md(如何测试配置类及使用它的代码)和 references/docs.md(README 章节地图);API 以 README 或 gem 源码(bundle info anyway_config --path)为准,不要猜测。
一、先查看项目现状。找到已有的配置:config/configs/、app/configs/,以及放在服务代码旁的 /config.rb。读 ApplicationConfig(多数应用把它做成单例,如 AppConfig.host)。读 config/application.rb 中的 config.anyway_config. 配置行,注意 autoload_static_config_path、default_environmental_key 和 enforce_config_schema。读 .gitignore,确认 config/.local.yml 和 config/credentials/local. 已被忽略。遵循项目既有约定;如果 gem 尚未初始化,运行 bin/rails g anyway:install。
二、决定新值放在哪里。先判断它是否是配置参数(会随部署或环境变化):不是则用代码常量;是则继续判断。若它是 Rails 或某个工具自身读取的基础设施项(PORT、RAILS_MAX_THREADS、DATABASE_URL、RAILS_LOG_LEVEL),保留在工具期望的位置(puma.rb、database.yml)。若已有配置类负责同一关注点(同一服务、同一子系统),给它添加属性;否则新建配置类。参数按关注点分组:每个集成或子系统一个类(StripeConfig、SMTPConfig、FlyDeploy::Config),不要一个参数一个类,也不要把所有东西塞进 AppConfig;AppConfig 只放应用级值,如 host、port、asset host、全局开关。
三、创建配置类并选择位置。启动时使用(config/application.rb、initializers、routes、puma.rb)或应用级的值放在 config/configs/<name>config.rb(静态,开发环境不重载);仅由一个模块、服务或 pack 使用的值放在该代码旁,如 app/services/fly_deploy/config.rb,此时需显式设置 config_name,且在自动加载前不可用;仅在运行时使用、且项目把这类配置放在 app/configs/ 的值放在 app/configs/<name>config.rb(开发环境会重载)。可用 bin/rails g anyway:config <name> param1 param2 生成类,加 --app 生成到 app/configs/。就地定义的类需手写,文档给出了示例:在模块内继承 ApplicationConfig,用 config_name 指定名称(否则名称是去掉下划线的形式,如 "flydeploy"),用 attr_config 声明属性和默认值,用 required 标记必填(可带 env: 限定环境),并可在类上定义方法。配置名决定所有来源的键:config/fly_deploy.yml、credentials.fly_deploy 以及 FLY_DEPLOY* 环境变量。如果 gem 或工具已占用该名称(例如 Litestream 读取 LITESTREAM*),换一个名称。
四、为每个值选择来源。非机密、各处相同的默认值用 attr_config name: default;非机密、随环境不同的值用 config/<name>.yml 的按环境键;开发与测试用的假值放在 YAML 的 development: / test: 键;机密(API key、密码、签名密钥)放在 Rails credentials 的 <name>: 下,或由部署平台提供 ENV <NAME>_<ATTR>;个人开发者覆盖放在 config/<name>.local.yml 或 config/credentials/local.yml.enc(被 git 忽略);运维无需部署即可修改的值用环境变量。加载优先级由低到高为:属性默认值 → YAML(含 .local.yml)→ credentials → ENV → 显式 Config.new(key: value)。不要在 YAML 中写 <%= ENV["STRIPE_API_KEY"] %>,ENV 加载器已自动把 STRIPE_API_KEY 映射到 StripeConfig#api_key。
五、编写属性。为每个有安全值的属性给默认值;布尔默认值会额外生成 ? 谓词方法。用 required 标记必填值,并可用 env: 限定(如 env: :production、env: {except: %i[development test]})。当 ENV 需要产生数组或必须保持字符串时,用 coerce_types(如 {type: :string, array: true})。逻辑放在配置类上,而不是调用方:配置是否完整的谓词、派生值(用 super 获取原值再计算)、为库准备的适配方法。属性用途或格式不明显时加注释。避免保留名称(values、to_h、clear、config_name 等);使用单例 ApplicationConfig 时还要避开类方法名。若项目用 RBS 做类型检查(sig/、Steepfile),为新配置添加签名,MyConfig.to_rbs 可基于 attr_config、coerce_types 和 required 生成。
六、使用配置。应用代码通过配置类读取,如 StripeConfig.secret_key、AppConfig.analytics_enabled?。当某个类依赖配置时,把它作为默认参数传入,测试可注入其他实例。集成是否启用由配置是否存在决定,而不是由环境决定(如 if GithubConfig.oauth_configured?)。在 config/application.rb 和 initializers 中用配置来配置 Rails 和 gem。对只读 ENV 的 gem,可在其 initializer 中复制一次值。
七、替换直接读取。文档列出常见替换:应用代码中的 ENV["FOO_API_KEY"] 改为 FooConfig.api_key;ENV.fetch("FOO_ENABLED", "false") == "true" 改为布尔属性加谓词;Rails.application.credentials.foo[:key] 改为 FooConfig.key;Rails.application.config_for(:foo) 改为 FooConfig;用 Rails.env.production? 选值改为按环境 YAML 值;用 Rails.env.production? 开关功能改为布尔属性或 configured? 谓词;ENV["X"] || "default" 改为带默认值的属性。涉及框架本身的环境判断(如仅测试用的视图辅助方法)应保留。
八、测试。测试值放在 config/<name>.yml 的 test: 段,CI 无需机密。用 described_class.new(key: value) 和 with_env 对配置类做单元测试;对使用配置的代码,注入配置实例或 stub 单例方法。不要在测试中直接设置 ENV。
九、排查取值错误。不要猜,而是让配置报告值的来源:bin/rails runner 'pp StripeConfig.new',或用 to_source_trace 得到哈希。使用 .new,因为单例保留进程启动时加载的值。输出会以明文显示机密,不要复制到提交、issue 或报告中。若追踪仍解释不了取值,按顺序检查:优先级(高优先级来源会掩盖低优先级改动,陈旧的 ENV 变量会隐藏 YAML 修改);名称(env_prefix 与 config_name,未设 config_name 的 FlyDeploy::Config 会读 FLYDEPLOY_* 和 config/flydeploy.yml);环境(带环境键的 YAML 需要当前 Rails.env 的段,本地文件仅在开发环境加载);拼写(YAML 或 credentials 中拼错的键会被静默忽略,可开启 enforce_config_schema 在未知键时报错);类型(ENV 值会自动转换,如 "0123" → 123,追踪显示原始字符串而读取返回转换后的值,可用 coerce_types key: :string 修正)。
十、gem 功能概览:attr_config、required、on_load、coerce_types 用于模式、校验与类型;本地文件用于个人开发覆盖;enforce_config_schema(2.9+)对未知键报错或警告;来源追踪用于定位取值来源;生成器创建基类和配置类;with_env 测试辅助在块内设置 ENV 并重置 Anyway 的 ENV 缓存;Doppler、EJSON 和自定义加载器提供更多来源(ENV 始终是最后的加载器);Anyway::Config.for(:name) 可在没有类的情况下读取配置(建议优先用类);to_rbs 与内置签名用于 RBS/Steep 类型检查;OptionParser 集成可从配置构建 CLI 选项(纯 Ruby 工具)。
十一、禁止事项:不要在配置类之外读取 ENV 或 credentials(基础设施项除外);不要把机密提交到 config/<name>.yml(开发测试假值可以);不要为已被其他配置覆盖的单个值新增配置类;不要在运行时修改配置来改变行为,应传入新实例;不要在启动时引用 app/configs/ 或就地定义的配置类,应移到 config/configs/;当 YAML 值足以表达差异时,不要给配置方法加按环境分支的 if。
十二、完成后的报告:列出新增或修改的每个配置类及其位置;每个新参数及其来源(YAML、credentials、ENV)和对应的 ENV 变量名;部署前运维必须设置的值(新增的必填机密);以及删除的直接 ENV、credentials、Rails.env 读取。