SuperAPI AI 工具集

andrew-kane-gem-writer

编程与开发

查看项目

更新于 10-16 04:24

技能介绍

用途

该技能用于在编写 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 遵循固定结构:

  1. 依赖(优先标准库),如 require "forwardable";
  2. 内部模块,使用 require_relative;
  3. 条件加载 Rails(关键:绝不直接 require Rails),写为 require_relative "gemname/railtie" if defined?(Rails);
  4. 含配置与错误的模块,定义 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 的仓库与文章链接)。

限制

资料未提供该技能的安装方式、运行平台要求、收费或价格信息、具体的授权许可,也未说明其与其它工具的兼容性细节;这些内容暂未提供。上述模式与代码示例均来自资料原文,具体使用效果未在资料中给出验证数据。