moai-lang-ruby

快速参考（30 秒）

Ruby 3.3+ 开发专家——Rails 7.2、ActiveRecord、Hotwire/Turbo、RSpec 和现代 Ruby 模式。

自动触发：扩展名为 .rb 的文件、Gemfile、Rakefile、config.ru，以及 Rails 或 Ruby 相关讨论

核心能力：

• Ruby 3.3 特性：YJIT 可用于生产环境、模式匹配、Data 类、无穷方法
• Web 框架：支持 Turbo、Stimulus 和 ActiveRecord 的 Rails 7.2
• 前端：Hotwire，包括 Turbo 和 Stimulus，可实现类似 SPA 的体验
• 测试：RSpec，支持工厂、请求规格和系统规格
• 后台任务：Sidekiq 和 ActiveJob
• 包管理：使用 Gemfile 的 Bundler
• 代码质量：带 Rails cops 的 RuboCop
• 数据库：ActiveRecord，支持迁移、关联和作用域

快速模式

Rails 控制器模式：

创建继承自 ApplicationController 的 UsersController。添加 before_action 调用 set_user，并仅用于 show、edit、update 和 destroy 操作。定义 index 方法，将 User.all 赋给实例变量。定义 create 方法，使用 user_params 创建新的 User。使用 respond_to 块：format.html 在成功时重定向，或以 unprocessable_entity 状态渲染 new；format.turbo_stream 用于 Turbo 响应。添加私有 set_user 方法，根据 params id 查找用户。添加 user_params 方法，要求提供 user，并允许传入 name 和 email。

ActiveRecord 模型模式：

创建继承自 ApplicationRecord 的 User 模型。定义 has_many 关联 posts，并设置 dependent destroy；定义 has_one 关联 profile，并设置 dependent destroy。添加 email 验证，要求其存在、唯一，并使用 URI::MailTo::EMAIL_REGEXP 验证格式。添加 name 验证，要求其存在且长度最少为 2、最多为 100。定义 active 作用域，筛选 active 为 true 的记录。定义 recent 作用域，按 created_at 降序排列。创建 full_name 方法，返回以空格连接并去除首尾空格后的 first_name 和 last_name。

RSpec 测试模式：

为 User 模型类型创建 RSpec.describe。在 describe validations 块中，添加针对 email 的 validate_presence_of 和 validate_uniqueness_of 断言。在 describe full_name 块中，使用 let 构建 first_name 为 John、last_name 为 Doe 的用户。添加 it 块，断言 user.full_name 等于 John Doe。

---

实现指南（5 分钟）

Ruby 3.3 新特性

YJIT 可用于生产环境：

Ruby 3.3 默认启用 YJIT，可使 Rails 应用的性能提升 15% 至 20%。运行带有 yjit 标志的 ruby，或将 RUBY_YJIT_ENABLE 环境变量设为 1，即可启用。调用 RubyVM::YJIT.enabled? 方法可检查状态。

使用 case/in 进行模式匹配：

创建一个接收 response 参数的 process_response 方法。使用 case 搭配 response 和 in 进行模式匹配。匹配 status 为 ok 的情况，并提取 data 变量，然后输出成功消息。匹配 status 为 error 的情况，并提取 msg 变量。使用 guard 条件匹配 status 为 pending 或 processing 的情况。使用 else 处理未知响应。

用于不可变结构体的 Data 类：

使用 Data.define 和 name、email 符号创建 User。添加代码块，定义返回包含 name 的问候语的 greeting 方法。使用关键字参数创建 User 实例。访问 name 属性并调用 greeting 方法。

无穷方法定义：

创建 Calculator 类，使用等号语法为单表达式方法定义 add、multiply 和 positive? 方法。

Rails 7.2 模式

Gemfile 中的应用设置：

将源设置为 rubygems.org。添加 Rails 版本约束 7.2、pg 版本 1.5、puma 版本 6.0 或更高版本、turbo-rails、stimulus-rails，以及 sidekiq 版本 7.0。在 development 和 test 组中添加 rspec-rails 版本 7.0、factory_bot_rails、faker，以及设置 require false 的 rubocop-rails。在 test 组中添加 capybara 和 shoulda-matchers。

包含 Concerns 的模型：

创建一个扩展 ActiveSupport::Concern 的 Sluggable 模块。在 included 块中添加 before_validation，在创建时调用 generate_slug，并添加 slug 的 presence 和 uniqueness 验证。定义返回 slug 的 to_param。添加私有的 generate_slug 方法：当 title 存在且 slug 为空时，将 slug 设置为参数化后的 title。创建包含 Sluggable 的 Post 模型，其中包含 belongs_to user、带 dependent destroy 的 has_many comments，以及 has_many_attached images。添加验证和 published 作用域。

