KLR-Pattern/pydantic-resolve

何を解決するか

pydantic-resolve は「N+1クエリ問題」を防止し、APIの応答モデルとデータベーススキーマを分離するデータアセンブリフレームワークです。従来のFastAPIプロジェクトでは、開発者がルートやサービス内で関連データを手動で取得するため、重複コードや非効率なデータベースクエリが生じがちです。このフレームワークは、関連データの読み込みと計算方法を構造的に定義する仕組みを提供し、応答ツリーの深さに関係なく、データをバッチで取得することを保証します。

動作方法

フレームワークはクリーンアーキテクチャに基づくプログレッシブレイヤリングシステムを使用しています：

• リゾルバー（resolve_*）： Pydanticモデルにメソッドを定義して、どのフィールドに外部データが必要かを宣言します。フレームワークは応答ツリー全体でこれらのリクエストを収集し、ローダーを使って1回のバッチクエリで取得します。
• ポストプロセッサー（post_*）： すべてのネストされた依存関係が解決された後に実行されるメソッドで、カウントや合計などの導出フィールドを計算するのに最適です。
• ER図： 複雑なプロジェクトでは、エンティティ関係（ER）図に関係定義を集中管理できます。これにより、個々のビューに対してリゾルバーを書かずに、関係を自動的にロード（AutoLoad）できます。
• 調整ヘルパー： ExposeAs は親がコンテキストを子に渡すことを可能にし、Collector と SendTo は子がデータを集約して親に返すことを可能にします。

対象ユーザー

複雑なネストされたデータ関係を扱うPython開発者（特にFastAPIを使用する）で、N+1クエリのパフォーマンスの落とし穴を避けつつ、データベース層とAPI契約の明確な分離を維持したい方。

特徴

• N+1安全： インターネットバッチロードにより、効率的なデータ取得が可能。
• クリーンアーキテクチャ： エンタープライズルール（エンティティ）、アプリケーションルール（リゾルバー）、インターフェースアダプター（ローダー）を厳密に分離。
• プログレッシブ導入： 単純なリゾルバーから始め、プロジェクトの成長に応じてER図と自動ロードへ移行可能。
• AIエージェント対応： Model Context Protocol（MCP）のネイティブサポートを備えており、AIエージェントがGraphQL風のインターフェースでデータグラフをクエリ可能。
• 複数ORM対応： SQLAlchemy、Django、Tortoise ORMから関係メタデータをインポート可能。