# 機能設計書 7-Action Controller

## 概要

本ドキュメントは、Ruby on RailsフレームワークにおけるAction Controllerの機能設計を記述する。Action Controllerは、HTTPリクエスト処理とレスポンス生成を担当し、HTML・JSON・XML・PDF等の多様な形式の出力に対応するコンポーネントである。

### 本機能の処理概要

Action Controllerは、MVCアーキテクチャにおけるController層を実装し、リクエストの受け取りからレスポンスの送信までの処理フローを管理する。

**業務上の目的・背景**：Webアプリケーションでは、ユーザーからのリクエストを適切に処理し、必要なデータの取得・加工を行い、結果をレスポンスとして返す必要がある。Action Controllerは、この処理フローを構造化し、フィルタ（コールバック）、パラメータ処理、レンダリング、リダイレクト等の共通機能を提供することで、開発者がビジネスロジックの実装に集中できる環境を提供する。Strong Parametersによりセキュアなパラメータ処理も実現する。

**機能の利用シーン**：
- HTTPリクエストの受け取りとパラメータ処理
- before_action等のフィルタによる共通処理
- モデルを介したデータ操作
- ビューのレンダリングまたはJSONレスポンス
- リダイレクト処理
- セッション・Flash管理
- 認証・認可の実装

**主要な処理内容**：
1. リクエストパラメータの取得とStrong Parameters
2. before_action/after_action/around_action コールバック
3. render/redirect_to によるレスポンス生成
4. respond_to によるフォーマット別処理
5. セッション・Flash・Cookie管理
6. CSRF保護
7. HTTP認証（Basic/Digest/Token）
8. ストリーミングレスポンス
9. レート制限

**関連システム・外部連携**：
- Action View: ビューレンダリング
- Action Dispatch: ルーティング、リクエスト/レスポンスオブジェクト
- Active Model: フォーム処理

**権限による制御**：before_actionとskip_before_actionを使用して認証・認可フィルタを実装可能。HttpAuthenticationモジュールでHTTP認証もサポート。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | アクション未定義画面 | 補助機能 | アクション候補の提案表示 |

## 機能種別

コントローラフレームワーク / リクエスト処理 / レスポンス生成

## 入力仕様

### 入力パラメータ

#### params

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| params | ActionController::Parameters | - | リクエストパラメータ | Strong Parametersで制御 |

#### render オプション

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| action | String/Symbol | No | レンダリングするアクション名 | - |
| template | String | No | テンプレートパス | - |
| json | Object | No | JSON出力対象 | - |
| xml | Object | No | XML出力対象 | - |
| status | Integer/Symbol | No | HTTPステータスコード | - |

#### redirect_to オプション

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| url | String/Hash/Object | Yes | リダイレクト先 | - |
| status | Integer/Symbol | No | HTTPステータスコード | 300番台 |
| notice/alert | String | No | Flashメッセージ | - |

### 入力データソース

- HTTPリクエストボディ
- URLパラメータ
- クエリストリング
- ルーティングパラメータ

## 出力仕様

### 出力データ

#### render

| 項目名 | 型 | 説明 |
|--------|-----|------|
| response_body | String | レンダリング結果 |
| content_type | String | Content-Typeヘッダ |
| status | Integer | HTTPステータスコード |

#### redirect_to

| 項目名 | 型 | 説明 |
|--------|-----|------|
| location | String | Locationヘッダ |
| status | Integer | HTTPステータスコード（デフォルト302） |

### 出力先

- HTTPレスポンス

## 処理フロー

### 処理シーケンス（アクション実行）

```
1. ルーティングからコントローラ・アクション特定
   └─ Action Dispatchからの呼び出し
2. before_action コールバック実行
   └─ 認証・認可、パラメータ準備等
3. アクションメソッド実行
   └─ ビジネスロジックの実行
4. レンダリング
   └─ render または redirect_to
5. after_action コールバック実行
   └─ ログ記録、クリーンアップ等
6. レスポンス返却
   └─ Action Dispatchへ
```

### フローチャート

