xiaohack's Blog - Clean Architecture
type: channel
link: https://blog.xiaohack.org/tag/clean-architecture/
items: 基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践 -- 一套面向复杂业务场景的 Python Web 开发方法论

基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践 -- 一套面向复杂业务场景的 Python Web 开发方法论
type: item
date: 2026-01-31T04:00:57+08:00
description: 基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践篇幅较长无法粘贴全文，原文链接： https://github.com/allmonday/A-Python-web-development-methodology-for-complex-business-scenarios/blob/main/README.zh.md一套面向复杂业务场景的 Python Web 开发方法论目录 基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践 目录 1. 背景与问题 1.1 当前主流做法及其痛点 [模式一：直接使用 ORM （如 SQLAlchemy ）](#模式一直接使用-orm 如-sqlalchemy) 模式二：使用 ORM 的 Eager Loading 模式三：手动组装数据 模式四：使用 GraphQL 1.2 问题根源分析 [问题 1：业务模型与数据模型混淆](#问题-1 业务模型与数据模型混淆) [问题 2：依赖方向错误](#问题-2 依赖方向错误) [问题 3：缺少业务关系的显式声明](#问题-3 缺少业务关系的显式声明) [问题 4：中间表的技术暴露](#问题-4 中间表的技术暴露) 2. Clean Architecture 思想 2.1 核心原则 [原则 1：依赖规则](#原则-1 依赖规则) [原则 2：业务规则独立](#原则-2 业务规则独立) [原则 3：跨边界的数据传递](#原则-3 跨边界的数据传递) 2.2 依赖规则 2.3 在 Web 开发中的应用 传统架构的问题 [3. Pydantic-Resolve：业务模型层](#3-pydantic-resolve 业务模型层) 3.1 核心概念 核心思想 [3.2 ERD：业务关系的声明](#32-erd 业务关系的声明) 定义实体关系图 ERD 的关键特性 [3.3 DataLoader：批量加载的秘密](#33-dataloader 批量加载的秘密) [问题：N+1 查询](#问题 n1-查询) [解决方案：DataLoader](#解决方案 dataloader) [DefineSubset：字段选择与复用](#definesubset 字段选择与复用) [3.4 Resolve 与 Post：数据组装与计算](#34-resolve-与-post 数据组装与计算) [Resolve：声明数据依赖](#resolve 声明数据依赖) [Post：数据后处理](#post 数据后处理) 3.5 跨层数据传递 [Expose：父节点向子节点暴露数据](#expose 父节点向子节点暴露数据) [Collect：子节点向父节点收集数据](#collect 子节点向父节点收集数据) 3.6 小结 [4. FastAPI-Voyager：架构可视化](#4-fastapi-voyager 架构可视化) 4.0 为什么需要架构可视化？ 4.1 核心功能 1. 自动扫描 API 结构 2. 三层架构展示 4.2 ERD 与 API Route 的结合 核心：业务-技术映射图 4.3 实战应用场景 [场景 1：发现架构偏离](#场景-1 发现架构偏离) [场景 2：发现过度嵌套](#场景-2 发现过度嵌套) [场景 3：新人快速理解系统](#场景-3 新人快速理解系统) 5. 完整的开发流程 5.1 架构设计阶段 [步骤 1：识别核心业务实体](#步骤-1 识别核心业务实体) [步骤 2：定义实体关系](#步骤-2 定义实体关系) 5.2 实体定义阶段 定义 ERD 5.3 数据层实现 [定义 ORM Models （以 ERD 为指导）](#定义-orm-models 以-erd-为指导) 实现 Loaders 5.4 API 实现阶段 定义 Response Models 实现 API Routes 5.5 可视化验证 集成 FastAPI-Voyager 验证架构 6. 与其他方案的对比 6.1 vs 传统 ORM 6.2 vs GraphQL 6.3 vs DDD 框架 7. 总结 核心价值 1. 业务模型优先 2. Clean Architecture 实现 3. 自动性能优化 4. 架构可视化 5. 开发效率提升 6. 更易测试和调试 适用场景 推荐使用 不推荐使用 结语 参考资料 1. 背景与问题1.1 当前主流做法及其痛点在 Python Web 开发中，处理复杂业务场景时，开发者通常采用以下几种模式：模式一：直接使用 ORM （如 SQLAlchemy ）@router.get("/teams/{team_i…

