mcpField
R
rails-expert

rails-expert

github.com/farmage开发224273 次安装5 周前更新
代码仓库

关于 rails-expert

面向 Rails 开发者的开发技能，覆盖从需求分析、脚手架和迁移到测试与性能检查的流程，并按主题提供参考资料。

主要功能

  1. 01需求分析到验证的流程
  2. 02Rails 脚手架与迁移
  3. 03Hotwire 和 Active Record 指引
  4. 04测试与性能检查
  5. 05按主题组织的参考文件

适用场景

  1. 01规划新的 Rails 功能
  2. 02排查迁移或测试失败
  3. 03检查查询中的 N+1 问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/farmage/opencode-skills --skill rails-expert

安装后在 Claude Code 中输入/rails-expert确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
active-record.md
api-development.md
background-jobs.md
hotwire-turbo.md
rspec-testing.md

详细介绍

Rails 专家

核心工作流

  1. 分析需求 — 确定模型、路由、实时需求和后台任务
  2. 生成资源脚手架 — rails generate model User name:string email:string、rails generate controller Users
  3. 运行迁移 — 执行 rails db:migrate，并通过 rails db:schema:dump 验证架构
    • 如果迁移失败：检查 db/schema.rb 中的冲突，使用 rails db:rollback 回滚，修复后重试
  4. 实现 — 编写控制器和模型，并添加 Hotwire（参见下方的参考指南）
  5. 验证 — bundle exec rspec 必须通过；使用 bundle exec rubocop 检查代码风格
    • 如果规格测试失败：检查错误输出，修复失败的示例，然后使用 --format documentation 重新运行以查看详细信息
    • 如果审查时发现 N+1 查询：添加 includes/eager_load（参见常见模式），并重新运行规格测试
  6. 优化 — 检查 N+1 查询、添加缺失的索引和缓存

参考指南

根据上下文加载详细指南：

主题参考资料加载时机
Hotwire/Turboreferences/hotwire-turbo.md使用 Turbo Frames、Streams、Stimulus 控制器时
Active Recordreferences/active-record.md涉及模型、关联、查询和性能时
后台任务references/background-jobs.md涉及 Sidekiq、任务设计、队列和错误处理时
测试references/rspec-testing.md涉及模型、请求、系统规格测试和工厂时
API 开发references/api-development.md涉及仅 API 模式、序列化和身份验证时

常见模式

使用 includes/eager_load 防止 N+1
# BAD — triggers N+1
posts = Post.all
posts.each { |post| puts post.author.name }

# GOOD — eager load association
posts = Post.includes(:author).all
posts.each { |post| puts post.author.name }

# GOOD — eager_load forces a JOIN (useful when filtering on association)
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}")
    # Do not re-raise; record is gone, no point retrying
  end
end

# Enqueue from controller or model callback
SendWelcomeEmailJob.perform_later(user.id)
Strong Parameters（控制器模板）
# 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 查询
  • 编写全面的规格测试，目标覆盖率 >95%
  • 对复杂业务逻辑使用服务对象；保持控制器精简
  • 为 WHERE、ORDER BY 或 JOIN 中使用的每一列添加数据库索引
  • 将耗时操作交给 Sidekiq 处理，绝不能在请求周期中同步运行
禁止事项
  • 架构变更时跳过迁移
  • 使用未经清理的原始 SQL（只能使用 sanitize_sql 或参数化查询）
  • 未经审慎考虑便在 URL 中暴露内部 ID

输出模板

实现 Rails 功能时，请提供：

  1. 迁移文件（如需更改架构）
  2. 包含关联和验证的模型文件
  3. 包含 RESTful 操作和强参数的控制器
  4. 视图文件或 Hotwire 设置
  5. 模型和请求的规格测试文件
  6. 对架构决策的简要说明

文档

评论

支持 Markdown