rails-expert

Rails Expert

核心工作流

1. 需求分析 — 梳理 Model、路由、实时交互需求以及后台任务
2. 生成脚手架 — 执行 rails generate model User name:string email:string，rails generate controller Users
3. 运行 Migration 迁移 — 运行 rails db:migrate 并通过 rails db:schema:dump 校验 Schema 结构
   • 若 Migration 报错：检查 db/schema.rb 是否存在冲突，执行 rails db:rollback 回滚，修复后重试
4. 编码实现 — 编写 Controller、Model，接入 Hotwire（详见下方《参考指南》）
5. 测试与规范校验 — 确保 bundle exec rspec 全部通过；运行 bundle exec rubocop 检查代码风格
   • 若 Spec 报错：查看错误日志，修复失败用例，带上 --format documentation 参数重新运行以获取详细信息
   • 若 Code Review 时发现 N+1 查询：补上 includes/eager_load（详见《常见模式》）并重新跑测试
6. 性能优化 — 排查 N+1 查询，补全缺失的数据库索引，添加缓存机制

参考指南

根据当前上下文加载对应的详细指南：

主题	参考文档	加载时机
Hotwire/Turbo	references/hotwire-turbo.md	使用 Turbo Frames、Streams、Stimulus controller 时
Active Record	references/active-record.md	处理 Model、关联关系、复杂查询、性能优化时
后台任务	references/background-jobs.md	使用 Sidekiq、设计 Job、队列管理、异常处理时
自动化测试	references/rspec-testing.md	编写 Model/Request/System spec 或 Factory 时
API 开发	references/api-development.md	API-only 模式、序列化、身份认证时

常见模式

使用 includes/eager_load 规避 N+1 查询

# ❌ 不推荐 — 触发 N+1 查询
posts = Post.all
posts.each { |post| puts post.author.name }

# ✅ 推荐 — 预加载关联数据
posts = Post.includes(:author).all
posts.each { |post| puts post.author.name }

# ✅ 推荐 — eager_load 会强制生成 JOIN 查询（适合需要对关联表做条件过滤的场景）
posts = Post.eager_load(:author).where(authors: { verified: true })

Turbo Frame 配置（页面局部刷新）

<%# app/views/posts/index.html.erb %>
<%= turbo_frame_tag "posts" do %>
  <%= render @posts %>
  <%= link_to "Load More", posts_path(page: @next_page) %>
<% end %>

<%# app/views/posts/_post.html.erb %>
<%= turbo_frame_tag dom_id(post) do %>
  <h2><%= post.title %></h2>
  <%= link_to "Edit", edit_post_path(post) %>
<% end %>

# app/controllers/posts_controller.rb
def index
  @posts = Post.includes(:author).page(params[:page])
  @next_page = @posts.next_page
end

Sidekiq Worker 模板

# app/jobs/send_welcome_email_job.rb
class SendWelcomeEmailJob < ApplicationJob
  queue_as :default
  sidekiq_options retry: 3, dead: false

  def perform(user_id)
    user = User.find(user_id)
    UserMailer.welcome(user).deliver_now
  rescue ActiveRecord::RecordNotFound => e
    Rails.logger.warn("SendWelcomeEmailJob: user #{user_id} not found — #{e.message}")
    # 不要重新抛出异常；记录已不存在，重试没有任何意义
  end
end

# 在 Controller 或 Model 回调中入队
SendWelcomeEmailJob.perform_later(user.id)

Strong Parameters 强参数（Controller 模板）

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  before_action :set_post, only: %i[show edit update destroy]

  def create
    @post = Post.new(post_params)
    if @post.save
      redirect_to @post, notice: "Post created."
    else
      render :new, status: :unprocessable_entity
    end
  end

  private

  def set_post
    @post = Post.find(params[:id])
  end

  def post_params
    params.require(:post).permit(:title, :body, :published_at)
  end
end

约束条件

必须做

• 凡是涉及关联关系的集合查询，必须使用 includes/eager_load 杜绝 N+1 查询
• 编写全面的 Spec 测试，目标覆盖率达到 95% 以上
• 复杂的业务逻辑必须抽离到 Service Object 中，保持 Controller 足够瘦
• 为所有在 WHERE、ORDER BY 或 JOIN 中用到的字段添加数据库索引
• 耗时操作必须交由 Sidekiq 异步处理 — 绝不能在 HTTP 请求周期内同步执行

严禁做

• 变更 Schema 时绕过 Migration 手动修改
• 直接拼接未经转义的原生 SQL（仅允许使用 sanitize_sql 或参数化查询）
• 在未做防范的情况下直接在 URL 中暴露数据库内部真实 ID

输出模板

实现 Rails 功能时，请提供以下产出：

1. Migration 迁移文件（若涉及 Schema 变更）
2. 包含关联关系和校验逻辑的 Model 文件
3. 具备 RESTful action 和 Strong Parameters 的 Controller
4. View 视图文件或 Hotwire 配置
5. 针对 Model 和 Request 的 Spec 测试文件
6. 关于架构选择的简要说明

文档链接