```mermaid
flowchart TD
    A[リクエスト受信] --> B[before_action]
    B --> C{フィルタ通過?}
    C -->|Yes| D[アクション実行]
    C -->|No| E[処理中断/リダイレクト]
    D --> F{render/redirect?}
    F -->|render| G[ビューレンダリング]
    F -->|redirect| H[リダイレクトレスポンス]
    F -->|暗黙| I[デフォルトテンプレート]
    G --> J[after_action]
    H --> J
    I --> J
    J --> K[レスポンス送信]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Strong Parameters | params.require/permit でホワイトリスト制御 | パラメータ使用時 |
| BR-002 | CSRF保護 | POST/PATCH/PUT/DELETEリクエストでトークン検証 | protect_from_forgery有効時 |
| BR-003 | 暗黙のレンダリング | render/redirect_toがない場合、アクション名のテンプレートをレンダリング | アクション終了時 |
| BR-004 | フィルタ順序 | before_actionは定義順、after_actionは逆順で実行 | コールバック実行時 |
| BR-005 | ダブルレンダー禁止 | 1リクエストで複数回のrender/redirectは禁止 | レスポンス生成時 |

### 計算ロジック

**Strong Parameters**：
```ruby
params.require(:user).permit(:name, :email)
# -> { name: "...", email: "..." } のみ許可
```

## データベース操作仕様

Action Controller自体は直接データベース操作を行わない。モデルを介してデータ操作を行う。

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | Action Controller自体はDB操作を行わない |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ActionController::ParameterMissing | require されたパラメータが存在しない | パラメータを確認 |
| - | ActionController::UnpermittedParameters | 許可されていないパラメータがある | permit を確認 |
| - | ActionController::DoubleRenderError | render/redirectを2回呼び出した | 処理フローを修正 |
| - | ActionController::UnknownFormat | 対応していないフォーマット | respond_to で対応 |
| - | ActionController::InvalidAuthenticityToken | CSRFトークン検証失敗 | フォームにトークンを含める |

### リトライ仕様

リクエスト処理でのリトライは行われない。

## トランザクション仕様

Action Controllerはトランザクション管理を直接行わない。モデルを介して制御する。

## パフォーマンス要件

- アクション実行は可能な限り高速に
- フラグメントキャッシュ、ページキャッシュで高速化可能

## セキュリティ考慮事項

- Strong Parametersによるマスアサインメント対策
- protect_from_forgery によるCSRF対策
- HttpAuthentication によるHTTP認証
- Content Security Policy の設定
- AllowBrowser によるブラウザバージョン制限
- RateLimiting によるレート制限

## 備考

Action Controllerは `actionpack` gem の一部として提供される。Strong Parametersによるパラメータ検証機能を含む。

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

Action Controllerのモジュール構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | action_controller.rb | `actionpack/lib/action_controller.rb` | モジュール定義とautoload一覧 |

**読解のコツ**: `autoload_under "metal"` でグループ化されたモジュール群を把握する。

**主要処理フロー**:
- **18-74行目**: ActionControllerモジュールの定義とautoload
- **21-24行目**: API, Base, Metal, Rendererの定義
- **31-63行目**: autoload_under "metal" で機能モジュール群の定義

#### Step 2: Baseクラスを理解する

コントローラの基底クラスを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | base.rb | `actionpack/lib/action_controller/base.rb` | ActionController::Baseの構成 |

#### Step 3: Strong Parametersを理解する

パラメータ処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | strong_parameters.rb | `actionpack/lib/action_controller/metal/strong_parameters.rb` | Strong Parametersの実装 |

#### Step 4: RequestForgeryProtectionを理解する

CSRF保護を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | request_forgery_protection.rb | `actionpack/lib/action_controller/metal/request_forgery_protection.rb` | CSRF保護の実装 |

### プログラム呼び出し階層図

```
ActionController::Base
    │
    ├─ Metal (継承)
    │      └─ 最小限のコントローラ機能
    │
    ├─ StrongParameters (include)
    │      ├─ params
    │      ├─ require
    │      └─ permit
    │
    ├─ RequestForgeryProtection (include)
    │      ├─ protect_from_forgery
    │      └─ verify_authenticity_token
    │
    ├─ Rendering (include)
    │      ├─ render
    │      └─ render_to_string
    │
    ├─ Redirecting (include)
    │      └─ redirect_to
    │
    ├─ Flash (include)
    │      ├─ flash
    │      └─ notice/alert
    │
    ├─ Cookies (include)
    │      └─ cookies
    │
    └─ HttpAuthentication (include)
           ├─ Basic
           ├─ Digest
           └─ Token
```

### データフロー図

```
[入力]                    [処理]                           [出力]

HTTPリクエスト ───▶ params (ActionController::Parameters)
       │                    │
       ▼                    ▼
パラメータ ───▶ require/permit ───▶ 許可されたパラメータ
       │                              │
       ▼                              ▼
コントローラ ───▶ アクション実行 ───▶ インスタンス変数設定
       │                              │
       ▼                              ▼
render/redirect ───▶ レスポンス生成 ───▶ HTTPレスポンス
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| action_controller.rb | `actionpack/lib/action_controller.rb` | ソース | モジュールエントリーポイント |
| base.rb | `actionpack/lib/action_controller/base.rb` | ソース | 標準コントローラ基底クラス |
| metal.rb | `actionpack/lib/action_controller/metal.rb` | ソース | 軽量コントローラ基底クラス |
| api.rb | `actionpack/lib/action_controller/api.rb` | ソース | APIコントローラ基底クラス |
| strong_parameters.rb | `actionpack/lib/action_controller/metal/strong_parameters.rb` | ソース | Strong Parameters |
| request_forgery_protection.rb | `actionpack/lib/action_controller/metal/request_forgery_protection.rb` | ソース | CSRF保護 |
| rendering.rb | `actionpack/lib/action_controller/metal/rendering.rb` | ソース | レンダリング |
| redirecting.rb | `actionpack/lib/action_controller/metal/redirecting.rb` | ソース | リダイレクト |
| flash.rb | `actionpack/lib/action_controller/metal/flash.rb` | ソース | Flash管理 |
| cookies.rb | `actionpack/lib/action_controller/metal/cookies.rb` | ソース | Cookie管理 |
| http_authentication.rb | `actionpack/lib/action_controller/metal/http_authentication.rb` | ソース | HTTP認証 |
| rate_limiting.rb | `actionpack/lib/action_controller/metal/rate_limiting.rb` | ソース | レート制限 |
