项目定位评估：sqlmodel-nexus 与 pydantic-resolve 的关系梳理

[allmonday]

背景

sqlmodel-nexus 是 pydantic-resolve 的简化版本，借助 SQLModel 提前固化了一些配置，节省了重复声明 schema 的成本，但也牺牲了一些灵活度。

核心对比

维度	pydantic-resolve	sqlmodel-nexus
数据源	任意（ORM、API、文件…）	SQLModel（数据库）
Schema 声明	每层手写	复用 SQLModel 定义
关系发现	手动 resolve_*	自动从 ForeignKey/Relationship 推断
灵活度	高（任意嵌套组合）	中（SQLModel 约束内）
上手成本	理解概念多	写好 Model 就有了

设计哲学

本质上是一个 约定优于配置（Convention over Configuration） 的 trade-off：

• pydantic-resolve — 通用声明式数据组装工具，任意数据源、任意嵌套结构，灵活但需要手写每一层 schema
• sqlmodel-nexus — 绑定 SQLModel，模型定义即 schema，关系已经自带了，省掉重复声明，开箱即用

产品策略思考

1. 目标用户：已有 SQLModel 定义、想快速出 API 的开发者
2. 核心价值：Model 即 Schema → 自动出 GraphQL API / REST DTO / MCP Server
3. 边界：需要超出 SQLModel 能力的复杂场景时，引导用户使用 pydantic-resolve
4. 互补关系：nexus 是 resolve 在 SQLModel 场景下的「快车道」

后续可考虑

• 在 README 中明确与 pydantic-resolve 的关系定位
• 文档中增加「何时选择 nexus vs resolve」的指引
• 考虑是否提供从 nexus 向 resolve 的迁移路径（进阶场景）

[allmonday]

补充：问题与改进点分析

基于对比梳理，整理以下 nexus 当前面临的核心问题和可改进方向：

问题

1. 灵活度受限于 SQLModel 边界

   • 只能处理 SQLModel 定义的数据结构，无法组装非 ORM 来源（外部 API、文件、缓存等）
   • 跨数据源的嵌套场景（如数据库模型 + 第三方 API 聚合）无法覆盖

2. Schema 定义与 ORM 模型耦合

   • API 响应结构完全依赖数据库模型定义，无法自由裁剪字段或增加计算字段
   • 不同接口需要同一模型的不同视图时，灵活性不足

3. 关系推断依赖 ForeignKey / Relationship 声明

   • 隐式关系（非外键的关联逻辑）无法自动发现，需要额外配置
   • 多态关系、条件关系等复杂场景可能超出自动推断能力

4. 与 resolve 的边界模糊

   • 用户不清楚何时该用 nexus、何时该直接用 resolve
   • 进阶场景从 nexus 迁移到 resolve 的路径不明确

改进方向

• DefineSubset 增强：在复用 SQLModel 定义的基础上，支持更灵活的字段裁剪和计算字段注入
• 非 ORM 关系支持：提供 Relationship(...) 机制补充隐式/虚拟关系声明，突破纯 ForeignKey 限制
• 混合数据源：允许在 nexus 的组装树中插入自定义 loader，接入非数据库数据
• 文档明确边界：在 README 中增加「nexus vs resolve」决策指南，让用户快速判断适用场景
• 迁移路径：提供从 nexus 到 resolve 的渐进式升级指引，降低用户成长焦虑
• Core API Mode 完善：ExposeAs / SendTo / Collector 跨层数据流能力需要更多示例和文档覆盖