当 Andrew Harmel-Law 邀请演讲者参加 QCon 伦敦大会时，他首先想到的是：“让 Diana 和 Cat 一起登台！”这完全是出于一种顽皮的冲动。 Cat Morris 是一位产品经理。Diana Montalion 是一位系统架构师。我们都专门从事软件系统和平台开发。我们都把对方视为我们所有痛苦的根源。不是个人层面的，我们从未一起工作过，但我们都认为对方所代表的角色是问题所在。 但我们也致力于改善我们的工作方式。如果我们能够消除我们之间存在的摩擦……那对每个人来说都是一件好事，对吧？ 首先，我们对参与的每一个重大项目做了建模分析。我们发现，每一个项目的结局都像泰坦尼克号一样：撞上了冰山。 我们发现了以下这些改变职业生涯的真相： 我们的工作有很多重合的地方。我们需要彼此。合作会带来更好的结果。我们思考问题的方式不同但互补。我们要解决的不是技术问题。技术挑战不难解决。困难之处在于消除摩擦。 摩擦是阻碍变革的无形暗流。摩擦并非孤立存在的，而是一个系统性问题，其来源是人、团队与技术之间的关系。解决之道不在于 Kubernetes、云计算或人工智能，而在于改变我们的思维模式、沟通方式和组织架构。 本文描述了在每一个项目中都会反复出现的六种摩擦： 反直觉行为拒绝改变效率与控制产品与技术角色之间相互指责线性管道思维交付能力不足 每一种摩擦都让我们忙于重写相同的代码库或重绘相同的组织结构图。摩擦导致很多无益于我们避开冰山的工作浪费。这篇文章将帮助你弄清楚如何应对这些问题。 反直觉行为 我们怪错了对象。因此，我们做错了事情。 反直觉行为，由系统科学家 Jay Forrester 定义，是指复杂的社会和管理系统倾向于用让问题变得更糟糕的解决方案来应对问题。例如，为一个处于后期的项目增派更多的工程师，加快项目进度。 面对系统性挑战时，我们人类会倾向于指责他人。遗憾的是，我们怪错了对象。我们责怪工程团队工作效率低下，或者断定是因为团队太小，却未能意识到甘特图不过是虚构的简化模型，它过度简化了复杂的动态过程。 “任何系统的输出结果都是其内在设计的必然产物‌。”——W. Edwards Deming 当我们改变一个系统的运作方式时，我们也需要改变塑造系统的底层模式、结构和心智模型。例如，不是在本已臃肿的数据库上放上 GraphQL 就能称之为图，而是需要重新构建我们思考数据的方式。我们需要创建异步事件，而不是把什么都塞进管道，我们需要创建反馈循环，让我们能及时知道数据在跨系统移动时出现了异常。 这可以解释为什么工程师们会工作到很晚。他们一边忙着给猪涂口红，一边又要完成甘特图上没有预料到的工作。 解决之道：理解系统 反直觉行为具有引力，会将我们吸入其中，卷入漩涡。至少，我们的感受是这样：感觉像是在行动，在前进，而实际情况是，我们就像烘干机里的衣物，在原地打转。自始至终，我们都是从同一个狭小的视角凝视问题。 解决方法是暂时停下来，找准方向再行动。 首先是确定核心领域。系统的目标是什么？对于联邦快递来说，是快速递送包裹。很可能，你所经历的反直觉行为，源于人们的说法一致但前进方向不同。 每个参与的人都清楚变革与核心领域的关系吗？怎么才能加快包裹递送而不产生负面影响？系统本身如何导致了问题的产生？当前的流程和模式会产生什么样的心态？系统中的关系如何强化了这些模式？有什么你没有看到的变革需求吗？开始绘制这些模式，确定你的核心领域，所需的变革自然便会显现。 拒绝改变 每个试图变革的组织都有这样一些人：守门人、地牢主、自封的 10 倍速工程师，他们对组织非常了解，并且拥有一个魔法词：不。 他们说，“我们已经尝试过迁移。我们已经尝试过平台迁移或重构。我们已经尝试过重组。都行不通。别费心了。”他们掌握着生产环境或管道或某个关键系统的控制权，你没法忽视他们。 对此，人们很容易把责任归咎于那人的固执性格。但他展现的行为模式，正是长期的奖励与强化所形成的。通过管理遗留系统的复杂性，他已成为不可或缺的存在。要改变他，必须改变整个组织的思维方式，否则，又会冒出另一个类似的角色取而代之。仅靠技术手段无法从根本上解决问题。 拒绝改变是会传染的。当那个人关闭了好奇心，其他人也会转向固定思维模式。人们首先做的是怀疑而不是实验。组织无法在规避风险和尝试新事物之间找到平衡。变革陷入了停滞。 “变革之所以困难，是因为人们高估了他们所拥有的东西的价值，低估了他们放弃这些东西可能获得的价值。” ——《会飞的水牛：卓越腾飞，学会让员工引领》（Belasco 和 Stayer，1999 年） 解决之道：解雇那个人 好吧，这可能有点极端。你可能无法解雇他们，但你可以限制他们的影响。你不是他们的导师、母亲或心理医生。不要陷入那种角色。 把他们装进盒子里。给他们一个静态领域，让他们可以保留自己的脚本和遗留代码，而你去改变系统的其余部分。用“是”的力量去平衡他们“不”的力量。 是的，这并不意味着认同所有观点。这意味着探索可能性。将对话引向可以向前推进的方向。找到愿意做出改变的人，并帮助他们解决自己的问题，而不是等待守门人为他们开锁。 效率与控制 效率带来安全感。控制带来责任感。二者结合，便形成了现代组织中最诱人的反模式：效率与控制。 当它们占据主导地位时，我们关注的焦点便会缩小到产出：发布特性、关闭工单、满足截止日期。工作以速度来衡量，而不是价值。组织最小化互动和反思，坚信速度等于进步。 但在复杂的系统中，只讲效率会使系统变得脆弱。你按时交付了错误的东西。你得到了与蓝图相匹配的结果，但忽略了变化的环境。你得到了短期的解决方案，而那最终会成为未来的障碍。 我们制定了一个有预算有时间表的路线图，而唯一的上下文是一堆令人困惑的架构。 要求我们增加控制，但又理不清头绪。效率不过是掩盖混乱的遮羞布。其结果是一场组织作秀：Jira 工单、自信满满的时间表，以及追踪一切却唯独忽略意义的指标。 截止日期不可更改。功能已锁定。缺的是什么呢？一个明确的目标和协同一致的成果，同时又留有空间，允许在学习过程中进行调整。包裹配送时间没有改善，客户体验也未见提升。 解决之道：设计知识流 让团队注重效能而非过度追求效率。如何确保时间、精力和注意力都用在塑造真正重要的成果上？用协同取代控制：建立能让正确信息在正确时间传递给正确人员的工作机制，让信息跨越边界自由流动，无需高管做微观管理。 思考你目前正在开展的项目。你是在度量产出还是成果？截止日期是反映了现实还是一厢情愿的想法？如何改善信息流，而不是构建一个工厂式的交付过程？做工作与交付价值不是一回事；改善知识流能让你更快地获得价值。 产品 vs. 技术 Andrew 让我们聚在一起，因为我们有类似的挫败感。我们都面临着用 Kubernetes 解决系统性问题的压力。当然，我们做不到。我们也因为反直觉行为，养成了互相指责对方角色的习惯。 工程团队不喜欢产品经理给他们施加压力，要求他们在一个紧迫的时间表内完成特性交付。他们不明白，他们正在做的改变怎么能提高代码质量。基础设施、架构和 DevSecOps 人员则抱怨说，他们需要的改进从未被优先考虑。 产品团队不喜欢工程师表现出的抵触和消极态度。他们不明白，为什么一些简单的事情需要那么长时间来构建。他们抱怨说，过度工程化浪费了大量的会议时间，而那些时间本来可以用在寻找前进的方法上。 在许多组织中，产品和工程是相互隔离的孤岛。双方对效率与控制的定义截然不同，成了两股相互对立的势力。产品部门只需将需求抛过隔离墙，便坐等可运行的代码返回；而工程部门则被要求加快编码速度，无暇顾及系统设计。 即使这两个角色坐在一起，他们相互冲突的方法和控制欲也会加剧摩擦。 解决之道：向学习驱动型转变 Carol Dweck 博士描述了两种心态：固定型和成长型。 固定型心态认为，擅长某事就意味着那件事应该很容易做到。如果某事很难，则说明你缺乏天赋。在这种模式下，人们会回避挑战，将反馈视为批评，将他人的成功视为威胁。其结果是团队很脆弱，他们要保护自己的地盘，而不是一起学习。 成长型心态认为，能力可以通过实践、反馈和坚持来提升。你不能只是做 Netflix 所做的事。在这种模式下，人们欢迎挑战，将努力视为精通之道，将挫折当作改进的数据基础。其结果是个人和团队都更有韧性，他们会适应而不是抵触。 当每个人，无论什么角色，都采用成长型思维时，他们就会一起学习。同理心是一项关键能力。它不同于单纯的同情，而是从多个角度理解情境的能力——对用户和代码的影响；产品团队与技术团队之间的流程和协作模式所导致的顽固问题。 为了共同做出有影响力的决策，我们需要成长型思维，借鉴他人的经验来丰富我们的世界观，并引导自己获得更深刻的洞察力。 线性管道思维 还记得过去软件中某个地方有 Bug 的日子吗？修复一行代码就能解决问题。现在，在微服务和分布式系统构成的复杂世界中，Bug 通常存在于各部分之间的关联关系中。系统架构的艺术和科学在于设计和编排。 每天，我们都会经历摩擦，因为我们在一个异步世界中交付线性管道。或许我们称其为平台，但真正的平台是精心设计的不同技术与流程之间的关联体系。它们能用不同的方式响应不同时间发生的各类事件。平台的各部分相互协同，达成单个组件无法独立实现的成果。这种现象被称为涌现（emergence）。 面向涌现的设计需要综合多方视角，理解如何调整整个系统以实现包裹快速配送，而又不破坏异步关系。 综合意味着不能单打独斗。你需要其他人贡献他们的专业知识，并将这些专业知识与你的知识整合在一起。当我们无法构建能整合组织知识与经验的实践体系时……我们就无法设计（或调试）平台。于是我们交付了一条管道，而所有人都将它的缺陷归咎于不充分。 解决之道：构建关系 与其用线性思维处理异步情境，不如退一步思考以下问题： 在你的系统中，关系如何产生效果？系统各部分之间如何通过关系实现它们不直接做的事情？信息如何在技术系统中流动？痛点和瓶颈在哪里，以及如何优化关系以消除这些阻碍？ 如果你的组织不支持这项工作，就组建一个秘密小组。无论身处何种角色，都要将多元视角融入建议的更改方案中。确保信息在人员之间顺畅流动，从而实现服务之间的无缝衔接。 当具有不同观点的团队（如架构师 Diana 和产品经理 Cat）共同构建这些模式时，一切都会变得更加轻松。与其他团队交流，观察用户使用系统的过程，向基础设施团队了解他们的痛点，并将这些洞察融入解决方案之中。 交付能力不足 我们以为我们专注于目标，而实际上我们是在专注于需求。目标是一个可衡量的成果，比如，提高包裹递送速度。如果我们提高了系统的能力，我们就实现了目标，而不是简单地添加另外一项功能。 对于内部平台团队而言，一个可能的例子是：团队被告知需将软件部署管道从 Jenkins 迁移至 CircleCI。这明确告知了操作步骤，却未说明迁移背后的原因。 这里的隐藏目标是将开发者的管道维护工作量减少百分之五十。没有这些信息，团队可能会迁移了软件交付管道却没有达到预期的结果。他们也可能有一些想法，不需要昂贵的管道迁移就能实现目标。 部署变更的能力早就已经存在。在这种情况下，交付流程会频繁出现各种断层。对于如何部署变更，每个人都有不同的想法。如果关注点是改变工具，那么这些想法将导致无尽的摩擦。 解决之道：专注于目标 制定有意义的目标，并整合实现目标的各种方案。描述需要交付的具体且可衡量的效益或成果。确保目标紧密契合核心领域，即加速包裹配送。系统的所有功能都应该服务于这个目标。每次部署变更时，我们（期望）都在提升系统履行职责的能力。聚焦目标能确保每位贡献者都理解自身工作的价值。 去尝试 现在，你可能感到不知所措。“我做不到这一切！我的工作已经很忙了！”这是真的。 幸运的是，你不需要全都做。选一件事来做就行。一个可以减少摩擦的小变革，可以是你最感兴趣的事情，也可以是给你的日常生活造成最大摩擦的事情。 系统就是这样工作的……小变革可以扩展为大改进。摩擦在细节中，解决之道也在细节中。原文链接：https://www.infoq.com/articles/friction-fix/
基于 Pydantic-Resolve 和 FastAPI-Voyager 的 Clean Architecture 实践 -- 一套面向复杂业务场景的 Python Web 开发方法论
基于 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_id}", response_model=TeamDetail) async def get_team(team_id: int, session: AsyncSession = Depends(get_session)): # 获取团队基本信息 team = await session.get(Team, team_id) # 获取 Sprint 列表 sprints = await session.execute( select(Sprint).where(Sprint.team_id == team_id) ) team.sprints = sprints.scalars().all() # 获取每个 Sprint 的 Story for sprint in team.sprints: stories = await session.execute( select(Story).where(Story.sprint_id == sprint.id) ) sprint.stories = stories.scalars().all() # 获取每个 Story 的 Task for story in sprint.stories: tasks = await session.execute( select(Task).where(Task.story_id == story.id) ) story.tasks = tasks.scalars().all() # 获取每个 Task 的负责人 for task in story.tasks: task.owner = await session.get(User, task.owner_id) return team 这种做法在简单场景下确实很直观，能够快速上手。ORM 的类型安全特性也能在编译时发现一些错误，而且与数据库表结构的一一对应关系让代码容易理解。但当我们面对真正的业务场景时，这种方式的缺陷很快就暴露出来了。最致命的问题是 N+1 查询。虽然代码看起来很清晰，但执行时会产生大量的数据库查询。每当我们访问一个关联关系时，ORM 就会发起一次新的查询。在深层嵌套的情况下，查询数量会呈指数级增长。更糟糕的是，这种性能问题在开发阶段不容易发现，只有当数据量积累到一定程度后才会显现出来，那时候往往已经太晚了。代码的组织方式也是个问题。数据获取的逻辑散落在各个嵌套的循环中，业务逻辑和数据获取逻辑混在一起，难以阅读和维护。当需要修改业务规则时，开发者不得不在复杂的嵌套结构中寻找修改点，很容易引入新的 bug 。性能更是不可控，随着数据量的增长，查询效率会急剧下降，而这些性能瓶颈很难在代码层面直接观察到。此外，相似的数据获取逻辑会在多个 API 中重复出现，导致大量代码冗余。当一个 API 需要获取"团队及其 Sprint"，另一个 API 需要"团队及其成员"时，即使它们的查询逻辑非常相似，也不得不重复编写。这违反了 DRY （ Don't Repeat Yourself ）原则，增加了维护成本。模式二：使用 ORM 的 Eager Loading@router.get("/teams/{team_id}", response_model=TeamDetail) async def get_team(team_id: int, session: AsyncSession = Depends(get_session)): # 使用 joinedload 预加载关联数据 result = await session.execute( select(Team) .options( joinedload(Team.sprints) .joinedload(Sprint.stories) .joinedload(Story.tasks) .joinedload(Task.owner) ) .where(Team.id == team_id) ) return result.scalar_one() 为了解决 N+1 查询问题，ORM 提供了 Eager Loading 机制，让我们可以通过 joinedload、selectinload 等方式预先加载关联数据。代码变得更简洁了，性能问题也得到了缓解。但这种方案也带来了新的挑战。最明显的问题是笛卡尔积。当我们使用多层 JOIN 预加载关联数据时，数据库返回的数据量会急剧膨胀。比如一个团队有 10 个 Sprint ，每个 Sprint 有 10 个 Story ，每个 Story 有 10 个 Task ，那么 JOIN 的结果集会包含 1000 行数据，即使每行的数据量不大，也会给网络传输和内存占用带来压力。更严重的问题是灵活性差。Eager Loading 的策略是在代码中硬编码的，所有使用同一个 Model 的 API 都会执行相同的预加载逻辑。但不同的 API 往往需要不同的数据。比如一个 API 只需要团队的基本信息，另一个 API 需要团队的 Sprint ，还有一个 API 需要团队的成员。如果统一使用 Eager Loading 加载所有关联数据，就会出现过度获取的问题，前端不需要的数据也被查询和传输了，浪费了资源。配置 Eager Loading 本身就很复杂。开发者需要理解 lazy、joinedload、selectinload、subquery 等多种加载策略的区别，知道什么时候用哪一种，以及它们各自会有什么副作用。这种配置错误很容易导致性能问题或意外的数据加载行为。而且，这种"一刀切"的配置方式意味着所有 API 都使用相同的加载策略，无法针对特定场景进行优化。模式三：手动组装数据@router.get("/teams/{team_id}", response_model=TeamDetail) async def get_team(team_id: int, session: AsyncSession = Depends(get_session)): # 1. 批量获取所有需要的数据 team = await session.get(Team, team_id) sprints_result = await session.execute( select(Sprint).where(Sprint.team_id == team_id) ) sprint_ids = [s.id for s in sprints_result.scalars().all()] stories_result = await session.execute( select(Story).where(Story.sprint_id.in_(sprint_ids)) ) story_ids = [s.id for s in stories_result.scalars().all()] tasks_result = await session.execute( select(Task).where(Story.id.in_(story_ids)) ) tasks = tasks_result.scalars().all() owner_ids = list(set(t.owner_id for t in tasks)) owners_result = await session.execute( select(User).where(User.id.in_(owner_ids)) ) owners = {u.id: u for u in owners_result.scalars().all()} # 2. 手动组装数据结构 sprint_dict = {s.id: s for s in sprints_result.scalars().all()} story_dict = {s.id: s for s in stories_result.scalars().all()} for story in story_dict.values(): story.tasks = [t for t in tasks if t.story_id == story.id] for task in story.tasks: task.owner = owners.get(task.owner_id) for sprint in sprint_dict.values(): sprint.stories = [s for s in story_dict.values() if s.sprint_id == sprint.id] team.sprints = list(sprint_dict.values()) return team 为了获得最优的性能和精确的数据控制，有经验的开发者会选择手动组装数据。这种方式完全掌控查询逻辑，可以精确控制每个查询的 SQL 语句，避免不必要的数据库访问。通过批量查询和智能的数据组装，可以获得最佳的性能，而且没有冗余数据。但这种方式的代价是代码变得非常冗长。如上面的例子所示，为了获取一个团队的完整信息，我们需要编写多个查询，手动构建数据字典，然后通过嵌套循环组装数据。代码的长度和复杂度都大幅增加，而真正表达业务逻辑的代码反而被淹没在数据组装的细节中。更容易出错也是个大问题。手动组装数据涉及到大量的索引操作和循环嵌套，很容易出现索引错误、空指针引用等 bug 。而且这些错误往往只有在运行时、特定数据条件下才会暴露，难以在开发阶段发现。维护成本更是高昂。当业务规则发生变化时（比如需要添加一个新的关联关系），开发者需要在所有相关的 API 中修改数据组装逻辑。如果遗漏了某个地方，就会导致数据不一致。而且，相似的数据组装逻辑会在多个 API 中重复出现，违反了 DRY 原则。最根本的问题是，这种代码已经变成了纯粹的数据搬运工，看不出任何业务意图。代码中充满了字典操作、循环嵌套、索引查找，而这些都是技术细节，与业务需求毫无关系。新加入的团队成员很难从这些代码中理解业务逻辑，业务知识的传递变得异常困难。模式四：使用 GraphQLtype Query { team(id: ID!): Team } type Team { id: ID! name: String! sprints: [Sprint!]! } type Sprint { id: ID! name: String! stories: [Story!]! } type Story { id: ID! name: String! tasks: [Task!]! } type Task { id: ID! name: String! owner: User! } GraphQL 确实是一个很有吸引力的方案。前端可以按需获取数据，需要什么字段就查什么字段，不会有过度获取的问题。它提供了类型安全的查询接口，而且通过 DataLoader 可以自动解决 N+1 查询问题。这些特性让 GraphQL 在前端开发中广受欢迎。但 GraphQL 的学习曲线非常陡峭。开发者需要学习全新的查询语言、Schema 定义、Resolver 编写、DataLoader 配置等一堆概念，这与 REST API 的直观性形成了鲜明对比。更麻烦的是，GraphQL 的过度灵活性给后端带来了巨大的挑战。前端可以构造任意复杂的查询，有些查询甚至可能是开发者没有想到过的，这导致后端很难进行针对性的优化。当一个查询嵌套了 10 层，返回了数百万条数据时，数据库和服务器都会面临巨大的压力。调试 GraphQL API 也比调试 REST API 复杂得多。当一个 GraphQL 查询出错时，错误信息往往很难定位到具体的问题源头。而且 GraphQL 需要额外的服务器和工具链支持，无法直接利用现有的 FastAPI 生态系统。比如 FastAPI 的依赖注入、中间件、自动文档生成等特性，在 GraphQL 中都无法直接使用。还有一个更深层次的问题是 ERD 和用例的界限模糊。GraphQL 的 Schema 同时扮演了实体模型和查询接口两个角色。当我们设计一个 GraphQL Schema 时，很难确定应该按照实体来组织（一个 Type 对应一个数据库表），还是按照用例来组织（不同的业务场景需要不同的字段）。这导致最佳实践不清晰，不同的项目、不同的开发者可能有完全不同的组织方式。而且随着业务增长，所有的用例都会堆砌在同一个 Schema 中，导致 Schema 膨胀，难以维护。权限控制也变得异常复杂。不同的 API 端点可能有不同的权限要求，但它们可能都查询同一个实体（比如 User ），在 GraphQL 中很难针对不同的查询场景应用不同的权限规则。1.2 问题根源分析上面我们探讨的所有模式，虽然表面上的问题各不相同，但它们的核心困境其实是一致的。问题 1：业务模型与数据模型混淆# SQLAlchemy ORM 同时扮演两个角色： # 1. 数据模型（如何存储） # 2. 业务模型（业务概念） class Team(Base): __tablename__ = 'teams' id = Column(Integer, primary_key=True) name = Column(String) # 这是数据库的外键关系，还是业务关系？ sprints = relationship("Sprint", back_populates="team") 在传统的 ORM 开发中，业务模型和数据模型是混在一起的。看看这个例子，Team 类既表达了业务概念（团队是什么），又承载了数据模型的细节（如何在数据库中存储）。当我们在 sprints 字段上定义 relationship 时，这到底是在描述一个业务关系（团队有多个 Sprint ），还是在声明一个数据库外键约束？这种模糊性会导致很多问题。数据库的设计约束会直接影响我们的业务建模。比如，如果数据库中的 teams 表没有直接到 users 的外键，而是通过中间表 team_members 关联，那么在 ORM 中我们也必须通过这个中间表来定义关系。这意味着业务模型被迫适应数据库的实现细节，而不是反过来。更严重的是，这种方式无法表达跨库、跨服务的业务关系。现代系统中，数据可能分布在不同的数据库中，甚至存储在外部服务里。比如用户的基本信息在 PostgreSQL ，而用户的偏好设置在 MongoDB ，用户的实时状态在 Redis 中。ORM 的 relationship 无法跨越这些边界，业务模型因此被限制在了单一数据库的范围内。问题 2：依赖方向错误传统架构的依赖方向： ┌─────────────┐ │ API Layer │ ← 依赖于 └──────┬──────┘ │ ↓ ┌─────────────┐ │ ORM Models │ ← 依赖于 └──────┬──────┘ │ ↓ ┌─────────────┐ │ Database │ └─────────────┘ 问题：业务规则依赖于数据库实现！ 这违反了 Clean Architecture 的依赖规则。正确的依赖关系应该是：业务规则最稳定，不依赖任何外层；数据库是实现细节，应该依赖业务规则；当数据库变化时，业务规则不应该受影响。但传统架构的依赖方向恰恰相反，业务规则被数据库的实现细节所绑架。问题 3：缺少业务关系的显式声明# 传统方式：业务关系隐藏在查询中 async def get_team_tasks(team_id: int): # "团队的任务"这个业务概念隐藏在 SQL WHERE 中 result = await session.execute( select(Task) .join(Sprint, Sprint.id == Task.sprint_id) .where(Sprint.team_id == team_id) ) return result.scalars().all() 业务关系没有被显式声明出来，这是个很隐蔽但危害很大的问题。看看这个例子，"团队的任务"是一个清晰的业务概念，但这个概念被隐藏在 SQL 的 JOIN 和 WHERE 子句中。新加入团队的成员需要阅读大量代码才能理解系统中有哪些业务关系，这些关系是如何定义的。更糟糕的是，没有自动化的方式来检查业务关系的一致性。当需求变化需要修改某个关系时，开发者很难找到所有相关的代码，很容易遗漏某个地方，导致业务逻辑的不一致。问题 4：中间表的技术暴露在 SQLAlchemy ORM 中，多对多关系需要显式定义中间表，这导致技术细节泄漏到业务层。# SQLAlchemy ORM：必须定义中间表 class Team(Base): __tablename__ = 'teams' id = Column(Integer, primary_key=True) name = Column(String) # ORM relationship 需要指定中间表 members = relationship("User", secondary="team_members", # 必须指定中间表 back_populates="teams") class User(Base): __tablename__ = 'users' id = Column(Integer, primary_key=True) name = Column(String) teams = relationship("Team", secondary="team_members", # 必须指定中间表 back_populates="members") # 中间表（技术实现细节） class TeamMember(Base): __tablename__ = 'team_members' team_id = Column(Integer, ForeignKey('teams.id'), primary_key=True) user_id = Column(Integer, ForeignKey('users.id'), primary_key=True) role = Column(String) # 可能还有额外字段 # 查询时需要关心中间表的存在 @router.get("/teams/{team_id}") async def get_team_members(team_id: int, session: AsyncSession): # 必须通过中间表查询 result = await session.execute( select(User) .join(TeamMember, TeamMember.user_id == User.id) # 中间表暴露 .where(TeamMember.team_id == team_id) ) return result.scalars().all() 这个问题的根源在于，ORM 的多对多关系需要显式定义中间表，这导致技术细节直接泄漏到业务层代码中。业务代码必须知道 team_members 中间表的存在，查询时也需要显式地 join 这个中间表。这增加了代码复杂度，更重要的是，业务逻辑被数据库的实现细节所绑架。更深层的问题是业务语义变得模糊。TeamMember 到底是一个有意义的业务概念，还是纯粹的技术实现？如果中间表还有额外的字段（比如 role 表示用户在团队中的角色，joined_at 表示加入时间），这些字段应该被建模为独立的实体吗？不同的开发者可能给出不同的答案，缺乏统一的指导原则。数据组装也因此变得复杂。查询"团队的所有成员"需要 join 中间表，查询"用户所属的团队"也需要 join 中间表。所有涉及多对多关系的查询都变得冗长和难以理解。当业务规则要求"获取用户在所有团队中的角色"时，情况就更加复杂了。这些技术细节让业务逻辑的实现变得异常沉重。对比：Pydantic-Resolve ERD 的方式# ERD：业务概念清晰，无需关心中间表 class TeamEntity(BaseModel, BaseEntity): """团队实体 - 业务概念""" __relationships__ = [ # 直接表达"团队有多个成员"的业务关系 Relationship( field='id', target_kls=list[UserEntity], loader=team_to_users_loader # loader 内部处理中间表 ), ] id: int name: str class UserEntity(BaseModel, BaseEntity): """用户实体 - 业务概念""" __relationships__ = [ # 直接表达"用户属于多个团队"的业务关系 Relationship( field='id', target_kls=list[TeamEntity], loader=user_to_teams_loader ), ] id: int name: str # Loader 实现细节：中间表只在这里出现 async def team_to_users_loader(team_ids: list[int]): """加载团队成员 - 内部处理中间表""" async with get_session() as session: # 只有这里需要知道中间表的存在 result = await session.execute( select(User) .join(TeamMember, TeamMember.user_id == User.id) .where(TeamMember.team_id.in_(team_ids)) ) users = result.scalars().all() # 构建映射 users_by_team = {} for user in users: for tm in user.team_memberships: if tm.team_id not in users_by_team: users_by_team[tm.team_id] = [] users_by_team[tm.team_id].append(user) return [users_by_team.get(tid, []) for tid in team_ids] 关键差异： 维度 SQLAlchemy ORM Pydantic-Resolve ERD 中间表位置 暴露在业务层 隐藏在 loader 实现中 业务语义 技术关系 (secondary) 业务关系 (团队包含成员) 查询代码 需要 join 中间表 loader.load(team_id) 代码位置 分散在多处 集中在 loader 测试 依赖数据库表结构 可 mock loader 架构优势：传统方式： Team → TeamMember (中间表) → User 业务层需要知道中间表的存在 Pydantic-Resolve 方式： Team → User (业务关系) 中间表是数据层的实现细节，业务层不关心 这意味着： 业务模型纯净：Team 和 User 的关系直接表达业务语义 技术细节封装：中间表的存在被封装在 loader 中 灵活的存储策略： 数据库可以用中间表实现 也可以用 JSON 字段存储 甚至可以是外部服务（如 LDAP ） 业务层代码无需修改 易于理解：新人看到 ERD 就能理解业务关系，不需要先学习数据库设计 2. Clean Architecture 思想2.1 核心原则Clean Architecture 由 Robert C. Martin (Uncle Bob) 提出，核心思想是："Software architecture is the art of drawing lines that I call boundaries." 软件架构的艺术在于画界线。原则 1：依赖规则外层依赖内层，内层不依赖外层。 ↓ 依赖方向 ┌─────────────────────┐ │ Frameworks & │ 外层 │ Drivers │ (实现细节) ├─────────────────────┤ │ Interface │ │ Adapters │ ├─────────────────────┤ │ Use Cases │ │ (Application) │ ├─────────────────────┤ │ Entities │ 内层 │ (Business Rules) │ (核心) └─────────────────────┘ 遵循依赖规则有几个关键点需要注意。首先，内层不知道外层的存在，这意味着核心业务逻辑不依赖于任何框架、数据库或 UI 的细节。其次，内层不包含外层的信息，比如业务规则不应该知道数据是用 PostgreSQL 还是 MongoDB 存储的。最后，外层的实现可以随时替换而不影响内层，这意味着我们可以从 SQLAlchemy 切换到 MongoDB ，或者从 FastAPI 切换到 Django ，而业务逻辑代码无需修改。原则 2：业务规则独立# ❌ 错误：业务规则依赖数据库 class Task: def calculate_priority(self, session): # 业务逻辑被数据库实现细节污染 if self.assignee_id in session.query(TeamMember).filter_by(role='lead'): return 'high' # ✅ 正确：业务规则独立 class Task: def calculate_priority(self, assignee_roles): # 业务逻辑只依赖业务概念 if 'lead' in assignee_roles: return 'high' 原则 3：跨边界的数据传递# 内层定义数据结构 class TaskEntity(BaseModel): id: int name: str assignee_id: int # 外层负责转换 def task_entity_to_orm(entity: TaskEntity) -> Task: return Task( id=entity.id, name=entity.name, assignee_id=entity.assignee_id ) 2.2 依赖规则在 Web 开发中，依赖规则可以这样理解：┌────────────────────────────────────────────────────┐ │ Presentation Layer (外层) │ │ - FastAPI Routes │ │ - Request/Response Models │ │ - 依赖: Application Layer │ └────────────────────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────┐ │ Application Layer (Use Cases) │ │ - 业务用例（获取用户、创建订单） │ │ - 依赖: Domain Layer │ └────────────────────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────┐ │ Domain Layer (内层) │ │ - Entities (业务实体) │ │ - Business Rules (业务规则) │ │ - Value Objects (值对象) │ │ - 不依赖任何外层 │ └────────────────────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────┐ │ Infrastructure Layer (最外层) │ │ - Database (SQLAlchemy) │ │ - External Services │ │ - File System │ └────────────────────────────────────────────────────┘ 关键洞察： Entities 不应该知道 SQLAlchemy 的存在 Business Rules 不应该知道数据库表结构 Use Cases 不应该知道 HTTP 协议的细节 2.3 在 Web 开发中的应用传统架构的问题# 传统方式：所有层次耦合 # Domain Layer (应该独立，但实际上依赖了 ORM) class User(Base): # ← SQLAlchemy Base __tablename__ = 'users' id = Column(Integer, primary_key=True) # Application Layer (应该只依赖 Domain ，但直接使用了 ORM) async def create_user(data: dict, session: AsyncSession): user = User(**data) # ← 直接使用 ORM Model session.add(user) await session.commit() # Presentation Layer @router.post("/users") async def api_create_user(data: dict, session=Depends(get_session)): return await create_user(data, session) # ← 暴露了数据库细节 这段代码暴露了传统架构的核心问题。SQLAlchemy 虽然建立了对象关系映射（ ORM ），让数据库表可以通过 Python 对象来操作，但这种映射关系过于紧密。ORM Model 既承担了数据持久化的职责，又要表达业务概念，导致对象无法自由地代表业务模型。业务实体被数据库的实现细节所绑架，每个字段、每个关系都必须与数据库表结构一一对应，完全失去了作为独立业务概念存在的自由。更深层次的问题包括： Domain Layer 被 SQLAlchemy 绑定：业务实体继承了 SQLAlchemy 的 Base ，无法独立于数据库存在 业务逻辑无法脱离数据库测试：编写单元测试时必须启动完整的数据库环境，大大降低了测试效率 切换数据库需要修改所有层：当从 PostgreSQL 迁移到 MongoDB 时，所有使用 ORM Model 的代码都需要重写 。。。
开源一款以博客为名的 AI 增强创作与分享的工具
哪天学不动技术了，写作仍然是我们必备的技能，我把写作当作一种自然语言编程，只要还能写，就还能产生成果。为此我开发了一款博客作为 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