KLR-Pattern/pydantic-resolve

해결하는 문제

pydantic-resolve는 "N+1 쿼리 문제"를 방지하고 API 응답 모델과 데이터베이스 스키마를 분리하는 데이터 어셈블리 프레임워크입니다. 전통적인 FastAPI 프로젝트에서는 라우트나 서비스에서 관련 데이터를 수동으로 가져오는 경우가 많아 반복 코드와 비효율적인 데이터베이스 쿼리가 발생합니다. 이 프레임워크는 관련 데이터를 어떻게 로드하고 계산할지 구조적으로 정의하는 방법을 제공하여, 응답 트리의 깊이에 관계없이 데이터를 일괄적으로 가져오도록 보장합니다.

작동 방식

프레임워크는 클린 아키텍처 기반의 점진적 레이어링 시스템을 사용합니다:

• 리졸버 (resolve_*): Pydantic 모델에 메서드를 정의하여 어떤 필드에 외부 데이터가 필요한지 선언합니다. 프레임워크는 전체 응답 트리에서 이러한 요청을 수집하고, 로더를 사용해 단일 배치 쿼리로 가져옵니다.
• 포스트프로세서 (post_*): 모든 중첩된 종속성이 해결된 후 실행되는 메서드로, 카운트나 합계와 같은 파생 필드를 계산하는 데 이상적입니다.
• ER 다이어그램: 복잡한 프로젝트에서는 엔티티-관계(ER) 다이어그램에 관계 정의를 중앙화할 수 있습니다. 이를 통해 개별 뷰마다 리졸버 메서드를 작성하지 않고도 관계를 자동으로 로드(AutoLoad)할 수 있습니다.
• 협조 헬퍼: ExposeAs는 부모가 컨텍스트를 자식에게 전달할 수 있게 하며, Collector와 SendTo는 자식이 데이터를 집계하여 부모로 다시 전달할 수 있게 합니다.

대상 사용자

복잡한 중첩된 데이터 관계를 다루는 Python 개발자(특히 FastAPI 사용자)로, N+1 쿼리의 성능 문제를 피하면서도 데이터베이스 계층과 API 계약 간의 명확한 분리를 유지하고자 하는 분들입니다.

주요 특징

• N+1 안전: 내장된 배치 로딩으로 효율적인 데이터 조회 보장.
• 클린 아키텍처: 엔터프라이즈 규칙(엔티티), 애플리케이션 규칙(리졸버), 인터페이스 어댑터(로더)를 엄격히 분리.
• 점진적 도입: 간단한 리졸버부터 시작해 프로젝트 성장에 따라 ER 다이어그램과 자동 로딩으로 확장 가능.
• AI 에이전트 대응: 모델 컨텍스트 프로토콜(MCP)의 네이티브 지원으로 AI 에이전트가 GraphQL 유사 인터페이스를 통해 데이터 그래프를 쿼리할 수 있음.
• 다중 ORM 지원: SQLAlchemy, Django, Tortoise ORM에서 관계 메타데이터를 가져올 수 있음.