基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践 -- 一套面向复杂业务场景的 Python Web 开发方法论
type: item
date: 2026-01-19T16:01:25+08:00
description: 基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践篇幅较长无法粘贴全文，原文链接： https://github.com/allmonday/A-Python-web-development-methodology-for-complex-business-scenarios/blob/main/README.zh.md一套面向复杂业务场景的 Python Web 开发方法论目录 基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践 目录 1. 背景与问题 1.1 当前主流做法及其痛点 [模式一：直接使用 ORM （如 SQLAlchemy ）](#模式一直接使用-orm 如-sqlalchemy) 模式二：使用 ORM 的 Eager Loading 模式三：手动组装数据 模式四：使用 GraphQL 1.2 问题根源分析 [问题 1：业务模型与数据模型混淆](#问题-1 业务模型与数据模型混淆) [问题 2：依赖方向错误](#问题-2 依赖方向错误) [问题 3：缺少业务关系的显式声明](#问题-3 缺少业务关系的显式声明) [问题 4：中间表的技术暴露](#问题-4 中间表的技术暴露) 2. Clean Architecture 思想 2.1 核心原则 [原则 1：依赖规则](#原则-1 依赖规则) [原则 2：业务规则独立](#原则-2 业务规则独立) [原则 3：跨边界的数据传递](#原则-3 跨边界的数据传递) 2.2 依赖规则 2.3 在 Web 开发中的应用 传统架构的问题 [3. Pydantic-Resolve：业务模型层](#3-pydantic-resolve 业务模型层) 3.1 核心概念 核心思想 [3.2 ERD：业务关系的声明](#32-erd 业务关系的声明) 定义实体关系图 ERD 的关键特性 [3.3 DataLoader：批量加载的秘密](#33-dataloader 批量加载的秘密) [问题：N+1 查询](#问题 n1-查询) [解决方案：DataLoader](#解决方案 dataloader) [DefineSubset：字段选择与复用](#definesubset 字段选择与复用) [3.4 Resolve 与 Post：数据组装与计算](#34-resolve-与-post 数据组装与计算) [Resolve：声明数据依赖](#resolve 声明数据依赖) [Post：数据后处理](#post 数据后处理) 3.5 跨层数据传递 [Expose：父节点向子节点暴露数据](#expose 父节点向子节点暴露数据) [Collect：子节点向父节点收集数据](#collect 子节点向父节点收集数据) 3.6 小结 [4. FastAPI-Voyager：架构可视化](#4-fastapi-voyager 架构可视化) 4.0 为什么需要架构可视化？ 4.1 核心功能 1. 自动扫描 API 结构 2. 三层架构展示 4.2 ERD 与 API Route 的结合 核心：业务-技术映射图 4.3 实战应用场景 [场景 1：发现架构偏离](#场景-1 发现架构偏离) [场景 2：发现过度嵌套](#场景-2 发现过度嵌套) [场景 3：新人快速理解系统](#场景-3 新人快速理解系统) 5. 完整的开发流程 5.1 架构设计阶段 [步骤 1：识别核心业务实体](#步骤-1 识别核心业务实体) [步骤 2：定义实体关系](#步骤-2 定义实体关系) 5.2 实体定义阶段 定义 ERD 5.3 数据层实现 [定义 ORM Models （以 ERD 为指导）](#定义-orm-models 以-erd-为指导) 实现 Loaders 5.4 API 实现阶段 定义 Response Models 实现 API Routes 5.5 可视化验证 集成 FastAPI-Voyager 验证架构 6. 与其他方案的对比 6.1 vs 传统 ORM 6.2 vs GraphQL 6.3 vs DDD 框架 7. 总结 核心价值 1. 业务模型优先 2. Clean Architecture 实现 3. 自动性能优化 4. 架构可视化 5. 开发效率提升 6. 更易测试和调试 适用场景 推荐使用 不推荐使用 结语 参考资料 1. 背景与问题1.1 当前主流做法及其痛点在 Python Web 开发中，处理复杂业务场景时，开发者通常采用以下几种模式：模式一：直接使用 ORM （如 SQLAlchemy ）@router.get("/teams/{team_i…

