# 機能設計書 2-Railties

## 概要

本ドキュメントは、Ruby on RailsフレームワークにおけるRailtiesの機能設計を記述する。Railtiesは、Railsアプリケーションの作成・運用・実行のための基盤ツールを提供し、アプリケーション起動、プラグイン機構、ジェネレータ、Rakeタスクを管理するコアコンポーネントである。

### 本機能の処理概要

RailtiesはRailsフレームワークのコア部分であり、アプリケーションの起動プロセス、設定管理、ミドルウェアスタック構築、およびプラグイン・エンジン統合の基盤を提供する。

**業務上の目的・背景**：大規模なWebフレームワークでは、多数のコンポーネント（Active Record、Action Controller、Action Mailer等）を協調させる必要がある。Railtiesは各コンポーネントの初期化順序を管理し、アプリケーション固有の設定を適用するための統一的なインターフェースを提供する。これにより、開発者は複雑な起動プロセスを意識せずにアプリケーション開発に集中できる。また、Engineやプラグインによる機能拡張を可能にすることで、コードの再利用性を高めている。

**機能の利用シーン**：
- 新規Railsアプリケーションの作成（`rails new`コマンド）
- アプリケーションの起動・ブートプロセス
- ジェネレータによるスキャフォールド・モデル・コントローラの生成
- Rakeタスクの実行（db:migrate、assets:precompile等）
- Engineやプラグインの作成・組み込み
- 開発・テスト・本番環境の切り替え

