KLR-Pattern/pydantic-resolve

解決的問題

pydantic-resolve 是一個防止「N+1 查詢問題」並解耦 API 回應模型與資料庫架構的資料組裝框架。在傳統的 FastAPI 專案中，開發者經常在路由或服務中手動取得相關資料，導致重複程式碼與低效的資料庫查詢。此框架提供一種結構化的方式來定義相關資料應如何載入與計算，確保無論回應樹的深度為何，資料都能以批次方式取得。

工作原理

框架使用基於 Clean Architecture 的漸進式分層系統：

• 解析器（resolve_*）： 您在 Pydantic 模型上定義方法，宣告哪些欄位需要外部資料。框架會收集整個回應樹中的這些請求，並使用 載入器 透過單一批次查詢取得資料。
• 後處理器（post_*）： 這些方法在所有嵌套依賴項解析完成後執行，非常適合用於計算衍生欄位，如計數或總和。
• ER 圖： 對於複雜專案，您可將關係定義集中於實體-關係（ER）圖中。這讓框架能自動載入關係（AutoLoad），無需為每個檢視寫下個別的解析器方法。
• 協調輔助工具： ExposeAs 允許父層將上下文傳遞給子層，而 Collector 與 SendTo 則允許子層將資料聚合後回傳給父層。

適用對象

使用 Python 建構 API（特別是 FastAPI）的開發者，處理複雜的嵌套資料關係，希望避免 N+1 查詢的效能陷阱，同時維持資料庫層與 API 合約之間的清晰分離。

核心亮點

• N+1 安全： 內建批次載入機制，確保高效資料取得。
• 清晰架構： 嚴格分離企業規則（實體）、應用規則（解析器）與介面適配器（載入器）。
• 漸進式採用： 可從簡單的解析器開始，隨著專案成長逐步過渡至 ER 圖與自動載入。
• AI 代理就緒： 原生支援 Model Context Protocol（MCP），讓 AI 代理可透過類似 GraphQL 的介面查詢您的資料圖。
• 多 ORM 支援： 可從 SQLAlchemy、Django 與 Tortoise ORM 導入關係元資料。