KLR-Pattern/pydantic-resolve

解决的问题

pydantic-resolve 是一个防止「N+1 查询问题」并解耦 API 响应模型与数据库模式的数据组装框架。在传统的 FastAPI 项目中，开发者经常在路由或服务中手动获取相关数据，导致代码重复和数据库查询效率低下。该框架提供了一种结构化的方式来定义相关数据应如何加载和计算，确保无论响应树的深度如何，数据都能以批量方式获取。

工作原理

该框架基于 Clean Architecture 的渐进式分层系统：

• 解析器（resolve_*）： 你在 Pydantic 模型上定义方法，声明哪些字段需要外部数据。框架会收集整个响应树中的这些请求，并使用 加载器 通过一次批量查询获取数据。
• 后处理器（post_*）： 这些方法在所有嵌套依赖项解析完成后运行，非常适合用于计算衍生字段，如计数或求和。
• ER 图： 对于复杂项目，你可以将关系定义集中在一个实体-关系（ER）图中。这使得框架能够自动加载关系（AutoLoad），而无需为每个视图编写单独的解析器方法。
• 协调辅助工具： ExposeAs 允许父级将上下文传递给子级，而 Collector 和 SendTo 允许子级将数据聚合后回传给父级。

适用人群

构建 API 的 Python 开发者（尤其是使用 FastAPI 的），处理复杂的嵌套数据关系，希望避免 N+1 查询的性能陷阱，同时保持数据库层与 API 协议之间的清晰分离。

核心亮点

• N+1 安全： 内置批量加载机制，确保高效的数据获取。
• 清晰架构： 严格分离企业规则（实体）、应用规则（解析器）和接口适配器（加载器）。
• 渐进式采用： 可从简单的解析器开始，随着项目增长逐步过渡到 ER 图和自动化加载。
• AI 代理就绪： 原生支持 Model Context Protocol（MCP），允许 AI 代理通过类似 GraphQL 的接口查询你的数据图。
• 多 ORM 支持： 可从 SQLAlchemy、Django 和 Tortoise ORM 导入关系元数据。