xiaohack's Blog - GraphQL
type: channel
link: https://blog.xiaohack.org/tag/graphql/
items: 摩擦解决之道：改变关键要素
items: 基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践 -- 一套面向复杂业务场景的 Python Web 开发方法论
items: 开源一款以博客为名的 AI 增强创作与分享的工具

摩擦解决之道：改变关键要素
type: item
date: 2026-01-31T08:04:10+08:00
description: 当 Andrew Harmel-Law 邀请演讲者参加 QCon 伦敦大会时，他首先想到的是：“让 Diana 和 Cat 一起登台！”这完全是出于一种顽皮的冲动。 Cat Morris 是一位产品经理。Diana Montalion 是一位系统架构师。我们都专门从事软件系统和平台开发。我们都把对方视为我们所有痛苦的根源。不是个人层面的，我们从未一起工作过，但我们都认为对方所代表的角色是问题所在。 但我们也致力于改善我们的工作方式。如果我们能够消除我们之间存在的摩擦……那对每个人来说都是一件好事，对吧？ 首先，我们对参与的每一个重大项目做了建模分析。我们发现，每一个项目的结局都像泰坦尼克号一样：撞上了冰山。 我们发现了以下这些改变职业生涯的真相： 我们的工作有很多重合的地方。我们需要彼此。合作会带来更好的结果。我们思考问题的方式不同但互补。我们要解决的不是技术问题。技术挑战不难解决。困难之处在于消除摩擦。 摩擦是阻碍变革的无形暗流。摩擦并非孤立存在的，而是一个系统性问题，其来源是人、团队与技术之间的关系。解决之道不在于 Kubernetes、云计算或人工智能，而在于改变我们的思维模式、沟通方式和组织架构。 本文描述了在每一个项目中都会反复出现的六种摩擦： 反直觉行为拒绝改变效率与控制产品与技术角色之间相互指责线性管道思维交付能力不足 每一种摩擦都让我们忙于重写相同的代码库或重绘相同的组织结构图。摩擦导致很多无益于我们避开冰山的工作浪费。这篇文章将帮助你弄清楚如何应对这些问题。 反直觉行为 我们怪错了对象。因此，我们做错了事情。 反直觉行为，由系统科学家 Jay Forrester 定义，是指复杂的社会和管理系统倾向于用让问题变得更糟糕的解决方案来应对问题。例如，为一个处于后期的项目增派更多的工程师，加快项目进度。 面对系统性挑战时，我们人类会倾向于指责他人。遗憾的是，我们怪错了对象。我们责怪工程团队工作效率低下，或者断定是因为团队太小，却未能意识到甘特图不过是虚构的简化模型，它过度简化了复杂的动态过程。 “任何系统的输出结果都是其内在设计的必然产物‌。”——W. Edwards Deming 当我们改变一个系统的运作方式时，我们也需要改变塑造系统的底层模式、结构和心智模型。例如，不是在本已臃肿的数据库上放上 GraphQL 就能称之为图，而是需要重新构建我们思考数据的方式。我们需要创建异步事件，而不是把什么都塞进管道，我们需要创建反馈循环，让我们能及时知道数据在跨系统移动时出现了异常。 这可以解释为什么工程师们会工作到很晚。他们一边忙着给猪涂口红，一边又要完成甘特图上没有预料到的工作。 解决之道：理解系统 反直觉行为具有引力，会将我们吸入其中，卷入漩涡。至少，我们的感受是这样：感觉像是在行动，在前进，而实际情况是，我们就像烘干机里的衣物，在原地打转。自始至终，我们都是从同一个狭小的视角凝视问题。 解决方法是暂时停下来，找准方向再行动。 首先是确定核心领域。系统的目标是什么？对于联邦快递来说，是快速递送包裹。很可能，你所经历的反直觉行为，源于人们的说法一致但前进方向不同。 每个参与的人都清楚变革与核心领域的关系吗？怎么才能加快包裹递送而不产生负面影响？系统本身如何导致了问题的产生？当前的流程和模式会产生什么样的心态？系统中的关系如何强化了这些模式？有什么你没有看到的变革需求吗？开始绘制这些模式，确定你的核心领域，所需的变革自然便会显现。 拒绝改变 每个试图变革的组织都有这样一些人：守门人、地牢主、自封的 10 倍速工程师，他们对组织非常了解，并且拥有一个魔法词：不。 他们说，“我们已经尝试过迁移。我们已经尝试过平台迁移或重构。我们已经尝试过重组。都行不通。别费心了。”他们掌握着生产环境或管道或某个关键系统的控制权，你没法忽视他们。 对此，人们很容易把责任归咎于那人的固执性格。但他展现的行为模式，正是长期的奖励与强化所形成的。通过管理遗留系统的复杂性，他已成为不可或缺的存在。要改变他，必须改变整个组织的思维方式，否则，又会冒出另一个类似的角色取而代之。仅靠技术手段无法从根本上解决问题。 拒绝改变是会传染的。当那个人关闭了好奇心，其他人也会转向固定思维模式。人们首先做的是怀疑而不是实验。组织无法在规避风险和尝试新事物之间找到平衡。变革陷入了停滞。 “变革之所以困难，是因为人们高估了他们所拥有的东西的价值，低估了他们放弃这些东西可能获得的价值。” ——《会飞的水牛：卓越腾飞，学会让员工引领》（Belasco 和 Stayer，1999 年） 解决之道：解雇那个人 好吧，这可能有点极端。你可能无法解雇他们，但你可以限制他们的影响。你不是他们的导师、母亲或心理医生。不要陷入那种角色。 把他们装进盒子里。给他们一个静态领域，让他们可以保留自…

基于 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-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…

开源一款以博客为名的 AI 增强创作与分享的工具
type: item
date: 2026-01-05T12:15:37+08:00
description: 哪天学不动技术了，写作仍然是我们必备的技能，我把写作当作一种自然语言编程，只要还能写，就还能产生成果。为此我开发了一款博客作为 MVP，试试当文章不再仅仅关注排版美化，而是作为一种 “意图指令” 时，会发生什么。项目地址：GitHub - code-gal/namblog: 一个致力于提升内容演示的博客系统。自由的写作，让 AI 生成页面。demo：https://namblog.nigzu.com当你提交一篇文档时，系统会根据你的指令 ——“生成一个交互式图表”、“设计一个沉浸式阅读页” 或 “构建一个带动画的卡片布局”—— 实时调用 AI 将 Markdown 编译为包含完整样式和脚本的 HTML 应用。这让 “写作” 的过程充满创意，从 md 到各个元数据提示词都是可以自定义的。虽然它的本意不是博客，但作为博客该有的功能基本都有了。后端架构： 基于 .NET 10 构建，采用 DDD（领域驱动设计）分层架构。数据查询： 全面采用 GraphQL，实现前端按需查询，摆脱预定义模板限制。实时反馈： 支持系统配置的热重载和前端及时反馈。体验融合： 单页应用（SPA）结构，支持 PWA 离线访问，同时兼顾 SEO 静态交付。开放生态： 支持 MCP 协议，支持从文档库自动扫描生成，可与 Claude、Obsidian 等工具深度集成。欢迎体验。📌 转载信息来源： https://linux.do/t/topic/1406605原作者： wumi转载时间： 2026/1/5 12:15:37