rails-architecture

モダンな Rails 8 アーキテクチャパターン

アーキテクチャの判断ツリー

Where should this code go?
|
+- View/display formatting?       -> Presenter (@presenter-agent)
+- Complex business logic?        -> Service Object (@service-agent)
+- Complex database query?        -> Query Object (@query-agent)
+- Shared behavior across models? -> Concern (/rails-concern skill)
+- Authorization logic?           -> Policy (@policy-agent)
+- Reusable UI with logic?        -> ViewComponent (@viewcomponent-agent)
+- Async/background work?         -> Job (@job-agent, /solid-queue-setup skill)
+- Complex form (multi-model)?    -> Form Object (@form-agent)
+- Transactional email?           -> Mailer (@mailer-agent)
+- Real-time/WebSocket?           -> Channel (/action-cable-patterns skill)
+- Data validation only?          -> Model (@model-agent)
+- HTTP request/response only?    -> Controller (@controller-agent)

レイヤーの責務

レイヤー	責務	含めるべきではないもの
Controller	HTTP、パラメーター、レスポンス	ビジネスロジック、クエリ
Model	データ、バリデーション、関連付け	表示ロジック、HTTP
Service	ビジネスロジック、オーケストレーション	HTTP、表示ロジック
Query	複雑なデータベースクエリ	ビジネスロジック
Presenter	ビューのフォーマット、バッジ	ビジネスロジック、クエリ
Policy	認可ルール	ビジネスロジック
Component	再利用可能な UI のカプセル化	ビジネスロジック
Job	非同期処理	HTTP、表示ロジック
Form	複雑なフォーム処理	永続化ロジック
Mailer	メールの作成	ビジネスロジック
Channel	WebSocket 通信	ビジネスロジック

抽象化しない場合

状況	シンプルに保つ方法	作成しないもの
シンプルな CRUD（10 行未満）	コントローラーに記述する	サービスオブジェクト
一度だけ使用する	コードをインラインで記述する	抽象化
条件が 1～2 個のシンプルなクエリ	モデルのスコープ	クエリオブジェクト
基本的なテキスト整形	ヘルパーメソッド	Presenter
単一モデルのフォーム	form_with model:	フォームオブジェクト
ロジックのないシンプルなパーシャル	パーシャル	ViewComponent

抽象化する場合

兆候	対応
同じコードが 3 箇所以上にある	Concern／サービスに切り出す
コントローラーのアクションが 15 行を超える	サービスに切り出す
モデルが 300 行を超える	Concern に切り出す
条件分岐が複雑	Policy／サービスに切り出す
クエリが 3 つ以上のテーブルを結合する	クエリオブジェクトに切り出す
フォームが複数のモデルにまたがる	フォームオブジェクトに切り出す

詳しい切り出し方針については、/extraction-timing スキルを参照してください。

コアパターン

スキニーコントローラー

# GOOD: Thin controller delegates to service
class OrdersController < ApplicationController
  def create
    result = Orders::CreateService.call(user: current_user, params: order_params)
    if result.success?
      redirect_to result.data, notice: t(".success")
    else
      flash.now[:alert] = result.error
      render :new, status: :unprocessable_entity
    end
  end
end

サービスの結果オブジェクト

すべてのサービスは、一貫した Result オブジェクトを返します。

Result = Data.define(:success, :data, :error) do
  def success? = success
  def failure? = !success
end

デフォルトでマルチテナント対応

# GOOD: Scoped through account
def index
  @events = current_account.events.recent
end

Rails 8 固有の機能

機能	用途	スキル／エージェント
認証	has_secure_password ジェネレーター	/authentication-flow
バックグラウンドジョブ	Solid Queue（データベース対応）	/solid-queue-setup, @job-agent
リアルタイム	Action Cable + Solid Cable	/action-cable-patterns
キャッシュ	Solid Cache（データベース対応）	/caching-strategies
アセット	Propshaft + Import Maps	（組み込み）
デプロイ	Kamal 2 + Thruster	（組み込み）

レイヤー別のテスト戦略

レイヤー	テストタイプ	注目点
Model	単体	バリデーション、スコープ、メソッド
Service	単体	ビジネスロジック、エッジケース
Query	単体	クエリ結果、テナント分離
Presenter	単体	フォーマット、HTML 出力
Controller	リクエスト	統合、HTTP フロー
Component	コンポーネント	レンダリング、バリアント
Policy	単体	認可ルール
System	E2E	重要なユーザーパス

新機能のチェックリスト

1. Model - データ構造を定義する（@migration-agent、@model-agent）
2. Policy - 認可ルールを追加する（@policy-agent）
3. Service - ロジックが複雑な場合は作成する（@service-agent）
4. Query - クエリが複雑な場合は追加する（@query-agent）
5. Controller - 薄く保つ（@controller-agent）
6. Presenter - 表示用にフォーマットする（@presenter-agent）
7. Component - 再利用可能な UI を構築する（@viewcomponent-agent）
8. Mailer - トランザクションメールを追加する（@mailer-agent）
9. Job - バックグラウンド処理を追加する（@job-agent）

参考資料

• レイヤー間の通信パターンについては、layer-interactions.md を参照してください
• サービスオブジェクトのパターンについては、service-patterns.md を参照してください
• クエリオブジェクトのパターンについては、query-patterns.md を参照してください
• エラー処理の方針については、error-handling.md を参照してください
• 包括的なテストについては、testing-strategy.md を参照してください