なぜ明示的な依存関係ワイヤリングなのか？

NENE2 はオートワイヤリングやコンベンションベースのコンテナマジックではなく、明示的に手書きした依存関係ワイヤリングを使います。このページではその理由を説明します。

明示的ワイヤリングとは

// RuntimeServiceProvider.php — すべての依存関係が書き出されている
$container->bind(NoteRepositoryInterface::class, function (ContainerInterface $c) {
    return new PdoNoteRepository($c->get(DatabaseQueryExecutorInterface::class));
});

オートワイヤリングではコンテナがコンストラクタの型ヒントを検査して自動解決します。

明示的ワイヤリングを選ぶ理由

1. ワイヤリングは常に見つけられる

オートワイヤリングでは「このクラスはどう構築されているか？」という問いに答えるためにコンテナの解決ルール、どのインターフェースがバインドされているか、デコレーターの有無を理解する必要があります。明示的ワイヤリングなら、サービスプロバイダーファイルで grep -r 'NoteRepository' を実行すれば完全な答えが得られます。

2. ミスはランタイムではなく起動時に失敗する

存在しないクラスを参照する明示的バインディングは、コンテナの構築時に失敗します。オートワイヤリングのミスは、特定のコードパスが本番環境で実行されたときに初めて現れることがあります。

3. AI エージェントと静的解析がグラフを追える

明示的ワイヤリングは grep・PHPStan・LLM エージェントがコンテナを実行せずにトラバースできる依存関係グラフを生成します。これは AI 支援デリバリーをサポートするために設計されたフレームワークにとって重要です。

4. アノテーションやアトリビュートの結合がない

一部の DI コンテナは #[Inject] アトリビュートや @inject docblock アノテーションを使って解決を誘導します。これによりドメインクラスがコンテナライブラリに結合します。NENE2 のドメインクラスはコンテナアノテーションを持ちません。

トレードオフ

明示的ワイヤリング	オートワイヤリング
常に読みやすい	ボイラープレートが少ない
起動時に速やかに失敗	高速スキャフォールドに便利
マジックなし	コンテナのルールを学ぶ必要がある
クラス数が多いと冗長	自動的にスケール

NENE2 は明示的バインディングの数が管理可能な範囲に収まる小規模・集中型の API プロジェクトを対象としています。プロジェクトが手書きサービスプロバイダーの限界を超えた場合、それはオートワイヤリングを追加するシグナルではなく、NENE2 が適切な基盤であるか再評価するシグナルです。

実践での意味

サービスプロバイダーは関心ごとにグループ化されています（RuntimeServiceProvider、DatabaseServiceProvider）。各プロバイダーは関連するサービスの小さなセットを登録します。プロバイダーファイルがコンテナが何を知っているかの正式な記録です。

新しいエンドポイントを追加する際のステップバイステップのパターンは docs/development/endpoint-scaffold.md を参照してください。