**主要な処理内容**：
1. Rails::Application による起動プロセスの管理
2. Rails::Railtie による各コンポーネントの初期化フック
3. Rails::Engine によるモジュール化されたアプリケーション構造
4. ジェネレータシステムによるコード自動生成
5. Rakeタスクの定義と実行
6. ミドルウェアスタックの構築
7. config/application.rb、config/environments/*.rb による設定管理
8. Zeitwerkオートローダーとの連携

**関連システム・外部連携**：
- Thor gem: コマンドラインインターフェース
- Zeitwerk gem: コードのオートロード
- Bundler: Gem依存関係の管理
- Rack: Webサーバーインターフェース

**権限による制御**：Railtiesは基盤ライブラリであり、直接的な認可制御は行わない。ただし、Rails.Info等の開発ツールはローカルリクエストのみに制限される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Railsウェルカム画面 | 主機能 | 新規Railsアプリケーション起動時のデフォルトページ表示処理 |
| 2 | アプリケーションプロパティ画面 | 主機能 | Rails.Infoによるアプリケーション情報の収集・表示処理 |
| 3 | ルーティング一覧画面 | 補助機能 | InfoControllerによるルート情報の表示制御 |
| 4 | ソースコードノート一覧画面 | 主機能 | SourceAnnotationExtractorによるTODO・FIXME・OPTIMIZE等の注釈抽出 |
| 5 | メーラープレビュー一覧画面 | 補助機能 | MailersControllerによるプレビュー一覧の制御 |
| 6 | メーラー詳細画面 | 補助機能 | MailersControllerによるメーラー詳細情報の制御 |

## 機能種別

アプリケーションフレームワーク / 起動管理 / コード生成

## 入力仕様

### 入力パラメータ

#### Rails::Application 初期化

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| initial_variable_values | Hash | No | 初期変数値 | - |
| block | Block | No | 設定ブロック | - |

#### rails new コマンド

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| app_path | String | Yes | アプリケーションパス | 有効なファイルパス |
| --database | String | No | データベースアダプタ | postgresql/mysql/sqlite3等 |
| --skip-* | Boolean | No | 各種スキップオプション | - |
| --api | Boolean | No | APIモード | - |

#### ジェネレータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | String | Yes | 生成対象名 | 有効な識別子 |
| attributes | Array | No | 属性定義 | name:type形式 |

### 入力データソース

- コマンドライン引数
- 設定ファイル（config/application.rb、config/environments/*.rb）
- 環境変数（RAILS_ENV、DATABASE_URL等）
- Gemfile

## 出力仕様

### 出力データ

#### Rails::Application

| 項目名 | 型 | 説明 |
|--------|-----|------|
| initialized? | Boolean | 初期化完了状態 |
| config | Configuration | アプリケーション設定 |
| routes | RouteSet | ルーティング定義 |
| middleware | MiddlewareStack | ミドルウェアスタック |

#### ジェネレータ出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| files | Array<String> | 生成されたファイルパス |
| migrations | Array<String> | 生成されたマイグレーションファイル |

### 出力先

- アプリケーションディレクトリ
- コンソール（ログ・情報表示）
- 生成されたソースファイル

## 処理フロー

### 処理シーケンス（起動プロセス）

```
1. require "config/boot.rb"
   └─ Bundlerによるロードパス設定
2. require "rails"
   └─ Railsモジュールと基本コンポーネントの読み込み
3. Rails::Application クラス定義
   └─ config/application.rb でアプリケーションクラスを定義
4. config.before_configuration コールバック実行
   └─ 設定前のフック処理
5. config/environments/ENV.rb の読み込み
   └─ 環境固有設定の適用
6. config.before_initialize コールバック実行
   └─ 初期化前のフック処理
7. Railtie#initializer の実行
   └─ 各Railtie/Engine/Applicationの初期化子を順次実行
8. config/initializers/*.rb の実行
   └─ カスタム初期化子の実行
9. ミドルウェアスタック構築
   └─ to_prepare コールバック実行
10. eager_load! 実行（本番環境）
    └─ 全コードの事前読み込み
11. config.after_initialize コールバック実行
    └─ 初期化完了後のフック処理
```

### フローチャート

```mermaid
flowchart TD
    A[boot.rb 読込] --> B[Rails読込]
    B --> C[Application定義]
    C --> D{before_configuration}
    D --> E[環境設定読込]
    E --> F{before_initialize}
    F --> G[Railtie初期化子実行]
    G --> H[initializers/*.rb 実行]
    H --> I[ミドルウェア構築]
    I --> J{eager_load?}
    J -->|Yes| K[eager_load!]
    J -->|No| L[after_initialize]
    K --> L
    L --> M[起動完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 初期化子実行順序 | 初期化子は:before/:afterオプションで指定された順序で実行される | アプリケーション起動時 |
| BR-002 | 環境分離 | RAILS_ENV によって読み込まれる設定ファイルが切り替わる | 常時 |
| BR-003 | Eager Loading | config.eager_load が true の場合、起動時に全コードを読み込む | 本番環境 |
| BR-004 | ローカルリクエスト制限 | Rails.Info等は config.consider_all_requests_local または 127.0.0.1/::1 からのリクエストのみ許可 | 開発ツールアクセス時 |

### 計算ロジック

**Zeitwerkオートロード**：
```ruby
# ファイルパスから定数名を推論
# app/models/user.rb -> User
# app/models/admin/user.rb -> Admin::User
```

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

Railties自体は直接データベース操作を行わない。ただし、Rakeタスク（db:migrate等）の提供やActive Recordとの連携を行う。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | LoadError | 必須ファイルが見つからない | ファイルパス・Gemfileを確認 |
| - | NameError | 定数が見つからない | オートロード設定・ファイル命名を確認 |
| - | Rails::Application::Finisher::MissingSecretKeyBase | secret_key_base が未設定 | credentials または環境変数で設定 |

### リトライ仕様

起動プロセスでのリトライは行われない。エラーが発生した場合は起動が中断される。

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

Railtiesはトランザクション管理を直接行わない。

## パフォーマンス要件

- 開発環境起動: 数秒以内
- 本番環境起動（eager_load有効）: アプリケーション規模に依存
- リクエスト処理: ミドルウェアスタックのオーバーヘッドは最小限

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

- secret_key_base は必ず安全に管理する
- 開発ツール（Rails::Info等）は本番環境で無効化
- config.force_ssl で HTTPS を強制可能
- credentials.yml.enc による機密情報の暗号化

## 備考

Railtiesは `railties` gem として提供され、Rails全体の基盤となるコンポーネント。`rails` コマンドはこのgemが提供する。

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: `Rails` モジュールのクラスメソッド（application、root、env等）を把握する。

**主要処理フロー**:
- **25-38行目**: Railsモジュールの定義と各種コントローラのautoload
- **45-47行目**: applicationメソッド。アプリケーションインスタンスの取得
- **66-68行目**: rootメソッド。アプリケーションルートパスの取得
- **76-78行目**: envメソッド。現在の環境名の取得

#### Step 2: エントリーポイントを理解する

アプリケーション起動の中心となるRails::Applicationを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | application.rb | `railties/lib/rails/application.rb` | Rails::Applicationの基本構造 |

**主要処理フロー**:
- **17-62行目**: クラスドキュメント。起動プロセスの概要説明
- **63行目**: `class Application < Engine` の継承関係
- **72-78行目**: inheritedフック。Rails.app_classの設定
- **85-91行目**: createメソッド。アプリケーションインスタンスの生成

#### Step 3: Railtieを理解する

各コンポーネントの初期化フックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | railtie.rb | `railties/lib/rails/railtie.rb` | Rails::Railtieの基本構造 |

**主要処理フロー**:
- **10-21行目**: クラスドキュメント。Railtieの役割説明
- **52-58行目**: initializerマクロの使用例
- **89-99行目**: rake_tasks、generatorsメソッドの説明

**読解のコツ**: `initializer` メソッドが :before, :after オプションで順序制御できることに注目。

#### Step 4: 設定システムを理解する

アプリケーション設定の管理方法を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | configuration.rb | `railties/lib/rails/application/configuration.rb` | 設定クラスの実装 |

#### Step 5: Engineを理解する

モジュール化されたアプリケーション構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | engine.rb | `railties/lib/rails/engine.rb` | Rails::Engineの基本構造 |

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

```
rails コマンド
    │
    ├─ Rails::Command
    │      └─ Rails::Command::ServerCommand
    │             └─ Rack::Server
    │
    └─ Rails::Application
           │
           ├─ Rails::Engine (継承)
           │      │
           │      └─ Rails::Railtie (継承)
           │             ├─ initializer 定義
           │             ├─ rake_tasks 定義
           │             └─ generators 定義
           │
           ├─ Bootstrap (initializers)
           │      └─ 基本的な初期化処理
           │
           ├─ Finisher (initializers)
           │      └─ 最終的な初期化処理
           │
           └─ RoutesReloader
                  └─ ルーティングの再読み込み
```

### データフロー図

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

config/boot.rb ───▶ Bundlerロードパス設定 ───▶ $LOAD_PATH
       │
       ▼
config/application.rb ───▶ Rails::Application定義 ───▶ Rails.app_class
       │
       ▼
config/environments/*.rb ───▶ 環境設定適用 ───▶ Rails.application.config
       │
       ▼
各Railtie ───▶ initializer実行 ───▶ 初期化済みコンポーネント
       │
       ▼
config/routes.rb ───▶ RouteSet構築 ───▶ Rails.application.routes
       │
       ▼
Rackサーバー ◀─── ミドルウェアスタック ◀─── Railsアプリケーション
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| rails.rb | `railties/lib/rails.rb` | ソース | Railsモジュールのメインエントリーポイント |
| application.rb | `railties/lib/rails/application.rb` | ソース | アプリケーション基底クラス |
| railtie.rb | `railties/lib/rails/railtie.rb` | ソース | 各コンポーネントの初期化フック基底 |
| engine.rb | `railties/lib/rails/engine.rb` | ソース | Engine基底クラス |
| configuration.rb | `railties/lib/rails/application/configuration.rb` | ソース | アプリケーション設定 |
| bootstrap.rb | `railties/lib/rails/application/bootstrap.rb` | ソース | 起動時初期化子 |
| finisher.rb | `railties/lib/rails/application/finisher.rb` | ソース | 最終初期化子 |
| routes_reloader.rb | `railties/lib/rails/application/routes_reloader.rb` | ソース | ルーティング再読み込み |
| info_controller.rb | `railties/lib/rails/info_controller.rb` | ソース | 開発情報表示コントローラ |
| welcome_controller.rb | `railties/lib/rails/welcome_controller.rb` | ソース | ウェルカムページコントローラ |