服务对象模式：

创建 UserRegistrationService，其 initialize 接受 user_params。定义 call 方法来创建 User，并使用 ActiveRecord::Base.transaction 保存用户、创建个人资料和发送欢迎邮件。返回 success 为 true 且包含 user 的 Result。捕获 RecordInvalid，并返回 success 为 false 且包含 errors 的 Result。添加私有方法 create_profile 和 send_welcome_email。将 Result 定义为包含 success、user 和 errors 的 Data.define，并添加 success? 和 failure? 谓词方法。

Hotwire Turbo 和 Stimulus

Turbo Frames 模式：

在 index 视图中，使用带有 posts id 的 turbo_frame_tag，并遍历 posts 渲染每一项。在 post 局部视图中，使用带有 post 的 dom_id 的 turbo_frame_tag，其中包含一个 article，内有 h2 链接和截断内容的段落。

Turbo Streams 模式：

在控制器的 create 操作中，根据 current_user.posts 构建 post。使用 respond_to，其中包含 format.turbo_stream 和 format.html；根据保存是否成功进行重定向或渲染。在 create.turbo_stream.erb 视图中，使用 turbo_stream.prepend 添加包含 post 的内容，并使用 turbo_stream.update 更新 new_post 表单局部视图。

Stimulus 控制器模式：

在 JavaScript 控制器文件中，从 hotwired/stimulus 导入 Controller。导出一个默认类，该类扩展 Controller，并定义包含 input 和 submit 的 static targets 数组。定义 connect 方法并调用 validate。定义 validate 方法，检查所有 input targets 是否都有值，并据此设置 submit target 的 disabled 状态。

RSpec 测试基础

Factory Bot 模式：

在 factories 文件中，定义 user 工厂：使用 sequence 生成 email，使用 Faker::Name.name 生成 name，并将 password 设为 password123。添加将 role 设置为 admin 符号的 admin trait。添加 with_posts trait，其中 transient 的 posts_count 默认值为 3，并使用 after create 回调为用户创建 posts 列表。

---

高级实现（10 分钟以上）

如需全面了解以下内容：

• Docker 和 Kubernetes 的生产部署模式
• 高级 ActiveRecord 模式，包括多态、STI 和查询对象
• Action Cable 实时功能
• 性能优化技术
• 安全最佳实践
• CI/CD 集成模式
• 完整的 RSpec 测试模式

请参阅：

• modules/advanced-patterns.md，了解生产模式和高级功能
• modules/testing-patterns.md，了解完整的 RSpec 测试指南

---

Context7 库映射

• rails/rails：Ruby on Rails Web 框架
• rspec/rspec：RSpec 测试框架
• hotwired/turbo-rails：适用于 Rails 的 Turbo
• hotwired/stimulus-rails：适用于 Rails 的 Stimulus
• sidekiq/sidekiq：后台作业处理
• rubocop/rubocop：Ruby 风格指南检查
• thoughtbot/factory_bot：测试数据工厂

---

配合使用效果良好

• moai-domain-backend：REST API 和 Web 应用架构
• moai-domain-database：SQL 模式和 ActiveRecord 优化
• moai-workflow-testing：DDD 和测试策略
• moai-essentials-debug：AI 驱动的调试
• moai-foundation-quality：TRUST 5 质量原则

---

故障排除

常见问题：

Ruby 版本检查：

运行带有版本标志的 ruby，确保版本为 3.3 或更高。运行 ruby -e 命令并执行 puts RubyVM::YJIT.enabled?，检查 YJIT 状态。

Rails 版本检查：

运行带有版本标志的 rails，确保版本为 7.2 或更高。运行 bundle exec rails about 获取完整的环境信息。

数据库连接问题：

• 检查 config/database.yml 配置
• 确保 PostgreSQL 或 MySQL 服务正在运行
• 如果数据库不存在，运行 rails db:create

Asset Pipeline 问题：

运行 rails assets:precompile 编译资源。运行 rails assets:clobber 清除已编译的资源。

RSpec 设置问题：

首次设置时运行 rails generate rspec:install。运行 bundle exec rspec 并指定文件路径，执行单个规范测试。运行 bundle exec rspec 并指定 format documentation，获取详细输出。

Turbo 和 Stimulus 问题：

运行 rails javascript:install:esbuild 配置 JavaScript。运行 rails turbo:install 安装 Turbo。

---

最后更新：2026-01-11 状态：活跃（v1.1.0）