用途
该技能用于在编写 Ruby gem 时套用 Andrew Kane 的成熟模式与哲学。资料说明其适用场景为:创建新的 Ruby gem、重构已有 gem 等。其宣称依据来自 100 多个 gem、累计 374M+ 下载量的实践(列举项目包括 Searchkick、PgHero、Chartkick、Strong Migrations、Lockbox、Ahoy、Blazer、Groupdate、Neighbor、Blind Index)。
核心哲学
- 简洁优于取巧(Simplicity over cleverness)。
- 零依赖或最少依赖。
- 显式代码优于元编程。
- 提供 Rails 集成,但不与 Rails 耦合。
- 每个模式都服务于生产用例。
主要模式
入口文件结构
每个 gem 的 lib/gemname.rb 遵循固定结构:
- 依赖(优先标准库),如
require "forwardable"; - 内部模块,使用
require_relative; - 条件加载 Rails(关键:绝不直接 require Rails),写为
require_relative "gemname/railtie" if defined?(Rails); - 含配置与错误的模块,定义
Error、InvalidConfigError等错误类,并用class << self配合attr_accessor/attr_writer,同时立即设置默认值。
类宏 DSL 模式
资料称这是标志性的 Kane 模式:单次方法调用完成全部配置,例如 searchkick word_start: [:name]。实现要点包括:校验未知关键字并抛出 ArgumentError;用 Module.new 与 module_eval 定义方法(用 method_defined? 防止覆盖);通过 include mod 混入;用 class_eval、cattr_reader 与 class_variable_set 保存选项副本。
Rails 集成
必须使用 ActiveSupport.on_load,绝不直接 require Rails gem。资料给出对比:错误写法是 require "active_record" 后直接 include;正确写法是在 ActiveSupport.on_load(:active_record) 块中 extend GemName::Model。如需修改既有行为,应使用 prepend,例如对 ActiveRecord::Migration 进行 prepend。
配置模式
使用 class << self 配合 attr_accessor,而非专门的 Configuration 对象。资料示例中 attr_writer :master_key 与自定义 reader 结合,实现从环境变量惰性取值(@master_key ||= ENV["GEMNAME_MASTER_KEY"]),并在文件末尾设定默认值。
错误处理
采用简单继承层级并给出有信息量的消息:Error < StandardError,其下设 ConfigError、ValidationError。在初始化时尽早用 ArgumentError 校验参数(例如密钥长度必须为 32 字节)。
测试
仅使用 Minitest。test/test_helper.rb 中 require bundler/setup、Bundler.require(:default)、minitest/autorun、minitest/pride;测试类继承 Minitest::Test,使用 assert_equal 等断言。
gemspec
尽可能零运行时依赖。示例中设置名称、版本、required_ruby_version = ">= 3.1"、files 使用 Dir[...]、require_path = "lib",并明确不写 add_dependency,开发依赖放在 Gemfile 中。
应避免的反模式
资料列出的反面做法包括:method_missing(应改用 define_method)、配置对象(应改用类访问器)、@@class_variables(应改用 class << self)、直接 require Rails gem、大量运行时依赖、在 gem 中提交 Gemfile.lock、使用 RSpec(应使用 Minitest)、重量级 DSL(应优先显式 Ruby)。
参考文件
资料提到以下更深入的参考文件:references/module-organization.md(目录布局、方法拆分)、references/rails-integration.md(Railtie、Engine、on_load 模式)、references/database-adapters.md(多数据库支持模式)、references/testing-patterns.md(多版本测试、CI 配置)、references/resources.md(Kane 的仓库与文章链接)。
限制
资料未提供该技能的安装方式、运行平台要求、收费或价格信息、具体的授权许可,也未说明其与其它工具的兼容性细节;这些内容暂未提供。上述模式与代码示例均来自资料原文,具体使用效果未在资料中给出验证数据。