基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践 -- 一套面向复杂业务场景的 Python Web 开发方法论
type: item
date: 2026-01-17T21:57:04+08:00
description: 基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践篇幅较长无法粘贴全文，原文链接： https://github.com/allmonday/A-Python-web-development-methodology-for-complex-business-scenarios/blob/main/README.zh.md一套面向复杂业务场景的 Python Web 开发方法论目录 基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践 目录 1. 背景与问题 1.1 当前主流做法及其痛点 [模式一：直接使用 ORM （如 SQLAlchemy ）](#模式一直接使用-orm 如-sqlalchemy) 模式二：使用 ORM 的 Eager Loading 模式三：手动组装数据 模式四：使用 GraphQL 1.2 问题根源分析 [问题 1：业务模型与数据模型混淆](#问题-1 业务模型与数据模型混淆) [问题 2：依赖方向错误](#问题-2 依赖方向错误) [问题 3：缺少业务关系的显式声明](#问题-3 缺少业务关系的显式声明) [问题 4：中间表的技术暴露](#问题-4 中间表的技术暴露) 2. Clean Architecture 思想 2.1 核心原则 [原则 1：依赖规则](#原则-1 依赖规则) [原则 2：业务规则独立](#原则-2 业务规则独立) [原则 3：跨边界的数据传递](#原则-3 跨边界的数据传递) 2.2 依赖规则 2.3 在 Web 开发中的应用 传统架构的问题 [3. Pydantic-Resolve：业务模型层](#3-pydantic-resolve 业务模型层) 3.1 核心概念 核心思想 [3.2 ERD：业务关系的声明](#32-erd 业务关系的声明) 定义实体关系图 ERD 的关键特性 [3.3 DataLoader：批量加载的秘密](#33-dataloader 批量加载的秘密) [问题：N+1 查询](#问题 n1-查询) [解决方案：DataLoader](#解决方案 dataloader) [DefineSubset：字段选择与复用](#definesubset 字段选择与复用) [3.4 Resolve 与 Post：数据组装与计算](#34-resolve-与-post 数据组装与计算) [Resolve：声明数据依赖](#resolve 声明数据依赖) [Post：数据后处理](#post 数据后处理) 3.5 跨层数据传递 [Expose：父节点向子节点暴露数据](#expose 父节点向子节点暴露数据) [Collect：子节点向父节点收集数据](#collect 子节点向父节点收集数据) 3.6 小结 [4. FastAPI-Voyager：架构可视化](#4-fastapi-voyager 架构可视化) 4.0 为什么需要架构可视化？ 4.1 核心功能 1. 自动扫描 API 结构 2. 三层架构展示 4.2 ERD 与 API Route 的结合 核心：业务-技术映射图 4.3 实战应用场景 [场景 1：发现架构偏离](#场景-1 发现架构偏离) [场景 2：发现过度嵌套](#场景-2 发现过度嵌套) [场景 3：新人快速理解系统](#场景-3 新人快速理解系统) 5. 完整的开发流程 5.1 架构设计阶段 [步骤 1：识别核心业务实体](#步骤-1 识别核心业务实体) [步骤 2：定义实体关系](#步骤-2 定义实体关系) 5.2 实体定义阶段 定义 ERD 5.3 数据层实现 [定义 ORM Models （以 ERD 为指导）](#定义-orm-models 以-erd-为指导) 实现 Loaders 5.4 API 实现阶段 定义 Response Models 实现 API Routes 5.5 可视化验证 集成 FastAPI-Voyager 验证架构 6. 与其他方案的对比 6.1 vs 传统 ORM 6.2 vs GraphQL 6.3 vs DDD 框架 7. 总结 核心价值 1. 业务模型优先 2. Clean Architecture 实现 3. 自动性能优化 4. 架构可视化 5. 开发效率提升 6. 更易测试和调试 适用场景 推荐使用 不推荐使用 结语 参考资料 1. 背景与问题1.1 当前主流做法及其痛点在 Python Web 开发中，处理复杂业务场景时，开发者通常采用以下几种模式：模式一：直接使用 ORM （如 SQLAlchemy ）@router.get("/teams/{team_i…

