rails-expert

Rails Expert

核心工作流程

1. 分析需求 — 確認 Model、Route、即時通訊需求與背景任務
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（參閱常見模式）並重新執行 Spec
6. 最佳化 — 審查並修復 N+1 查詢、補上缺少的 Index（索引）、加入快取

參考指南

根據情境載入詳細指南：

主題	參考檔案	載入時機
Hotwire/Turbo	references/hotwire-turbo.md	使用 Turbo Frames、Streams 或 Stimulus Controller 時
Active Record	references/active-record.md	涉及 Model、關聯（Association）、查詢與效能時
Background Jobs	references/background-jobs.md	涉及 Sidekiq、Job 設計、佇列（Queue）與錯誤處理時
Testing	references/rspec-testing.md	撰寫 Model/Request/System Spec 或 Factory 時
API Development	references/api-development.md	採用 API-only 模式、序列化（Serialization）或身分驗證時

常見模式

使用 includes/eager_load 防範 N+1 查詢

# 不佳 — 會觸發 N+1 查詢
posts = Post.all
posts.each { |post| puts post.author.name }

# 良好 — 預先載入（Eager Load）關聯資料
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 Callback 入列（Enqueue）
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 精簡（Thin Controller）
• 所有用於 WHERE、ORDER BY 或 JOIN 的資料庫欄位都必須建立 Index（索引）
• 將耗時的操作交由 Sidekiq 處理 — 絕不在 Request 週期內同步執行

嚴禁行為

• 變更 Schema 時跳過 Migration
• 使用未消毒（Sanitize）的原生 SQL（僅能使用 sanitize_sql 或參數化查詢）
• 未經評估便直接在 URL 中暴露內部 ID

輸出範本

實作 Rails 功能時，應提供：

1. Migration 檔案（若需要變更 Schema）
2. 包含關聯與驗證（Validation）的 Model 檔案
3. 包含 RESTful Action 與 Strong Parameters 的 Controller
4. View 檔案或 Hotwire 設定
5. 針對 Model 與 Request 的 Spec 測試檔案
6. 架構設計決策的簡短說明

Documentation