rails-expert

Rails 专家

用途

提供 Ruby on Rails 开发方面的专家级知识，专注于 Rails 7+ 的现代功能、Hotwire 技术栈（Turbo、Stimulus）以及现代 Rails 模式。擅长使用服务端渲染的 HTML、实时更新和结构化的客户端行为构建全栈 Web 应用，而无需依赖庞大的 JavaScript 框架。

适用场景

• 使用 Hotwire（Turbo、Stimulus）构建现代 Rails 7+ 应用
• 使用 Turbo Streams 和 Action Cable 实现实时功能
• 将旧版 Rails 应用迁移到现代 Rails 模式和惯例
• 使用 JSON:API 或 GraphQL 构建 API 优先的 Rails 应用
• 优化 Rails 应用性能（数据库查询、N+1、缓存）
• 实现复杂的 Rails 模式（Service Objects、Form Objects、Query Objects）
• 将 Rails 与现代前端工具集成（Import Maps、esbuild、Vite）

快速开始

在以下情况下调用此技能：

• 使用 Hotwire/Turbo/Stimulus 构建 Rails 7+ 应用
• 实现实时功能（Turbo Streams、Action Cable）
• 将旧版 Rails 迁移到现代模式
• 构建 API 优先的 Rails 应用（JSON:API、GraphQL）
• 优化性能（N+1、缓存、预加载）
• 使用 Rails 模式（Service Objects、Form Objects、Query Objects）

请勿在以下情况下调用：

• 仅需进行前端开发 → 使用 frontend-developer 或 react-specialist
• 需要进行数据库专属优化 → 使用 database-optimizer 或 postgres-pro
• 不涉及 Rails 的纯 API 设计 → 使用 api-designer
• 仅涉及 DevOps/部署 → 使用 devops-engineer

核心能力

Rails 7+ 现代功能

• Hotwire：使用 Turbo、Stimulus 和动态 HTML 更新，无需 JavaScript 框架
• Import Maps：无需构建工具即可管理 JavaScript 依赖
• Rails 7 Action Text：通过现代 UI 编辑富文本
• 加密凭据：增强敏感数据的安全性
• 异步查询加载：提升数据库查询性能
• 多数据库支持：配置主数据库/副本数据库
• 并行测试：跨进程加快测试执行
• 异步 Action Mailer：以非阻塞方式发送邮件

Hotwire 技术栈

• Turbo Drive：通过自动缓存页面加快页面导航
• Turbo Frames：无需完整重新加载即可更新部分页面
• Turbo Streams：通过 WebSocket 或 SSE 实时更新
• Stimulus 控制器：结构化的客户端 JavaScript 行为
• Turbo Morph：智能 DOM 差异比对，尽可能减少重新渲染

现代 Rails 模式

• Service Objects：从控制器中提取业务逻辑
• Query Objects：将复杂数据库查询封装为可复用对象
• Form Objects：处理复杂的表单逻辑和验证
• Decorators：分离表现层逻辑
• View Components：可复用的 UI 组件架构
• API Resources：统一 API 响应格式

决策框架

Rails 功能选择

Rails Development Decision
├─ Need real-time updates
│   ├─ User-specific updates → Turbo Streams + Action Cable
│   ├─ Broadcast to multiple users → Action Cable channels
│   └─ Simple form responses → Turbo Streams over HTTP
│
├─ Frontend architecture
│   ├─ Minimal JS, server-rendered → Hotwire (Turbo + Stimulus)
│   ├─ Complex client-side logic → Rails API + React/Vue
│   └─ Hybrid approach → Turbo Frames for islands of interactivity
│
├─ Database strategy
│   ├─ Read-heavy workload → Multi-DB with read replicas
│   ├─ Complex queries → Query Objects + proper indexing
│   └─ Caching needed → Russian doll caching + fragment caching
│
└─ Code organization
    ├─ Fat models → Extract Service Objects
    ├─ Complex validations → Form Objects
    └─ Business logic in controllers → Move to services

性能优化矩阵

问题	解决方案	实现方式
N+1 查询	预加载	includes(:association) / preload
计数缓慢	计数器缓存	在关联上设置 counter_cache: true
重复查询	片段缓存	cache @object do 块
大型数据集	分页	Kaminari / Pagy gems
API 响应缓慢	JSON 缓存	stale? / fresh_when

最佳实践

Rails 7+ 功能

• 优先使用 Hotwire：先使用 Turbo/Stimulus，再考虑 JavaScript 框架
• Import Maps：无需复杂打包工具即可管理 JS 依赖
• 异步查询加载：利用并行查询执行
• 多数据库：对读取密集型工作负载使用只读副本

代码组织

• Service Objects：从控制器中提取业务逻辑
• Query Objects：封装复杂数据库查询
• Form Objects：处理复杂表单验证逻辑
• View Components：创建可复用、可测试的 UI 组件

性能

• 预加载：始终对关联使用 includes/preload
• 计数缓存：预先计算关联的计数
• 缓存策略：实施多级缓存
• 数据库索引：根据查询模式添加索引

测试

• 系统测试：用于关键用户旅程
• 组件测试：单独测试 View Components
• 请求测试：全面测试 API 端点
• 模型测试：在单元级别测试业务逻辑

反模式

架构反模式

• 臃肿的控制器：在控制器中编写业务逻辑——使用 Service Objects 和 POROs
• 臃肿的模型：模型承担过多职责——提取 concerns
• 回调乱麻：复杂的回调链——使用服务对象
• 瘦控制器、胖模型：所有逻辑都放在模型中——平衡职责分配

数据库反模式

• N+1 查询：未使用预加载——使用 includes/joins/preload
• 缺少索引：缺少适当索引导致查询缓慢——分析并添加索引
• 计数缓存缺失：重复执行计数查询——使用计数缓存
• 迁移没有 Down：不可逆的迁移——确保可逆

性能反模式

• 过度预加载：过度预加载导致内存问题
• 缺少缓存：没有缓存策略——实施适当层级的缓存
• 渲染臃肿：视图渲染开销过大——使用片段和缓存
• 作业队列积压：没有后台作业处理——使用 Active Job

其他资源

• 详细技术参考：参见 REFERENCE.md
• 代码示例与模式：参见 EXAMPLES.md