基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践 -- 一套面向复杂业务场景的 Python Web 开发方法论
type: item
date: 2026-01-12T10:44:53+08:00
description: 基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践篇幅较长无法粘贴全文，原文链接： https://github.com/allmonday/A-Python-web-development-methodology-for-complex-business-scenarios/blob/main/README.zh.md一套面向复杂业务场景的 Python Web 开发方法论目录 基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践 目录 1. 背景与问题 1.1 当前主流做法及其痛点 [模式一：直接使用 ORM （如 SQLAlchemy ）](#模式一直接使用-orm 如-sqlalchemy) 模式二：使用 ORM 的 Eager Loading 模式三：手动组装数据 模式四：使用 GraphQL 1.2 问题根源分析 [问题 1：业务模型与数据模型混淆](#问题-1 业务模型与数据模型混淆) [问题 2：依赖方向错误](#问题-2 依赖方向错误) [问题 3：缺少业务关系的显式声明](#问题-3 缺少业务关系的显式声明) [问题 4：中间表的技术暴露](#问题-4 中间表的技术暴露) 2. Clean Architecture 思想 2.1 核心原则 [原则 1：依赖规则](#原则-1 依赖规则) [原则 2：业务规则独立](#原则-2 业务规则独立) [原则 3：跨边界的数据传递](#原则-3 跨边界的数据传递) 2.2 依赖规则 2.3 在 Web 开发中的应用 传统架构的问题 [3. Pydantic-Resolve：业务模型层](#3-pydantic-resolve 业务模型层) 3.1 核心概念 核心思想 [3.2 ERD：业务关系的声明](#32-erd 业务关系的声明) 定义实体关系图 ERD 的关键特性 [3.3 DataLoader：批量加载的秘密](#33-dataloader 批量加载的秘密) [问题：N+1 查询](#问题 n1-查询) [解决方案：DataLoader](#解决方案 dataloader) [DefineSubset：字段选择与复用](#definesubset 字段选择与复用) [3.4 Resolve 与 Post：数据组装与计算](#34-resolve-与-post 数据组装与计算) [Resolve：声明数据依赖](#resolve 声明数据依赖) [Post：数据后处理](#post 数据后处理) 3.5 跨层数据传递 [Expose：父节点向子节点暴露数据](#expose 父节点向子节点暴露数据) [Collect：子节点向父节点收集数据](#collect 子节点向父节点收集数据) 3.6 小结 [4. FastAPI-Voyager：架构可视化](#4-fastapi-voyager 架构可视化) 4.0 为什么需要架构可视化？ 4.1 核心功能 1. 自动扫描 API 结构 2. 三层架构展示 4.2 ERD 与 API Route 的结合 核心：业务-技术映射图 4.3 实战应用场景 [场景 1：发现架构偏离](#场景-1 发现架构偏离) [场景 2：发现过度嵌套](#场景-2 发现过度嵌套) [场景 3：新人快速理解系统](#场景-3 新人快速理解系统) 5. 完整的开发流程 5.1 架构设计阶段 [步骤 1：识别核心业务实体](#步骤-1 识别核心业务实体) [步骤 2：定义实体关系](#步骤-2 定义实体关系) 5.2 实体定义阶段 定义 ERD 5.3 数据层实现 [定义 ORM Models （以 ERD 为指导）](#定义-orm-models 以-erd-为指导) 实现 Loaders 5.4 API 实现阶段 定义 Response Models 实现 API Routes 5.5 可视化验证 集成 FastAPI-Voyager 验证架构 6. 与其他方案的对比 6.1 vs 传统 ORM 6.2 vs GraphQL 6.3 vs DDD 框架 7. 总结 核心价值 1. 业务模型优先 2. Clean Architecture 实现 3. 自动性能优化 4. 架构可视化 5. 开发效率提升 6. 更易测试和调试 适用场景 推荐使用 不推荐使用 结语 参考资料 1. 背景与问题1.1 当前主流做法及其痛点在 Python Web 开发中，处理复杂业务场景时，开发者通常采用以下几种模式：模式一：直接使用 ORM （如 SQLAlchemy ）@router.get("/teams/{team_i…