《电商系统架构设计与实现》

面向中大型团队的实战指南

最后更新: 2026-04-18

项目简介

本书是基于作者多年电商系统开发经验，系统梳理电商平台架构设计与工程实践的技术专著。全书以理论与实践结合、架构与代码并重的方式，深入讲解从领域建模到系统落地的完整过程。

定位：

• 工程实践指南：提供可落地的实现方案和代码示例
• 架构设计参考：讲解架构决策过程和系统边界划分

适合读者：

• 中高级后端工程师（3-8年经验）
• 准备系统设计面试的候选人
• 电商/O2O 领域的架构师
• 希望系统学习 DDD 和 Clean Architecture 的开发者

内容结构

全书分为三大部分，共 17 章：

第一部分：架构设计方法论（6章）

• 第1章：架构师的组合拳
• 第2章：业务边界与战略设计
• 第3章：系统内部结构设计
• 第4章：系统集成与一致性设计
• 第5章：编码原则与设计模式
• 第6章：架构质量保障

第二部分：电商核心系统设计（10章）

Part A：全局架构

• 第7章：电商系统全景图

Part B：商品供给与运营

• 第8章：商品中心系统
• 第9章：库存系统
• 第10章：营销系统
• 第11章：商品供给管理：运营、库存与生命周期

Part C：交易链路

• 第12章：计价系统（基础模块：PDP/购物车/创单/支付全链路试算）
• 第13章：搜索与导购
• 第14章：购物车与结算
• 第15章：订单系统
• 第16章：支付系统

第三部分：综合案例与落地（1章）

• 第17章：B2B2C 平台完整架构（200人团队、日订单200万）

核心特色

1. 理论与实践深度结合

• 每个系统都讲解架构设计思路和具体实现方案
• 提供 Go 语言的生产级代码示例
• 包含真实案例和踩坑经验

2. 系统边界与集成贯穿始终

• 每个核心系统章节都有**“系统边界与职责”**小节
• 详细讲解与其他系统的集成模式和契约
• 提供集成失败处理和降级策略

3. 完整的知识体系

• 从方法论（Clean Architecture + DDD + CQRS）
• 到核心系统（商品、库存、订单、支付等10个系统）
• 再到综合案例（200人团队的 B2B2C 平台）

4. 面试与工程双重价值

• 涵盖系统设计面试的高频考点
• 提供工程落地的实战方案
• 附录包含面试题精选、集成模式速查表、商品供给与运营治理平台和供应商数据同步链路完整案例

预期篇幅

850-950 页，包含：

• 核心正文：约 750 页
• 附录（技术选型、面试题、术语表等）：约 100 页

当前进度：已完成约 15 万字（17 章），预计占正文的 50-60%

相关资源

GitHub 仓库

开源地址：github.com/wxquare/wxquare.github.io

仓库内容：

• 书籍完整内容（Markdown 格式）
• 配套代码示例（Go 语言）
• 架构图源文件
• 勘误与讨论（Issues）

博客文章

本书的很多内容源自博客文章，可以提前阅读：

• 电商系统设计系列
• 架构与整洁代码系列

许可协议

本书计划采用 CC BY-NC-SA 4.0（署名-非商业性使用-相同方式共享）协议开源：

• 可以自由阅读和分享
• 可以用于学习和教学
• 不可用于商业出版（需获得授权）

最后更新时间：2026-04-23
当前状态：已完成 17 章（第1-17章），共计约 150,000 字
最新进展：第一部分目录结构已重排，第二部分（电商核心系统设计）全部完成！

导航：书籍主页 | 完整目录 | 下一章：第2章

第1章 架构师的组合拳

复杂系统设计的方法论地图

1.1 软件架构的本质挑战

对一个做了 8 年左右后端或系统设计的工程师来说，软件架构真正难的地方，通常不是“有没有听过某个名词”，而是你会一遍又一遍遇到同一类问题：业务越来越复杂，团队越来越大，系统之间的调用越来越多，查询越来越重，规则越来越碎，而每一次新需求都在把这些问题继续放大。

很多人第一次认真接触架构，往往是从技术概念开始的：分层、DDD、CQRS、事件驱动、六边形架构、Clean Architecture。但真正在项目里工作几年之后，你会慢慢发现，架构设计并不是在概念之间“站队”，而是在不断回答几个非常现实的问题：

• 业务边界到底应该怎么划，才能避免概念混乱？
• 服务内部应该怎么组织，才能扛住持续变化？
• 系统拆开之后，彼此之间怎么协作才不会越来越乱？
• 代码怎么写、评审怎么做、上线怎么控，才能让设计不在落地时变形？

也正因为如此，本章并不打算把几个流行概念逐一解释一遍，而是想先做一件更重要的事：从工程实践的角度，沉淀软件架构面对的本质挑战，再引出架构师通常会如何打出一套“组合拳”来应对这些挑战。

1.1.1 为什么软件架构问题总会反复出现

软件架构之所以让人反复感到“似曾相识”，是因为很多系统最终都会落进相同的复杂性轨道。

项目刚开始时，大家通常只觉得“先把功能做出来”最重要。于是一个订单服务里，先有了下单接口，再加上支付回调、取消订单、超时关单、库存预占、营销校验、事件通知。前几个月看起来一切都还可控，但只要系统开始承接更多业务，问题就会陆续出现：

• 原本只有几条状态流转，后来变成十几种特殊流程
• 原本只有一个团队维护，后来变成多个团队协作
• 原本只需要简单查询，后来页面需要展示越来越多聚合信息
• 原本只改一处代码就够，后来一个需求要改接口、应用层、数据库、缓存和消息逻辑

这些问题反复出现，不是因为团队不努力，也不是因为某个框架选错了，而是因为复杂性会自然增长。如果没有一套稳定的边界、结构和协作方式，系统最终都会从“能跑”走向“难改”，再从“难改”走向“没人敢动”。

从这个角度看，架构设计并不是锦上添花，它更像是在系统复杂性不断上升时，为团队建立一套能够持续控住复杂性的秩序。

1.1.2 复杂系统的四类核心矛盾

如果把这些年在项目里反复遇到的问题抽象一下，大多数复杂系统最终都会面对四类矛盾。

第一类矛盾：业务复杂性不断上升

• 商品、订单、库存、支付、营销之间的边界到底怎么划？
• 同一个“订单”“商品”“价格”概念，在不同团队和不同系统里是否还是同一个意思？
• 规则越来越多之后，它们到底应该落在流程里、模型里，还是散落在各个 Service 里？

第二类矛盾：系统必须持续应对变化

• 业务规则会变，促销玩法会变，履约流程会变
• 技术栈也会变，数据库、框架、消息中间件都可能调整
• 如何让这些变化被限制在局部，而不是每次都牵动整条链路？

第三类矛盾：多人协作需要统一认知

• 50+ 开发者同时开发，如何降低彼此干扰？
• 产品、运营、业务专家和开发是否真的在使用同一套语言？
• 新成员加入时，是否能快速理解系统边界和核心规则？

第四类矛盾：性能、一致性与可维护性彼此拉扯

• 查询希望越快越好，往往需要宽表、缓存、搜索和反范式化
• 写入希望越稳越好，往往需要事务、一致性和严格规则保护
• 如果为了性能不断破坏模型，系统会变脏；如果为了模型纯净牺牲响应能力，业务体验又会变差

这些矛盾单独看都不新鲜，但真正困难的地方在于：它们几乎总是一起出现。这也是为什么软件架构很少有“一招鲜”，而更像是一套围绕不同问题分层出招的组合动作。

1.1.3 电商系统为什么是观察架构问题的最佳样本

电商系统之所以适合拿来讨论架构，不是因为它更“高级”，而是因为它几乎天然把前面四类矛盾全部放大了。

从业务上看，电商系统同时涉及商品、库存、计价、营销、订单、支付、履约、售后，业务规则彼此交叉，非常容易出现边界模糊和语义冲突。

从流量上看，商品详情、搜索、列表页有很高的读压力；下单、支付、库存扣减等链路又对一致性极其敏感。这意味着系统既要面对高并发，又不能把正确性让位给性能。

从组织上看，电商项目通常不是一个小团队就能长期覆盖的。商品团队、营销团队、交易团队、支付团队、履约团队会围绕同一个平台长期协作。边界一旦划不清，协作成本会非常快地吞掉研发效率。

也正因为如此，电商系统非常适合拿来回答这样一个问题：面对真实复杂系统，架构师到底需要哪些方法论，它们分别在什么阶段解决什么问题？

1.2 架构师如何应对这些挑战

如果说上一节回答的是“问题到底是什么”，那么这一节要回答的是另一个更重要的问题：架构师通常会按什么顺序来应对这些问题？

在真实项目中，成熟的架构设计很少是“先选一个流行概念，再把所有问题往里塞”。更常见的做法是按问题的层次逐步处理：先确定边界，再稳定内部结构，再设计系统之间的协作方式，最后用代码规范和质量机制把这套设计守住。

这也是本书第一部分的主线。

1.2.1 先做业务边界

复杂系统最先要解决的，通常不是“选哪种分层”，而是“系统到底应该怎么切”。

如果业务边界没有先划清楚，那么后面几乎所有设计都会失焦：

• 团队不知道哪个规则属于哪个系统
• 同一个概念在不同服务里被重复定义
• 上下游关系长期靠口头约定维持
• 一个变更会反复穿透多个模块和多个团队

因此，架构师首先要做的，往往是识别核心域、支撑域、通用域，划分限界上下文，建立通用语言，并明确上下文之间的关系模式。换句话说，先画地图，再开始谈地图里的建筑。

这一步对应本书的 第 2 章《业务边界与战略设计》。

1.2.2 再建系统内部秩序

边界画清楚之后，问题会自然转向单个系统内部：这个服务应该如何分层？依赖方向怎么控制？业务规则落在哪？读写路径是否应该继续共用同一套模型？

这一步其实是在解决“单个系统内部如何建立秩序”的问题。也是大多数团队最熟悉、但最容易混在一起的一步。

在工程实践里，这一层通常不是靠单一方法论完成的，而是几种方法一起配合：

• 用三层架构先建立基本职责分层
• 用 Clean Architecture 约束依赖方向
• 用 DDD 战术设计承载复杂业务规则
• 在读写矛盾明显的地方引入 CQRS

这一步对应本书的 第 3 章《系统内部结构设计》。

1.2.3 再处理系统之间的协作

系统一旦拆分成多个上下文、多个服务，新的问题就出现了：调用如何解耦？跨服务流程怎么编排？消息如何可靠投递？事务边界跨不过去时，一致性又怎么保证？

也就是说，边界和内部结构解决的是“单个系统怎么设计”，而系统间协作解决的是“多个系统如何一起工作”。

这一层关注的不再只是类、包和目录，而是：

• 事件驱动与同步调用如何搭配
• 防腐层和集成契约如何守住边界
• Outbox 如何处理双写问题
• Saga 和补偿事务如何处理长流程一致性

这一步对应本书的 第 4 章《系统集成与一致性设计》。

1.2.4 最后落实代码与质量保障

很多设计图看起来都很漂亮，但真正决定系统能否长期维持下去的，往往不是图画得多完整，而是代码怎么写、评审怎么做、上线怎么控。

如果没有编码原则，系统内部结构很快会在日常开发中被打穿；如果没有质量保障机制，再好的边界和架构也会在交付压力下被不断开洞。

因此，架构的最后一公里，通常落在两个层面：

• 代码层面：如何写出可读、可改、可测试的实现
• 质量层面：如何通过评审、检查清单和上线前验证守住设计

这两部分分别对应本书的：

• 第 5 章《编码原则与设计模式》
• 第 6 章《架构质量保障》

如果把这一整套顺序收成一句话，就是：

先划清业务边界，再建立系统内部秩序，再处理系统之间的协作，最后通过代码原则与质量机制把架构真正落地。

1.3 架构设计的方法论地图

理解了问题层次和应对顺序之后，我们就可以把常见的方法论重新放回同一张地图中。

在实际落地中，架构师通常不会只选一种方法论，而是把它们嵌套使用，形成一个完整闭环。这也是“组合拳”这个说法最核心的含义：不是每种方法论都解决所有问题，而是每一种方法论都在处理复杂系统中的一个关键维度。

1.3.1 DDD：解决业务边界与领域建模

DDD 在这套组合拳中有两层作用。

第一层是战略设计：帮助架构师识别核心域、划分限界上下文、建立通用语言和上下文映射。它回答的是“系统应该怎么切”的问题。

第二层是战术设计：帮助团队在单个上下文内部用聚合根、实体、值对象、领域事件表达复杂业务规则。它回答的是“切出来的系统内部，规则应该怎么承载”的问题。

因此，DDD 既属于“先划边界”，也会延伸到“内部结构设计”。这也是为什么本书把它拆成了第 2 章和第 3 章两部分来讲。

1.3.2 三层架构：建立工程分层的默认起点

三层架构不是最“先进”的方法论，但它仍然是很多项目最实用的起点。

它先解决的是一个非常现实的问题：代码应该按什么职责落位，团队才能顺利协作。表现层、业务逻辑层、数据访问层的分工，让系统至少先具备了基本秩序。

从架构师视角看，三层架构的价值不在于它能一次解决所有问题，而在于它能以很低的成本让项目快速从“无结构”进入“有分层”的状态。因此，它经常成为后续引入更强结构的起点。

1.3.3 Clean Architecture：约束依赖方向

如果说三层架构先回答“代码放在哪”，那么 Clean Architecture 进一步回答“核心业务应该依赖谁”。

它最核心的要求是依赖方向向内：外层技术可以依赖内层业务，但内层业务不应该知道数据库、框架和中间件的具体存在。这个约束看起来很抽象，但它直接影响系统是否可测试、可替换、可长期演进。

很多项目在目录上看起来仍然是三层，但一旦在依赖方向上开始服从这个规则，它其实就已经在朝 Clean Architecture 靠拢了。

1.3.4 CQRS：解决读写目标冲突

CQRS 解决的是另一个常见矛盾：同一套模型能否同时服务好读和写。

在简单系统里，共用统一模型通常更经济；但在复杂系统里，写侧关注一致性和规则保护，读侧关注查询性能和展示效率，二者的目标很容易发生冲突。这个时候，继续强行共用一条路径，往往会让双方互相拖累。

CQRS 的价值，正在于允许我们承认这种冲突，并把命令侧和查询侧分别优化。它经常出现在系统内部结构演进的后期，同时又会自然和事件驱动、投影、最终一致性衔接起来。

1.3.5 事件驱动与一致性设计：解决系统间协作

当系统之间开始协作时，单个服务内部的分层已经不够了。新的问题变成了：事件怎么发、消息怎么投、双写怎么解、长流程怎么补偿、一致性怎么守。

这一组方法论通常包括：

• 事件驱动
• 集成模式
• Outbox Pattern
• Saga / 补偿事务
• 最终一致性设计

它们不再主要解决“单个系统内部怎么组织”，而是解决“多个系统之间如何可靠协作”。这也是为什么它们会放到第 4 章集中讨论。

1.3.6 编码原则与质量保障：守住架构落地质量

一套架构设计如果不能稳定落到代码和交付流程里，最终就会退化成 PPT 上的结构。

因此，架构师的组合拳里还缺最后两类能力：

• 用编码原则和设计模式保证实现层不把架构意图写坏
• 用评审、检查清单、测试与上线前验证保证架构不在交付时变形

这两类能力看起来不像 DDD 或 CQRS 那样“有名词感”，但它们恰恰决定了一套架构能不能在团队里真正活下来。

如果把整套方法论再压缩成一句话，就是：

DDD 帮助我们认清业务边界，三层架构和 Clean Architecture 帮助我们建立系统内部秩序，CQRS 帮助我们在读写冲突中做结构优化，事件驱动与一致性设计帮助我们处理系统间协作，而编码原则与质量保障负责把这一切真正守住。

1.4 本章小结

1.4.1 核心观点回顾

本章想传达的核心观点其实很简单：

• 软件架构面对的不是单一问题，而是一组会长期反复出现的复杂性挑战
• 架构师真正做的，不是“选择某一个流行概念”，而是按问题层次打一套组合拳
• 这套组合拳通常遵循固定顺序：先做业务边界，再建系统内部秩序，再处理系统间协作，最后通过代码原则和质量机制把设计守住

也就是说，架构设计的本质不是追逐术语，而是控制复杂性如何在系统中传播。

1.4.2 与后续章节的关系

这一章只是全书的总序，负责建立方法论地图。后续章节会沿着这条主线逐步展开：

• 第 2 章《业务边界与战略设计》：先讨论系统应该如何划清边界
• 第 3 章《系统内部结构设计》：讨论单个系统内部如何建立秩序
• 第 4 章《系统集成与一致性设计》：讨论多个系统之间如何协作
• 第 5 章《编码原则与设计模式》：讨论架构如何真正落到代码
• 第 6 章《架构质量保障》：讨论如何用评审和验证机制守住架构质量

读完这一章之后，你不必已经掌握所有细节，但应该先建立一个判断框架：当系统变复杂时，架构师会从哪些层次出手，又该如何把这些方法论组合起来。

1.4.3 延伸阅读

• Robert C. Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design, 2017
• Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software, 2003
• Vaughn Vernon, Implementing Domain-Driven Design, 2013
• Martin Fowler, CQRS Pattern

下一章：第2章 业务边界与战略设计 将深入讲解限界上下文、通用语言与上下文映射，回答系统应该如何划分边界、团队如何围绕边界协作。

导航：返回目录 | 书籍主页 | 下一章：第2章

导航：书籍主页 | 完整目录 | 上一章：第1章 | 下一章：第3章

第2章 业务边界与战略设计

限界上下文、通用语言与上下文映射，先画对系统的地图

2.1 为什么需要战略设计

第 1 章从 Clean Architecture、DDD 与 CQRS 的协作关系出发，已经用「三位一体」搭好了工程骨架，并简要触及了限界上下文、上下文映射与通用语言。本章不再重复分层目录、Outbox 或读写分离的细节，而是把镜头拉近到 DDD 的战略设计：它回答的是「边界在哪里、团队如何协作、概念如何对齐」——这些问题若未澄清，战术层的聚合与仓储很容易变成「漂亮的样板代码」，却无法降低沟通与演进成本。

2.1.1 战术先行常见症状

许多团队第一次接触 DDD 时，会直接从「实体 / 聚合 / 仓储」入手，短期内代码结构变整齐，但很快遇到以下矛盾：

• 同名不同义：产品口中的「商品」指前台可售的 SKU；库存同学口中的「商品」是可售量与仓位的组合；订单里的「商品」又是下单快照。没有上下文边界时，一个 Product 结构体会被迫承载三套语义。典型症状是代码中出现 Product.InventoryQty（库存关注）和 Product.DisplayTitle（商品关注）混杂在同一个类型中，任何修改都需要跨团队协调，变更成本高昂。

• 跨团队改同一张表：订单服务为了赶需求直接更新库存表，或营销脚本回写订单金额字段。短期省事，长期让「谁拥有这条数据」变得模糊。某次故障中，订单团队修改了库存表的索引，导致库存域的查询性能暴跌；两边互相推诿责任，最终花了一周才定位问题。这种「绕过契约直连数据库」的路径，是边界模糊的最大隐患。

• 集成靠私下约定：RPC 参数、Kafka Topic、回调字段在口口相传中演进，缺少显式的上下游关系与防腐策略。某次营销域修改了优惠券事件的字段名（从 coupon_id 改为 couponCode），订单域的消费者直接报错，才发现双方没有契约测试与版本策略。线上故障持续了 2 小时，影响了数万订单。

真实案例：某团队在引入 DDD 后，代码中充满了精美的聚合、仓储、领域服务，但每次跨服务需求都需要「拉群对齐」，因为没有明确的上下文地图。产品经理提需求时说「改一下商品价格显示逻辑」，三个团队（商品、订单、营销）都认为这是自己的职责，最终在会议室吵了一下午才确定归属。

战略设计的目标，是把上述隐性知识变成可评审的工件：上下文地图、术语表、子域投资优先级与集成模式（客户-供应商、防腐层等）。战术设计再在这些边界之内展开。有了清晰的上下文映射，「改商品价格显示」的需求可以在 10 分钟内定位到正确的上下文（计价域），而不是三方扯皮。

关键认知：战略设计不是「画图玩」，而是团队协作的操作系统。当产品提需求、技术做设计、代码做评审时，都参考同一张上下文地图、同一份术语表，沟通成本会显著降低。没有战略设计的团队，每个需求都要重新「对齐理解」；有战略设计的团队，大部分对齐工作已经提前完成。

2.1.2 战略设计与第 1 章的分工

读完本章，你应能用一页纸向团队说明：我们有哪些限界上下文、各自语言是什么、之间用哪种映射集成、哪几块值得重仓投入。

实践建议：战略设计不必一次性做到完美。可以先用一次 2 小时的工作坊识别出 3-5 个核心上下文，画出简单的映射图，建立初版术语表（20-30 个核心术语）。在后续迭代中，根据实际协作痛点逐步细化边界、补充术语、调整映射关系。重要的是让战略设计的产物（上下文地图、术语表、集成契约）成为团队评审与决策的依据，而不是藏在某个架构师的脑子里。

2.2 限界上下文（Bounded Context）

限界上下文是模型的显式边界：在边界之内，术语含义稳定、规则可推敲；跨边界则允许同名不同义，但必须通过契约（API、事件、发布语言）连接。

2.2.1 识别限界上下文

识别不是一次性「微服务切分」，而是对业务能力与协作现实的建模。可组合使用以下线索：

1. 业务能力：下单、收款、发货、圈品投放通常是不同能力，各自有独立生命周期。例如「订单履约」是一个完整的业务能力，包含订单创建、支付确认、发货、收货等完整流程，这些步骤紧密耦合，应该归属同一个上下文。而「商品展示」则是另一个独立能力，包含商品上架、搜索、详情页等，两者可以独立演进。

2. 语言边界：当同一个词在两处讨论时含义开始分叉，往往意味着边界临近。例如「锁库」在订单侧可能是预留，在库存侧可能是可售量扣减。再比如「价格」，在商品域是「标价」，在计价域是「试算结果」，在订单域是「合同金额」，在支付域是「实付金额」——四个上下文中的「价格」含义完全不同，需要明确划分。

3. 一致性边界：需要同事务维护的不变量，通常落在同一上下文内；可接受最终一致的协作，适合跨上下文用事件衔接。例如订单总价必须等于各明细之和（强一致），适合在订单上下文内用聚合保证；而库存扣减后通知搜索索引更新（可接受秒级延迟），适合跨上下文用事件。

4. 团队与发布节奏（康威定律）：若两个模块永远由同一小队同节奏发布，拆成两个部署单元的紧迫性要重新评估；反之则倾向清晰上下文与契约。例如订单域和支付域虽然业务相关，但由不同团队维护、发布节奏独立、技术栈不同（订单用 Go，支付用 Java），应该拆分为独立上下文，通过清晰的 API 与事件集成。

电商示例（订单链路）：

graph TB
    subgraph 订单上下文
        O[Order 聚合<br/>生命周期 / 金额快照]
    end
    subgraph 商品上下文
        P[Catalog / SKU<br/>上架与展示属性]
    end
    subgraph 库存上下文
        I[Stock / Reservation<br/>可售 / 预留 / 扣减]
    end
    subgraph 营销上下文
        M[Promotion / Coupon<br/>规则与资格]
    end
    O -->|下单前询价 / 快照| P
    O -->|预留 / 释放| I
    O -->|试算 / 核销| M

识别要点：每个上下文有清晰的核心职责与生命周期——订单管理订单状态流转，商品管理可售商品信息，库存管理可售量与预占，营销管理优惠规则。它们通过定义明确的接口与事件协作，而不是共享同一个「大而全」的模型。

2.2.2 上下文边界的划分原则

1. 优先保护不变量：订单总价与明细一致、库存不为负等，各自应在所属上下文的聚合内守护，而不是靠分布式事务「一把梭」。例如订单聚合在 AddLine 方法中同步更新 TotalAmount，保证总价与明细一致性；而库存扣减与订单创建分属两个上下文，通过事件最终一致。

2. 拒绝共享大模型：不要把「全局统一 Product」当作目标；不同上下文各自建模，用 ID 与快照连接。订单上下文的 OrderLine 包含商品快照（标题、单价），商品上下文的 Product 包含展示信息（详情、图片），两者模型不同但通过 ProductID 关联。

3. 数据所有权清晰：每个业务表有唯一写入方；其他上下文只通过 API 或事件消费。库存表只能由库存服务写入，订单服务需要库存数据时通过 GetStock API 查询，而不是直接读库存表。

4. 映射显式化：同步调用、异步事件、批量对账的选择应写进架构说明，而不是隐含在代码路径里。例如在上下文映射图中明确标注「订单 → 库存：同步预占 API + 超时释放事件」。

拆分决策树（可与团队工作坊共用）：

flowchart TD
    A[是否存在稳定业务边界？]
    A -->|是| B[候选独立上下文]
    A -->|否| C{一致性要求是否冲突？}
    C -->|是| D[倾向拆分并定义集成]
    C -->|否| E{是否不同团队 / 发布节奏？}
    E -->|是| F[拆分 + 强化契约与监控]
    E -->|否| G[模块化单体中先划清包边界]

使用建议：这个决策树适合在「是否拆分」的争议中使用。当团队对某个功能模块是否应该独立成服务有分歧时，逐个回答上述问题，多数情况下能达成共识。关键是不要为了拆而拆——模块化单体同样可以有清晰的限界上下文，只是物理部署在同一个进程中。等到团队规模、发布节奏确实需要独立时，再升级为独立服务。

2.2.3 电商案例：订单域、商品域、营销域

以下表格用于对齐职责与对外能力（示例命名可按团队语言替换）：

实战案例：边界划分的决策过程

某电商平台早期把计价能力分散在订单、营销、商品三个域：订单域计算小计，营销域计算优惠，商品域返回基础价。随着业务复杂度上升，出现多处问题：

症状：

• 购物车、订单创建、支付确认三处的价格计算逻辑不一致
• 营销规则变更需要同步修改订单与商品的计算代码
• 无法支持「PDP 加购试算」场景，因为没有统一的计价入口

重构决策：

1. 识别核心能力：「给定商品清单、营销规则、用户身份，计算出各层级价格」是一个完整的业务能力
2. 独立上下文：新建计价上下文，职责是提供统一的试算接口，收敛所有价格计算逻辑
3. 定义边界：
   • 计价上下文不拥有商品基础价、营销规则、订单状态——它是编排者
   • 对外提供 Calculate(items, promotions, context) -> PriceBreakdown
   • 各场景（PDP / 购物车 / 订单）通过统一接口获取价格

收益：

• 价格计算的一致性得到保证（同一套代码服务所有场景）
• 营销规则变更只需在营销域发布事件，计价域订阅后自动生效
• 支持了试算、价格预览、价格审计等新需求

经验：识别边界不是一次性切分，而是在「职责不清、协作成本高、重复逻辑多」的信号出现时，主动重构出清晰边界。

Go 建模提示：在订单上下文中，不要直接引用商品聚合的类型，而是使用 ID + 快照 表达跨边界依赖。

package order

type ProductID string

// Money 在订单上下文中表示「合同金额」；实现细节可复用共享包，但语义归属订单。
type Money struct {
	Cents    int64
	Currency string
}

// OrderLine 属于订单上下文：保存下单时刻解释合同所需的快照。
type OrderLine struct {
	ProductID   ProductID
	ProductName string // 快照：避免商品改标题影响历史订单
	UnitPrice   Money  // 快照：避免改价影响已生成应付金额
	Qty         int
}

package catalog

type ProductID string

// Product 属于商品上下文：关注展示与销售属性，而非订单合同解释。
type Product struct {
	ID          ProductID
	Title       string
	Description string
	OnShelf     bool
}

要点：两个包里的「商品信息」形状不同不是重复，而是上下文各有权威——合同解释以订单快照为准，陈列以商品上下文为准。

实践建议：在代码评审时，如果发现两个上下文共享同一个 Product 类型，应该追问：「这两处对商品的关注点是否相同？」如果答案是「不同」（一个关注展示，一个关注合同），那么应该拆分为两个独立的类型。宁可有一些字段重复，也不要为了「消除重复」而强行共享模型——这种重复是有意义的重复，体现了不同上下文的自治性。

2.3 通用语言（Ubiquitous Language）

通用语言是业务方与研发共同维护的精确词汇系统，贯穿需求、设计与代码。战略阶段的价值在于：先对齐语言，再讨论服务拆分与表结构。

2.3.1 建立通用语言

推荐从一次轻量工作坊开始：

1. 列出动词与名词：下单、支付、发货、锁库、核销、退款……标记同义词（「关闭订单」vs「取消订单」）。
2. 为每个词写一句业务定义：谁触发、前置状态、成功后的世界有何不同。
3. 映射到代码锚点：包名、类型名、公开方法名尽量使用一致词汇（如 PlaceOrder 而非 CreateOrderRecord）。
4. 记录禁用词：例如团队约定不用「更新状态 2」这类技术黑话对外沟通。

工作坊实践流程（2 小时示例）

参与者：产品经理、领域专家、架构师、核心开发各 1-2 人。

第一阶段（30 分钟）：业务流程梳理

• 在白板上画出核心业务流程（如「用户下单到收货」）
• 标记出关键状态节点与触发动作
• 识别出现频率最高的业务名词（订单、商品、库存、优惠券）

第二阶段（45 分钟）：术语对齐

• 逐个讨论每个名词的精确定义
  • 示例：「库存」在商品上架时指初始可售量，在订单创建时指预占后的剩余量，在发货后指实际扣减
  • 决策：用「可售库存（Available Stock）」、「预占库存（Reserved Stock）」、「已扣库存（Deducted Stock）」三个明确术语替代模糊的「库存」
• 识别同义词并统一
  • 示例：技术侧说「关单」，业务侧说「取消订单」→ 统一为 CancelOrder
  • 示例：「锁库」、「预占库存」、「冻结库存」→ 统一为 ReserveStock

第三阶段（30 分钟）：映射到代码

• 为每个术语分配英文命名（供代码使用）
• 明确哪些术语属于哪个限界上下文
• 示例输出：

| 中文术语 | 英文命名 | 所属上下文 | 定义 |
|---------|---------|-----------|------|
| 下单 | PlaceOrder | 订单域 | 用户提交购买意图，生成待支付订单 |
| 预占库存 | ReserveStock | 库存域 | 为订单预留库存，防止超卖；超时后自动释放 |
| 核销优惠券 | RedeemCoupon | 营销域 | 将优惠券从可用状态变更为已使用 |

第四阶段（15 分钟）：归档与宣导

• 将术语表提交到代码仓库（docs/glossary.md）
• 在下次需求评审时强制对齐：新需求必须使用术语表中的词汇
• 代码评审时检查：新增 API / 事件命名是否符合术语表

工作坊成果示例：

## 订单上下文术语（v1.0）

- **下单（PlaceOrder）**：用户提交购买意图，生成待支付订单；不等于支付成功。
  - 前置条件：商品可售、库存充足、优惠券可用
  - 后置状态：订单状态为 `PendingPayment`，库存为 `Reserved`
  
- **锁库 / 预占库存（ReserveStock）**：为指定订单行预留可售库存，防止超卖；不等同于「扣减库存」。
  - 触发方：订单域在创单时调用库存域接口
  - 超时策略：30 分钟未支付自动释放
  
- **订单已支付（OrderPaid）**：支付渠道确认成功后的领域事实；会触发履约与扣减等后续流程。
  - 事件订阅者：库存域（扣减库存）、物流域（创建配送单）、营销域（核销优惠券）

实战技巧：

• 不要追求第一版术语表的完美——先建立 60% 共识，剩余在迭代中补充
• 争议术语标记「待定」，给出 2-3 个候选，在实际编码中验证哪个更顺
• 每季度 Review 一次术语表，淘汰不再使用的术语，补充新增的核心概念

Go：让类型系统承载语言：

package order

type OrderID string
type UserID string
type ProductID string

// PlaceOrderCommand 用业务动词命名命令，而非数据库操作。
type PlaceOrderCommand struct {
	BuyerID UserID
	Lines   []OrderLineDraft
}

type OrderLineDraft struct {
	ProductID ProductID
	Qty       int
}

2.3.2 语言的演进与维护

语言会随业务演进，需要低成本维护机制：

• ADR / RFC：当术语含义变化（例如「预售」从全款改为定金），用简短架构记录说明新旧语义与兼容期。
• 版本化 API：对外契约（REST / gRPC / 事件 Schema）与术语表联动更新，避免「文档是新的、代码是旧的」。
• 定期 Review：每个迭代挑一个争议需求，反问「我们用的是哪一个上下文里的定义？」

演进示例：当业务引入「先用后付」，需明确它属于支付上下文的授信产品，还是订单上下文的支付子状态——结论应写回术语表，并调整 OrderStatus 与集成事件名，而不是仅在 if 分支加 flag。

版本化策略：术语表应该有版本号（如 v1.0、v1.1），每次重大变更（如删除术语、修改定义）都升级版本并记录变更日志。这样新人可以追溯「为什么当初选择这个词」，避免重复讨论已解决的问题。同时，对外API的命名也应该与术语表版本对应，例如PlaceOrder v1使用术语表v1.0的定义，PlaceOrder v2使用v1.1的定义，保证向后兼容。

跨团队同步：术语表变更应该通知所有相关团队。可以在 Git 仓库中设置术语表文件的 CODEOWNERS，任何修改都需要相关团队的 Approver 确认。这样可以避免「术语表改了但代码没改」或「不同团队理解不一致」的问题。

2.3.3 反模式：技术术语污染业务讨论

典型反模式包括：在评审中使用 OrderDTO / OrderVO、把数据库动词当业务语言（InsertOrder）、用魔法状态码沟通。它们会阻断业务专家的参与。

package badexample

// ❌ 技术噪声：业务方无法从命名理解用例意图
type OrderService struct{}

func (s *OrderService) HandleSubmit(data map[string]any) error { return nil }

// ✅ 使用业务动词与强类型参数，评审可对读
package order

import "context"

type OrderService interface {
	PlaceOrder(ctx context.Context, cmd PlaceOrderCommand) (OrderID, error)
}

更多语言污染案例与纠正

反模式 1：用数据库字段名代替业务概念

// BAD: 数据库思维泄漏到业务层
type Order struct {
    OrderNo    string
    UserId     int64
    TotalAmt   int64
    StatusCode int    // 0=待支付 1=已支付 2=已取消 3=已关闭
}

func (s *OrderService) UpdateStatusCode(orderNo string, code int) error {
    // 业务规则隐藏在魔法数字背后
}

// GOOD: 业务语言驱动设计
type Order struct {
    ID         OrderID
    CustomerID CustomerID
    Total      Money
    Status     OrderStatus // 枚举类型
}

type OrderStatus int
const (
    StatusPendingPayment OrderStatus = iota
    StatusPaid
    StatusCanceled
    StatusFulfilled
)

// 业务动词显式化
func (o *Order) MarkAsPaid(paidAt time.Time) error {
    if o.Status != StatusPendingPayment {
        return ErrInvalidTransition
    }
    o.Status = StatusPaid
    o.PaidAt = paidAt
    return nil
}

收益：代码评审时，业务方能直接参与讨论状态转换规则，而不是盯着 SQL 猜测 status = 1 的含义。

反模式 2：接口命名只有 CRUD，没有业务意图

// BAD: 贫血模型 + CRUD
type OrderRepository interface {
    Insert(ctx context.Context, order *Order) error
    Update(ctx context.Context, order *Order) error
    Delete(ctx context.Context, id string) error
    Select(ctx context.Context, id string) (*Order, error)
}

问题：

• Update 可以改任意字段，无法表达业务约束
• 新人看不出「订单支付」应该调用哪个方法
• 业务规则散落在 Service 层的 if-else 中

// GOOD: 用例驱动的接口
type OrderUseCase interface {
    PlaceOrder(ctx context.Context, cmd PlaceOrderCommand) (OrderID, error)
    MarkAsPaid(ctx context.Context, orderID OrderID, paidAt time.Time) error
    CancelOrder(ctx context.Context, orderID OrderID, reason string) error
}

收益：接口即文档——每个方法对应一个明确的业务用例。

反模式 3：在需求评审中使用技术黑话

真实案例：产品提需求「用户支付后，订单状态改为 2」。

问题：

• 产品被迫记忆「2」的含义（下次可能记错）
• 新人无法从文档理解业务流程
• 数据库状态码变更时，文档需要全局替换

纠正方案：

• 需求文档使用业务语言：「用户支付后，订单状态改为已支付」
• 代码中使用枚举常量：StatusPaid
• 数据库存储可以是数字，但对外接口和文档必须是业务术语

落地检查：

• 代码评审时，发现「魔法数字」或「技术缩写」，要求作者用业务术语重命名
• API 文档生成时，枚举值自动展示为业务含义（如 "status": "paid"）
• 新人培训时，术语表是必读文档

2.4 上下文映射（Context Mapping）

上下文映射描述谁依赖谁、如何集成。它把组织关系与架构关系对齐，避免「谁都能改」的隐式耦合。

2.4.1 上下游关系模式

常见关系（节选）：

graph LR
    subgraph 上游
        Catalog[商品上下文]
        Promo[营销上下文]
    end
    subgraph 下游
        Checkout[结算上下文]
        Order[订单上下文]
    end
    Catalog -->|Customer-Supplier| Order
    Promo -->|Customer-Supplier| Checkout
    Checkout -->|同步编排| Order

各模式的实战应用

客户-供应商（Customer-Supplier）实践

场景：订单域（客户）依赖商品域（供应商）获取商品信息。

关键点：

• 上游（商品域）提供版本化 API，保证向后兼容
• 下游（订单域）通过契约测试验证依赖稳定性
• 定期召开「契约评审会」，下游提需求，上游评估可行性

实现示例：

// 商品域对外提供的稳定接口（v1版本）
package catalogapi

type GetProductRequest struct {
    ProductID string `json:"product_id"`
}

type GetProductResponse struct {
    ID          string  `json:"id"`
    Title       string  `json:"title"`
    Price       float64 `json:"price"`
    Available   bool    `json:"available"`
}

// 订单域依赖商品域的接口
package order

type ProductAPI interface {
    GetProduct(ctx context.Context, productID string) (*catalogapi.GetProductResponse, error)
}

契约测试：

func TestProductAPI_Contract(t *testing.T) {
    // 验证商品域的响应格式是否符合订单域的预期
    resp := &catalogapi.GetProductResponse{
        ID:    "SKU123",
        Title: "iPhone 15",
        Price: 5999.00,
        Available: true,
    }
    // 断言必需字段存在
    assert.NotEmpty(t, resp.ID)
    assert.NotEmpty(t, resp.Title)
}

遵奉者（Conformist）实践

场景：对接税务系统、支付渠道等强势上游，无力改变对方模型。

策略：

• 直接使用对方的数据结构（避免无谓的翻译层）
• 在上游变更时快速跟进（监听对方发布公告）
• 内部文档记录「为什么使用对方模型」（避免后人困惑）

示例：

// 直接使用支付宝 SDK 的类型
import "github.com/alipay/alipay-sdk-go"

type AlipayAdapter struct {
    client *alipay.Client
}

func (a *AlipayAdapter) CreatePayment(orderID string, amount float64) error {
    // 直接使用 Alipay SDK 的请求结构
    req := alipay.TradeCreateRequest{
        OutTradeNo:  orderID,
        TotalAmount: fmt.Sprintf("%.2f", amount),
        Subject:     "订单支付",
    }
    _, err := a.client.TradeCreate(&req)
    return err
}

适用场景：上游是成熟的外部系统，模型变更频率低，翻译成本高于收益。

开放主机服务（OHS）+ 发布语言实践

场景：商品中心需要服务多个下游（搜索、推荐、营销、订单），避免为每个下游定制接口。

策略：

• 设计通用查询接口，支持灵活的筛选与投影
• 发布标准事件（JSON Schema / Protobuf），所有下游订阅相同事件
• 使用 API Gateway 管理多租户访问（限流、鉴权、版本路由）

示例：

// 商品域发布统一的查询接口
type ProductQueryAPI interface {
    ListProducts(ctx context.Context, req ListProductsRequest) (*ListProductsResponse, error)
}

type ListProductsRequest struct {
    CategoryID string   `json:"category_id,omitempty"`
    Tags       []string `json:"tags,omitempty"`
    OnShelf    *bool    `json:"on_shelf,omitempty"`
    Limit      int      `json:"limit"`
    Offset     int      `json:"offset"`
}

发布语言（事件）：

{
  "event_type": "ProductOnShelf",
  "version": "1.0",
  "product_id": "SKU123",
  "title": "iPhone 15",
  "price": 5999.00,
  "occurred_at": "2026-04-17T10:00:00Z"
}

收益：

• 下游（搜索、推荐）可以独立订阅事件，无需与商品域强耦合
• 商品域只需维护一套接口，降低维护成本
• 通过 Schema Registry 管理事件版本，保证向后兼容

选型决策树：

flowchart TD
    start([识别上下游关系]) --> q1{上游是否可控？}
    q1 -->|是| q2{下游数量？}
    q2 -->|1-2个| customer[Customer-Supplier]
    q2 -->|3个以上| ohs[OHS + Published Language]
    q1 -->|否| q3{模型是否冲突？}
    q3 -->|冲突| acl[ACL 防腐层]
    q3 -->|不冲突| conformist[Conformist 遵奉者]

2.4.2 共享内核

共享内核是两方共同维护的一小块模型或库。它减少重复，但会牺牲自治，需要强治理。

电商谨慎场景：订单与库存若共享「SKU ID 类型 + 基础校验函数」这类极小内核尚可；一旦共享「库存数量字段」或「订单状态枚举」，边界会迅速模糊。

// sharedkernel/sku.go — 保持极小、稳定、少变更
package sharedkernel

type SKUCode string

func (c SKUCode) IsWellFormed() bool {
	return len(string(c)) >= 6 // 示例规则：长度下限
}

实践建议：共享内核应能通过双人评审 + 语义化版本演进；否则优先改为 Published Language（如清晰的事件字段）而非代码级共享。

何时使用共享内核：

• 两个上下文由同一团队维护，且模型变更成本低
• 共享的是极其稳定的基础类型（如 ID、Money、Email 等值对象）
• 双方都同意「修改共享内核需要通知并等待对方确认」

何时避免共享内核：

• 两个上下文由不同团队维护（会严重拖慢发布节奏）
• 共享的是经常变化的业务规则（如订单状态、库存策略）
• 无法保证「修改前通知」的纪律（会导致隐式破坏性变更）

真实案例：某团队在订单与库存之间共享了 ProductStatus 枚举。营销需求要求增加「预售」状态，订单团队快速修改了枚举并发布，但忘记通知库存团队。库存服务在处理「预售商品」时因为没有对应的分支处理逻辑，导致库存同步失败。最终双方约定：将共享内核降级为 Published Language（事件 Schema），每次变更必须走 RFC 流程并双方确认。

2.4.3 防腐层

防腐层把外部不稳定协议挡在边界之外，领域层只依赖自己的端口接口。

package order

import (
	"context"
	"fmt"
)

type OrderID string

// Money 表示订单上下文的应付金额（示例：用分存储，避免 float）。
type Money struct {
	cents    int64
	currency string
}

func NewMoneyFromCents(cents int64, currency string) Money {
	return Money{cents: cents, currency: currency}
}

func (m Money) DecimalYuan() string {
	if m.cents < 0 {
		return "0.00"
	}
	yuan := m.cents / 100
	fen := m.cents % 100
	return fmt.Sprintf("%d.%02d", yuan, fen)
}

// PaymentSession 是领域侧对「可跳转支付」的最小抽象，不暴露渠道字段。
type PaymentSession struct {
	CheckoutURL string
}

type StartPaymentCommand struct {
	OrderID OrderID
	Payable Money
}

// PaymentGateway 由订单领域定义：表达「我需要的支付能力」，由基础设施实现。
type PaymentGateway interface {
	StartPayment(ctx context.Context, cmd StartPaymentCommand) (*PaymentSession, error)
}

package alipayacl

import (
	"context"
	"fmt"

	"example/order"
)

// 仅示意第三方 SDK 的能力边界，避免示例依赖真实包名。
type alipayPrecreateClient interface {
	Precreate(ctx context.Context, body map[string]any) (*alipayPrecreateResult, error)
}

type alipayPrecreateResult struct {
	QRCodeURL string
}

// AlipayACL 位于基础设施侧：翻译领域命令 ↔ 支付宝请求 / 响应。
type AlipayACL struct {
	client alipayPrecreateClient
}

func NewAlipayACL(client alipayPrecreateClient) *AlipayACL {
	return &AlipayACL{client: client}
}

func (a *AlipayACL) StartPayment(ctx context.Context, cmd order.StartPaymentCommand) (*order.PaymentSession, error) {
	req := map[string]any{
		"out_trade_no": string(cmd.OrderID),
		"total_amount": cmd.Payable.DecimalYuan(),
		"subject":      fmt.Sprintf("订单支付 %s", string(cmd.OrderID)),
	}
	resp, err := a.client.Precreate(ctx, req)
	if err != nil {
		return nil, err
	}
	return &order.PaymentSession{CheckoutURL: resp.QRCodeURL}, nil
}

收益：

• 当渠道字段变更时，修改集中在 ACL；订单聚合与用例不被第三方类型污染
• 可以为同一个端口提供多个实现（支付宝 ACL、微信 ACL、PayPal ACL），通过工厂模式或配置切换
• 测试时可以使用 Fake 实现替代真实支付渠道，提升测试速度和可靠性
• 防腐层承担了「翻译」职责，领域层保持纯粹，不受外部依赖污染

反模式警示：有些团队会在防腐层之外再包一层「防防腐层」，过度封装导致代码层级过深。原则是一次翻译足矣——从第三方模型翻译到领域模型，中间不需要再多一层「通用模型」。

2.4.4 电商系统的上下文映射实例

综合一版可挂在 Wiki 首页的示意（箭头表示依赖方向）：

graph LR
    OrderBC[订单上下文]
    CatalogBC[商品上下文]
    InventoryBC[库存上下文]
    PaymentBC[支付上下文]
    LogisticsBC[物流上下文]
    PromoBC[营销上下文]

    OrderBC -->|Customer-Supplier| CatalogBC
    OrderBC -->|Customer-Supplier| InventoryBC
    OrderBC -->|ACL| PaymentBC
    OrderBC -->|Customer-Supplier| LogisticsBC
    OrderBC -->|Customer-Supplier| PromoBC
    InventoryBC -.->|极小共享内核| CatalogBC

落地检查清单：

• 每个箭头是否有明确契约（OpenAPI / Proto / 事件表）？
• 失败模式（超时、重试、幂等）是否写清归属上下文？
• 是否存在「绕过契约直连数据库」的路径？若有，计划消除。

集成失败案例与解决方案

案例 1：订单域直接读取库存表（违反边界）

背景：订单服务为了展示「剩余库存」，在查询订单详情时直接 JOIN 库存表。

问题：

• 库存表结构变更时，订单服务也要修改（耦合）
• 库存域无法独立演进（加缓存、分库、切换存储）
• 破坏了「库存域拥有库存数据」的所有权原则

解决方案：

// 订单域定义端口
type StockQueryPort interface {
    GetAvailableQty(ctx context.Context, sku string) (int, error)
}

// 基础设施层实现（调用库存域 API）
type RemoteStockAdapter struct {
    client *stockservice.Client
}

func (a *RemoteStockAdapter) GetAvailableQty(ctx context.Context, sku string) (int, error) {
    resp, err := a.client.GetStock(ctx, &stockpb.GetStockRequest{Sku: sku})
    if err != nil {
        return 0, fmt.Errorf("query stock: %w", err)
    }
    return int(resp.AvailableQty), nil
}

收益：库存域可以独立优化存储、加缓存、切换数据库，订单域只依赖接口契约。

案例 2：营销规则变更导致订单金额计算不一致

背景：营销域上线新规则后，订单域的价格计算逻辑未同步更新，导致订单金额与用户预览不一致。

根因：没有统一的计价入口，订单域、购物车、PDP 各自实现计算逻辑。

解决方案：

1. 新建计价上下文作为编排者
2. 所有场景通过计价域的 Calculate 接口获取价格
3. 营销规则变更时，只需更新营销域；计价域自动订阅规则变更事件

graph LR
    PDP[商品详情页] -->|试算请求| Pricing[计价上下文]
    Cart[购物车] -->|试算请求| Pricing
    Order[订单域] -->|确认金额| Pricing
    Pricing -->|查基础价| Catalog[商品域]
    Pricing -->|查规则| Promo[营销域]

案例 3：支付回调丢失导致订单状态不同步

背景：支付域通过 HTTP 回调通知订单域支付成功，但网络抖动导致回调丢失，订单长时间停留在「待支付」状态。

问题：

• 同步回调不可靠（网络、超时、重启）
• 缺少补偿机制

解决方案：

1. 异步事件 + 重试：支付域发布 PaymentCaptured 事件到 Kafka，订单域订阅并幂等处理
2. 对账任务：每小时扫描「待支付」订单，调用支付域查询实际状态，发现不一致则补偿
3. 状态机保护：订单状态机禁止「已支付 → 待支付」的逆向转换，防止数据损坏

// 订单域订阅支付事件
func (s *OrderService) HandlePaymentCaptured(ctx context.Context, event PaymentCapturedEvent) error {
    order, err := s.repo.FindByID(ctx, event.OrderID)
    if err != nil {
        return err
    }
    // 幂等检查
    if order.Status == StatusPaid {
        return nil // 已处理
    }
    return order.MarkAsPaid(event.PaidAt)
}

经验：跨上下文集成必须考虑失败场景——同步调用加超时与重试，异步事件加幂等与对账。

2.5 领域的分类

战略精炼的重要产出，是把公司能力地图分为 核心域、支撑域、通用域，以指导人力与风险的投放。

2.5.1 核心域、支撑域、通用域

• 核心域：差异化竞争力所在，复杂且多变，应重仓自研与深度建模。例如亚马逊的推荐算法、阿里的交易风控，这些是竞争壁垒，必须投入顶尖人才与架构资源。
• 支撑域：业务必需但非胜负手，可适度定制，避免过度设计。例如商品管理、库存管理，参考业界成熟模型即可，不必追求极致创新。
• 通用域：行业共性，成熟外包或 SaaS 更划算。例如短信通知、对象存储、日志监控，云服务比自研更经济。

2.5.2 投资策略

可用「四维度」快速评分：业务价值、复杂度、变化频率、差异化。不必追求精确分数，关键是相对比较与资源承诺。

投资决策案例

案例 1：搜索推荐从支撑域升级为核心域

背景：某平台早期将搜索视为支撑域，采用开源 Elasticsearch + 简单配置。随着 GMV 增长，发现 70% 流量来自搜索，转化率直接影响营收。

决策过程：

• 重新评估：搜索从「辅助发现」变为「核心转化入口」
• 投资升级：
  • 组建搜索算法团队（相关性、个性化排序）
  • 自研召回引擎与排序服务（而非依赖 ES 默认评分）
  • 建设 ABTest 平台与实时指标体系
• 资源配比：从 1 人维护 → 8 人团队（算法 + 工程）

收益：搜索点击率提升 40%，GMV 贡献占比从 70% 提升到 85%。

案例 2：自研消息队列的代价

背景：某团队因「担心 Kafka 运维复杂」，自研了轻量级消息队列。

问题暴露：

• 维护成本：集群故障、数据丢失、性能瓶颈需要专人处理
• 功能缺失：不支持事务、延迟消息、死信队列等企业级特性
• 团队分心：核心业务开发被「救火中间件」打断

纠正方案：

• 迁移到云服务商托管的 Kafka（或 RocketMQ）
• 内部仅封装薄的 SDK 层（日志、监控、错误处理）
• 释放的人力投入到核心业务优化

经验：通用域的自研往往是「过早优化」——先用成熟方案，待瓶颈确认后再评估自研价值。

常见误判：

• 把所有模块都标成核心域：资源分散，真正的差异化无人深耕。
• 把支撑域做成「无设计」：质量太差会反向拖垮核心域（数据错误、不可用）。
• 在通用域自研中间件：短期有掌控感，长期维护成本侵蚀核心业务投入。
• 忽视支撑域的稳定性：商品数据错误、库存不准确会直接影响订单转化——支撑域不是「二等公民」。

投资复盘机制

建议每半年召开一次「子域投资复盘会」：

1. 回顾当前分类：哪些域的重要性发生了变化？
2. 评估资源配比：核心域是否得到了足够的架构师与工程资源？
3. 识别欠投资域：哪些支撑域因质量问题拖累了核心域？
4. 调整策略：将资源从「过度投资的通用域」转移到「欠投资的核心域」

输出示例：

2.5.3 电商平台的领域分类

结合国内中大型平台的常见划分（需按公司战略微调）：

核心域候选：交易订单、库存准确性、交易风控、推荐与搜索体验（若差异化来自发现与转化）。

支撑域候选：商品中心、营销规则、计价、物流对接、客服工单。

通用域候选：登录注册、对象存储、日志监控、基础消息通道。

详细领域分类与资源配比

分类决策的实战案例

案例 1：库存系统从支撑域升级为核心域

初始阶段：

• 分类：支撑域（「库存只是个数字，没啥复杂的」）
• 投资：2 人维护，简单 Redis + MySQL

问题暴露：

• 大促期间频繁超卖，投诉量激增
• 供应商库存同步延迟，导致用户下单后被取消
• 库存准确性成为用户信任的核心指标

重新评估：

• 业务价值：库存不准 → 超卖 → 投诉 → 品牌损失（极高）
• 复杂度：多仓、多供应商、实时同步、预占释放（高）
• 差异化：准确率 99.9% vs 竞品 95%（高）
• 结论：升级为核心域

投资升级：

• 团队扩充到 8 人（架构师 + 高工 + 算法）
• 建设预占释放机制、对账系统、实时监控
• 引入分布式锁与 Lua 脚本保证并发正确性
• 建立库存准确性 SLA（99.95%）

收益：超卖率从 5% 降到 0.1%，用户满意度显著提升。

案例 2：消息通知从自研降级为云服务（通用域）

初始阶段：

• 分类：支撑域
• 投资：4 人团队自研短信 / 邮件 / 推送网关

问题暴露：

• 维护成本高（渠道对接、失败重试、速率控制）
• 功能落后（不支持模板管理、A/B 测试）
• 团队被「救火」占用，无法投入核心业务

重新评估：

• 业务价值：中（通知到达率影响体验，但非核心竞争力）
• 差异化：无（所有平台都需要通知，无差异化空间）
• 结论：降级为通用域，使用云服务

调整方案：

• 迁移到云服务商（阿里云 / 腾讯云 / AWS SNS）
• 内部仅保留薄封装层（日志、监控、降级）
• 释放的 4 人转投到核心域（搜索推荐优化）

收益：维护成本降低 80%，功能更丰富（模板管理、多渠道支持），团队聚焦核心业务。

包结构与投资映射

// 用包结构反映投资重心（示意）：核心域包内更完整领域模型，外围保持薄封装。

// 核心域：完整的 DDD 分层
// core/order/
//   ├── domain/       (聚合、实体、值对象、领域服务)
//   ├── application/  (用例、命令处理器)
//   ├── adapter/      (HTTP、gRPC、事件订阅)
//   └── infra/        (仓储实现、外部集成)

// 支撑域：适度建模，控制复杂度
// supporting/catalog/
//   ├── service/      (业务逻辑)
//   ├── repository/   (数据访问)
//   └── api/          (对外接口)

// 通用域：薄封装，优先使用外部服务
// generic/notification/
//   ├── client/       (云服务 SDK 封装)
//   └── config/       (配置与降级)

说明：包划分只是辅助沟通的手段，真正重要的是团队边界、发布边界与数据所有权是否与之一致。核心域投入更多架构设计与代码质量保障，支撑域保持适度复杂度，通用域优先复用成熟方案。

2.6 本章小结

2.6.1 核心要点回顾

• 战略设计解决边界、协作与语言问题，是战术建模的前置条件；与第 1 章的架构骨架互补而非重复。
• 限界上下文按业务能力、语言分叉、一致性与团队现实划分；订单、商品、营销应各自维护模型，以 ID 与快照连接。
• 通用语言需要术语表、命令动词与演进机制，避免技术黑话污染评审。
• 上下文映射把依赖关系产品化：客户-供应商、防腐层、共享内核（克制使用）、开放主机服务与发布语言各得其所。
• 子域分类驱动投资：核心域求精，支撑域求稳，通用域求省，并定期复盘调整。

2.6.2 落地检查清单

在项目启动或重构时，可用以下清单自查：

限界上下文识别：

• 是否识别出 3-8 个主要限界上下文？（过少说明边界模糊，过多说明过度拆分）
• 每个上下文是否有清晰的职责描述（一句话能说清楚）？
• 是否避免了「大而全的领域模型」（如一个 Product 类服务所有上下文）？
• 跨上下文的数据引用是否通过 ID 与快照，而非直接依赖对方的聚合类型？

通用语言建立：

• 是否建立了术语表（docs/glossary.md）？
• 代码中的核心类型、方法名是否与术语表一致？
• 是否消除了魔法数字与技术黑话（如 status=2、UpdateData）？
• 新需求评审时，是否强制使用术语表中的词汇？

上下文映射：

• 是否有明确的上下文映射图（类似 2.4.4 的 Mermaid 图）？
• 每个依赖关系是否标注了集成模式（Customer-Supplier / ACL / OHS）？
• 是否为关键集成定义了契约（API 文档 / Proto / 事件 Schema）？
• 是否考虑了失败场景（超时、重试、降级、对账）？

子域投资：

• 是否明确标记了核心域、支撑域、通用域？
• 核心域是否得到了架构师与高级工程师的投入？
• 通用域是否优先使用成熟的开源 / 云服务，而非自研？
• 是否有定期复盘机制（每半年 Review 一次子域分类）？

2.6.3 常见陷阱总结

2.6.4 实践建议

1. 战略设计不是一次性工作——建议每季度召开一次「边界复盘会」，回顾上下文划分是否合理，术语表是否需要更新。

2. 工作坊轻量化——不必追求「完美的限界上下文图」，先建立 60% 共识，剩余在实际编码中验证和调整。

3. 术语表即文档——将术语表提交到代码仓库，作为新人培训与需求评审的必读材料。

4. 从小处着手——若团队尚未实践 DDD，可以从「建立一个术语表」或「重命名一个核心 API」开始，而非一次性重构整个系统。

5. 与第 1 章方法论结合——战略设计画出边界 → Clean Architecture 确保依赖方向 → DDD 战术设计守护不变量 → CQRS 优化读写路径，四者协同发力。

与下一章的衔接：第 3 章将把镜头转向单个系统内部，讨论三层架构、Clean Architecture、DDD 战术与 CQRS 如何共同建立稳定的内部秩序。战略设计先回答「边界是什么、边界在哪里」，系统内部结构再回答「边界之内如何组织代码与数据流」。

导航：返回目录 | 上一章：第1章 | 书籍主页 | 下一章：第3章

导航：书籍主页 | 完整目录 | 上一章：第2章 | 下一章：第4章

第3章 系统内部结构设计

三层架构、Clean Architecture、DDD 战术与 CQRS 的协同落地

3.1 为什么要单独讨论系统内部结构

如果说第 2 章解决的是「系统应该被划分成哪些业务边界」，那么这一章要回答的是另一个同样关键的问题：在边界已经划定之后，单个系统内部到底应该怎么组织？

很多团队在架构演进时，会把两个层面混在一起讨论：

• 一边在谈限界上下文怎么划
• 一边又在争论 Handler 能不能直接调 Repository
• 同时还在讨论聚合根、值对象、读写分离和查询性能

这样做的问题是，边界问题、依赖问题、建模问题和数据流问题被混成一团，最后往往谁都没有真正讲清楚。

对架构师来说，系统内部结构设计至少要同时回答四个问题：

1. 代码先按什么方式分层，团队才容易协作？
2. 依赖应该按什么方向流动，外部技术才不会污染核心业务？
3. 复杂业务规则应该由什么模型承载，而不是散落在 Service 里？
4. 当读和写的目标已经出现冲突时，数据流又该如何拆开？

这也正对应了本章的四个关键抓手：

• 三层架构：先建立最基本的职责秩序
• Clean Architecture：再约束依赖方向
• DDD 战术设计：让复杂规则回到模型内部
• CQRS：当读写目标冲突时，再拆分读写路径

从这个角度看，这四者并不是彼此替代，而是逐层叠加。

3.1.1 从业务边界到系统内部结构

第 2 章讲的战略设计，解决的是「地图」问题：哪些能力属于订单，哪些属于库存，哪些属于营销，团队之间怎样通过上下文地图协作。

而本章解决的是「房间内部装修」问题：当我们已经确定了这里是订单上下文、那里是库存上下文之后，订单系统内部又该如何分层、如何建模、如何组织读写路径。

如果没有第 2 章的边界，系统内部结构设计会失去落点；
如果只有边界、没有内部结构，系统很快又会退化成新的大泥球。

因此，这一章在全书里承担的是承上启下的角色：

• 承接第 2 章：边界已经划清
• 通向第 4 章：单个系统内部有了秩序之后，才有条件进一步讨论系统之间如何协作

3.1.2 架构师在这一层真正关注什么

在系统内部结构设计这一层，架构师最需要关注的，通常不是“某个类放在哪个目录”，而是以下几类长期成本：

• 变更成本：一个新需求会不会牵一发而动全身？
• 理解成本：新人能不能在有限时间内看懂业务主线？
• 测试成本：核心逻辑能否脱离数据库和消息中间件被验证？
• 扩展成本：当新促销规则、新支付方式、新查询场景出现时，系统能否局部演进？

这也是为什么系统内部结构设计，不能只靠“项目目录看起来很整齐”来判断。真正重要的是：职责有没有分清、依赖有没有收束、规则有没有回到模型内部、读写目标有没有被正确拆分。

3.2 标准三层架构：多数项目的默认起点

3.2.1 为什么三层架构会成为默认起点

在系统设计的早期阶段，最重要的往往不是“架构是否优雅”，而是“职责是否基本清楚”。对于一个刚开始建设的 order-service 来说，下单、查询订单、支付后更新状态、超时关单，这些需求虽然已经涉及接口、业务逻辑和数据存储，但复杂度通常还不足以支撑更重的架构方法论。此时，标准三层架构往往是一个合适的起点。

它之所以在很多项目里成为默认选择，不是因为它“最先进”，而是因为它在低复杂度阶段最务实。对多数团队而言，先让代码按职责分区、让调用链基本清晰，往往比一开始就引入大量抽象更重要。

3.2.2 三层架构的核心分工

三层架构的核心思想很简单：把系统按职责拆成表现层、业务逻辑层和数据访问层。如果用更统一的工程命名来表达，这三类职责通常会分别落在 interfaces、application 和 infrastructure 中。这样做的目的不是追求抽象，而是让不同类型的代码各归其位：

• 表现层（Interfaces）：接收 HTTP、RPC 或消息请求，完成参数解析和响应组装
• 业务逻辑层（Application）：承载核心业务流程，例如创建订单、计算总价、更新状态
• 数据访问层（Infrastructure 中的 persistence）：负责和数据库交互，执行查询、插入和更新操作

这里要特别注意，三层架构首先强调的是职责分层，而不是接口隔离。在这个阶段，层与层之间通常可以直接调用，不需要一开始就为每一层都设计 Port、Adapter 和复杂的依赖注入。

3.2.3 Go 项目中的典型目录映射

对于一个订单服务，这种分层通常可以组织成如下结构：

order-service/
├── cmd/
│   ├── order-server/               # 同步服务入口：HTTP / RPC
│   │   └── main.go
│   ├── order-job/                  # 定时任务入口
│   │   └── main.go
│   └── order-consumer/             # 消息消费入口
│       └── main.go
├── internal/
│   ├── interfaces/                 # 表现层：接收外部请求
│   │   ├── http/
│   │   │   └── order.go
│   │   ├── rpc/
│   │   │   └── order.go
│   │   ├── job/
│   │   │   ├── close_timeout_order.go
│   │   │   └── retry_publish.go
│   │   └── event/
│   │       ├── payment_paid.go
│   │       ├── stock_reserved.go
│   │       └── stock_failed.go
│   ├── application/                # 业务逻辑层：创单、支付、取消、关单
│   │   ├── service/
│   │   │   ├── order.go
│   │   │   ├── job.go
│   │   │   ├── consumer.go
│   │   │   └── event.go
│   │   └── dto/
│   │       ├── request.go
│   │       └── response.go
│   ├── model/                      # 早期共享模型，承载数据结构
│   │   ├── order.go
│   │   ├── request.go
│   │   └── event.go
│   ├── infrastructure/             # 基础设施：MySQL、日志、事件总线
│   │   ├── persistence/
│   │   │   ├── order.go
│   │   │   └── transaction.go
│   │   ├── event/
│   │   │   └── event_bus.go
│   │   ├── logger/
│   │   │   └── logger.go
│   │   └── mysql/
│   │       └── mysql_db.go
│   └── bootstrap/
│       └── app.go                  # 程序启动与依赖组装
└── go.mod

这里虽然目录名已经统一成了 interfaces / application / infrastructure 这套风格，但它的本质仍然是三层架构。interfaces 对应表现层，application 对应业务逻辑层，infrastructure/persistence 对应数据访问层。额外出现的 model 只是为了集中承载共享数据结构，例如 Order、CreateOrderRequest，它还不是后续 DDD 阶段那种真正承担业务规则的 domain。

3.2.4 一个订单服务的调用链

以“创建订单”接口为例，这条调用链通常是这样的：

HTTP / RPC 请求
    -> interfaces.CreateOrder
    -> application.CreateOrder
    -> infrastructure.persistence.Save
    -> MySQL

在这条链路中，每一层都只做自己该做的事情。

**表现层（Interfaces）**负责与外部世界打交道。它知道请求从哪里来，也知道响应该怎么返回，但它不应该承担核心业务判断。一个典型的创单 Handler 通常会做下面几件事：

• 接收 HTTP 或 RPC 请求
• 解析 customer_id、商品列表等参数
• 做最基础的参数合法性校验
• 调用 OrderService.CreateOrder
• 把结果组装成 API 响应返回

也就是说，表现层回答的是“外部如何调用系统”，而不是“系统内部如何完成下单”。

**业务逻辑层（Application）**是三层架构的中心。它负责把“创建订单”这个业务动作真正组织起来，例如校验商品列表是否为空、计算订单总价、生成订单号、设置订单初始状态、调用 Repository 持久化订单，以及在需要时发布订单创建事件。

示例代码可以写成这样：

// application/service/order.go — 标准三层架构中的业务逻辑层
type OrderService struct {
    repo *persistence.OrderRepository  // 直接依赖具体实现
    db   *sql.DB
}

func (s *OrderService) CreateOrder(ctx context.Context, req CreateOrderReq) (*Order, error) {
    order := &Order{
        CustomerID: req.CustomerID,
        Items:      req.Items,
    }
    order.Total = s.calculateTotal(order.Items)
    return s.repo.Save(ctx, order)
}

这段代码很好地体现了三层架构在早期的特点：简单、直接、上手快。Application Service 直接依赖持久化实现，不需要先设计接口、适配器、领域对象等抽象。对于一个业务规则还不复杂的系统来说，这种直接性反而能提高开发效率。

**数据访问层（Infrastructure/Persistence）**的职责是把业务层提出的“保存订单”“查询订单”这些需求，翻译成具体的数据库操作。例如，OrderRepository 里可能包含下面这些方法：

• Save(order)：插入或更新订单
• FindByID(orderID)：根据订单 ID 查询订单
• ListPendingPaymentBefore(t)：查询超时未支付订单

它的价值在于：把 SQL、表结构、连接池、事务细节集中到一个位置。这样，业务层不需要到处散落 SQL 语句，表现层也不必知道数据库长什么样。

3.2.5 为什么这种结构在项目初期很好用

在标准三层架构中，层与层之间通常不需要一开始就为每一层专门定义接口和适配器。更常见的做法是：

• interfaces 直接调用 application
• application 直接调用 infrastructure/persistence
• 各层之间通过普通的函数签名和结构体协作

也就是说，三层架构首先解决的是“代码应该放在哪一层”，而不是“核心业务到底应该依赖谁”。这也是它和后续 Clean Architecture 的关键区别。

这种结构在项目初期很好用，通常有三个原因。

第一，它容易理解。即使团队成员没有 DDD 或 Clean Architecture 背景，也能快速知道一个需求应该落在哪一层。

第二，它开发成本低。不需要在一开始就设计大量接口和抽象，代码路径短，调试方便，适合快速迭代。

第三，它足够支撑早期业务。对于订单创建、订单查询、支付回调、超时关单这类相对直接的业务流程，三层架构通常已经可以胜任。

换句话说，三层架构不是“过时的做法”，而是在业务复杂度还低时，一种成本最低的秩序化手段。

3.2.6 三层架构的边界与典型问题

三层架构的问题，通常不是一开始就出现，而是在业务逐渐变复杂时慢慢显现。最常见的几个信号是：

• Application 层越来越大，开始同时处理业务规则、事务、SQL 细节和外部依赖
• Infrastructure/Persistence 和数据库实现耦合过深，换存储成本高
• Model 逐渐退化成纯数据结构，真正的业务规则散落在多个 Application Service 方法里
• 单元测试越来越困难，因为业务逻辑强依赖数据库和基础设施
• 同一个“订单”概念，在不同模块里开始出现不一致的含义

例如，当你想把 MySQL 更换为 PostgreSQL 时，可能会发现 Application 层虽然没有直接操作数据库连接，但它已经对持久化实现、事务组织方式，甚至某些 MySQL 特有能力形成了隐式依赖。此时，问题就不再只是“换个数据库驱动”这么简单，而是说明：业务逻辑与基础设施实现已经纠缠在一起了。

这正是三层架构的边界所在。它非常适合作为系统的起点，但当复杂度继续增长时，仅靠“Interfaces / Application / Persistence”这条主线，已经不足以持续控制系统复杂性。接下来，就需要进一步引入更明确的依赖边界、更强的业务模型表达，以及更清晰的读写分离策略。这也是后续要引入 Clean Architecture、DDD 和 CQRS 的原因。

3.3 Clean Architecture（整洁架构）

3.3.1 核心思想：依赖规则

Clean Architecture 由 Robert C. Martin（Uncle Bob）在 2012 年提出，其核心思想非常简单：

业务逻辑应该独立于 UI、数据库、框架或任何外部代理。

这句话的含义是：当你决定从 MySQL 换到 PostgreSQL，或者把 Web 框架从 Gin 换到 Echo 时，核心的业务逻辑（Use Cases 和 Entities）不需要改动一行代码。

依赖规则：源代码的依赖方向只能向内。外层（如数据库、Web 框架）可以依赖内层，但内层绝不能知道外层的存在。

┌──────────────────────────────────────────────────────────────┐
│  Frameworks & Drivers  (Web, DB, External APIs)              │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  Interface Adapters  (Controllers, Gateways, Repos)  │    │
│  │  ┌──────────────────────────────────────────────┐    │    │
│  │  │  Application Business Rules  (Use Cases)     │    │    │
│  │  │  ┌──────────────────────────────────────┐    │    │    │
│  │  │  │  Enterprise Business Rules (Entities) │    │    │    │
│  │  │  └──────────────────────────────────────┘    │    │    │
│  │  └──────────────────────────────────────────────┘    │    │
│  └──────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────┘

                   依赖方向 ──────→ 向内

3.3.2 四层模型

Clean Architecture 将系统划分为四层，每层有清晰的职责：

关键理解：

• Entity 层是纯业务逻辑，不知道 HTTP、数据库、消息队列的存在
• Use Case 层编排业务流程，依赖 Entity 层的接口，不依赖具体实现
• Adapter 层连接内外，实现 Entity/Use Case 层定义的接口
• Framework 层是具体的技术选型，可以随时替换

3.3.3 Go 项目中的典型目录映射

在 Go 项目中，Clean Architecture 通常可以映射成和前面三层架构相近、但依赖方向更清晰的目录结构。例如，一个 order-service 可以演进成这样：

order-service/
├── cmd/
│   ├── order-server/
│   │   └── main.go                     # HTTP / RPC 服务入口
│   ├── order-job/
│   │   └── main.go                     # 定时任务入口
│   └── order-consumer/
│       └── main.go                     # 消息消费入口
├── internal/
│   ├── interfaces/                     # 接口层：所有进入系统的请求入口
│   │   ├── http/
│   │   │   ├── order.go
│   │   │   └── health.go
│   │   ├── rpc/
│   │   │   └── order.go
│   │   ├── event/
│   │   │   ├── payment_paid.go
│   │   │   ├── stock_reserved.go
│   │   │   └── stock_failed.go
│   │   └── job/
│   │       ├── close_timeout_order.go
│   │       └── retry_publish.go
│   ├── application/                    # 应用层：编排业务用例
│   │   ├── service/
│   │   │   ├── create_order.go
│   │   │   ├── cancel_order.go
│   │   │   ├── mark_order_paid.go
│   │   │   └── close_timeout_order.go
│   │   ├── dto/
│   │   │   ├── request.go
│   │   │   ├── response.go
│   │   │   └── event.go
│   │   └── transaction.go             # 应用层依赖的事务抽象（可选）
│   ├── domain/                         # 最内层：业务概念与规则
│   │   ├── order.go                    # Order 实体 / 核心业务规则
│   │   ├── order_item.go               # OrderItem 实体 / 值对象
│   │   ├── repository.go               # Repository Port
│   │   ├── event_publisher.go          # EventPublisher Port
│   │   ├── event.go                    # 领域事件定义
│   │   └── errors.go                   # 领域错误
│   ├── infrastructure/                 # 基础设施层：技术实现
│   │   ├── persistence/
│   │   │   ├── order_repo.go           # Repository Port 的 MySQL 实现
│   │   │   ├── order_po.go             # 持久化对象 / 表映射
│   │   │   └── transaction.go          # 事务实现
│   │   ├── event/
│   │   │   └── publisher.go            # EventPublisher Port 的实现
│   │   ├── cache/
│   │   │   └── order_cache.go
│   │   ├── mysql/
│   │   │   └── db.go
│   │   ├── mq/
│   │   │   └── producer.go
│   │   ├── logger/
│   │   │   └── logger.go
│   │   └── config/
│   │       └── config.go
│   └── bootstrap/
│       ├── app.go                      # 依赖注入
│       ├── router.go                   # HTTP / RPC 路由注册
│       └── wiring.go                   # application / interfaces / infrastructure 组装
├── api/
│   ├── http/
│   │   └── order.md
│   └── proto/
│       └── order.proto
└── go.mod

关键设计原则：

1. 依赖方向向内：interfaces 依赖 application，application 依赖 domain，infrastructure 负责从外层实现内层需要的能力
2. 接口在内层定义：例如 internal/domain/repository.go 定义 Port，internal/infrastructure/persistence/order_repo.go 提供实现
3. 框架在外层：Gin、MySQL、Kafka、Redis 等技术细节都停留在 interfaces 或 infrastructure，不会侵入核心业务

3.3.4 三层架构与 Clean Architecture 的区别

这一点非常容易被误解。很多团队以为自己已经做了三层分层，就等于已经做了 Clean Architecture。其实两者并不等价：

• 三层架构关注的是分层职责：表现层、业务层、数据访问层分别负责什么
• Clean Architecture 关注的是依赖方向：核心业务是否只依赖抽象，而不是依赖具体实现

所以，三层架构回答的是“代码应该放在哪一层”，而 Clean Architecture 回答的是“核心业务应该依赖谁”。

这也是为什么一个项目可以“已经分层”，但仍然没有真正获得可替换性和可测试性。只要 application/service 仍然依赖某个具体的 MySQL repository、具体的消息发布器、具体的框架对象，业务逻辑就还没有真正从基础设施中解耦出来。

3.3.5 改造要点：引入 Port，把实现推到外层

阶段 1 的关键动作通常有两个：

• 在内层定义接口，例如 OrderRepository
• 让外层提供具体实现，例如 MySQLOrderRepository

代码通常会变成这样：

// domain/repository.go — 内层定义接口
package domain

type OrderRepository interface {
    Save(ctx context.Context, order *Order) error
}

// application/service/create_order.go — 应用层依赖接口而非实现
type CreateOrderService struct {
    repo domain.OrderRepository
}

func (svc *CreateOrderService) Execute(ctx context.Context, req CreateOrderRequest) error {
    order := domain.NewOrder(req.CustomerID)
    // ... 应用逻辑 ...
    return svc.repo.Save(ctx, order)
}

在这段代码里，CreateOrderService 并不知道底层是不是 MySQL，也不知道外面是不是 HTTP Handler 调用它。它只关心“创建订单”这件业务本身。这种内层稳定、外层可替换的结构，就是 Clean Architecture 的核心价值。

3.3.6 以一个订单服务的调用链为例

如果把 Clean Architecture 放到一个具体的 order-service 中，它的调用链通常会比三层架构多出一层清晰的“依赖反转”：

HTTP 请求
    -> adapter/inbound/http.OrderHandler
    -> usecase.PlaceOrderUseCase
    -> domain.Order / domain.Repository
    -> adapter/outbound/persistence.MySQLOrderRepo
    -> MySQL

这条链路的关键，不只是“多了几层目录”，而是每一层的依赖关系开始变得可控：

• HTTP Handler 只负责接收请求、解析参数、返回响应
• Use Case 只负责组织业务流程，不直接操作数据库
• Domain 负责承载核心业务规则和抽象接口
• Outbound Adapter 负责把领域层定义的接口落到 MySQL、Redis 或 MQ 上

从外面看，它和三层架构一样，仍然是在处理“下单请求”；但从里面看，业务逻辑和基础设施已经不再直接耦合。也正因为如此，后面不管你是替换存储、补单元测试，还是进一步引入 DDD，都有了更清晰的落脚点。

3.3.7 核心价值：技术无关的业务逻辑

让我们通过一个具体的代码示例来理解 Clean Architecture 的价值。

反例：依赖具体实现

// ❌ 反例：OrderService 直接依赖具体的 MySQL 实现
package service

import (
    "database/sql"
    _ "github.com/go-sql-driver/mysql"
)

type OrderService struct {
    db *sql.DB  // 直接依赖 MySQL
}

func (s *OrderService) CreateOrder(ctx context.Context, req CreateOrderReq) (*Order, error) {
    // 业务逻辑和数据库操作混在一起
    tx, err := s.db.BeginTx(ctx, nil)
    if err != nil {
        return nil, err
    }
    defer tx.Rollback()
    
    order := &Order{
        CustomerID: req.CustomerID,
        Items:      req.Items,
        Total:      calculateTotal(req.Items),
    }
    
    // SQL 语句直接写在业务逻辑中
    _, err = tx.ExecContext(ctx, 
        "INSERT INTO orders (customer_id, total, status) VALUES (?, ?, ?)",
        order.CustomerID, order.Total, "pending")
    if err != nil {
        return nil, err
    }
    
    return order, tx.Commit()
}

问题：

1. 业务逻辑和数据库操作混在一起，难以测试
2. 换数据库（如 PostgreSQL）需要改动业务逻辑代码
3. 无法编写不依赖数据库的单元测试
4. OrderService 直接依赖 database/sql 和 MySQL 驱动

正例：依赖抽象

// ✅ 正例：Clean Architecture 方式

// domain/order/repository.go — 内层只定义接口
package order

type Repository interface {
    Save(ctx context.Context, order *Order) error
    FindByID(ctx context.Context, id string) (*Order, error)
}

// domain/order/order.go — 领域模型
package order

type Order struct {
    id         string
    customerID string
    items      []OrderItem
    status     Status
    totalPrice Money
}

func NewOrder(customerID string) *Order {
    return &Order{
        id:         generateID(),
        customerID: customerID,
        items:      make([]OrderItem, 0),
        status:     StatusDraft,
    }
}

func (o *Order) AddItem(product Product, qty int) error {
    if o.status != StatusDraft {
        return ErrOrderNotEditable
    }
    if qty <= 0 {
        return ErrInvalidQuantity
    }
    item := NewOrderItem(product, qty)
    o.items = append(o.items, item)
    o.recalculateTotal()
    return nil
}

func (o *Order) Place() error {
    if len(o.items) == 0 {
        return ErrEmptyOrder
    }
    o.status = StatusPlaced
    return nil
}

// usecase/place_order.go — Use Case 依赖接口而非实现
package usecase

import "myapp/domain/order"

type PlaceOrderUseCase struct {
    orderRepo order.Repository  // 依赖抽象接口
}

func (uc *PlaceOrderUseCase) Execute(ctx context.Context, req PlaceOrderRequest) (*PlaceOrderResponse, error) {
    // 创建订单聚合
    o := order.NewOrder(req.CustomerID)
    
    // 添加商品
    for _, item := range req.Items {
        product := order.Product{ID: item.ProductID, Price: item.Price}
        if err := o.AddItem(product, item.Quantity); err != nil {
            return nil, err
        }
    }
    
    // 下单
    if err := o.Place(); err != nil {
        return nil, err
    }
    
    // 持久化（通过接口）
    if err := uc.orderRepo.Save(ctx, o); err != nil {
        return nil, err
    }
    
    return &PlaceOrderResponse{OrderID: o.ID()}, nil
}

// adapter/persistence/mysql_order_repo.go — 外层实现接口
package persistence

import (
    "database/sql"
    "myapp/domain/order"
)

type MySQLOrderRepo struct {
    db *sql.DB
}

func NewMySQLOrderRepo(db *sql.DB) order.Repository {
    return &MySQLOrderRepo{db: db}
}

func (r *MySQLOrderRepo) Save(ctx context.Context, o *order.Order) error {
    _, err := r.db.ExecContext(ctx,
        "INSERT INTO orders (id, customer_id, total, status) VALUES (?, ?, ?, ?)",
        o.ID(), o.CustomerID(), o.Total().Amount, o.Status().String())
    return err
}

func (r *MySQLOrderRepo) FindByID(ctx context.Context, id string) (*order.Order, error) {
    // 实现查询逻辑
    // ...
    return nil, nil
}

// adapter/persistence/mongo_order_repo.go — 换存储只需新增实现
package persistence

import (
    "go.mongodb.org/mongo-driver/mongo"
    "myapp/domain/order"
)

type MongoOrderRepo struct {
    collection *mongo.Collection
}

func NewMongoOrderRepo(col *mongo.Collection) order.Repository {
    return &MongoOrderRepo{collection: col}
}

func (r *MongoOrderRepo) Save(ctx context.Context, o *order.Order) error {
    _, err := r.collection.InsertOne(ctx, bson.M{
        "_id":         o.ID(),
        "customer_id": o.CustomerID(),
        "total":       o.Total().Amount,
        "status":      o.Status().String(),
    })
    return err
}

对比收益：

3.3.8 依赖注入的 Go 实现

在 Clean Architecture 中，组装（将接口与实现绑定）发生在最外层——通常是 main.go 或 cmd/server/main.go。

方式一：手动注入（推荐，适合中小项目）

// cmd/server/main.go
package main

import (
    "database/sql"
    "log"
    "myapp/adapter/inbound/http"
    "myapp/adapter/outbound/persistence"
    "myapp/infra/mysql"
    "myapp/usecase"
    
    _ "github.com/go-sql-driver/mysql"
    "github.com/gin-gonic/gin"
)

func main() {
    // 1. Infrastructure 层：初始化基础设施
    db, err := sql.Open("mysql", "user:pass@tcp(localhost:3306)/mydb")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // 2. Adapter 层：创建实现（实现 domain 接口）
    orderRepo := persistence.NewMySQLOrderRepo(db)
    productRepo := persistence.NewMySQLProductRepo(db)

    // 3. Use Case 层：注入依赖
    placeOrderUC := usecase.NewPlaceOrderUseCase(orderRepo, productRepo)
    cancelOrderUC := usecase.NewCancelOrderUseCase(orderRepo)

    // 4. Adapter 层（Inbound）：创建 HTTP Handler
    orderHandler := http.NewOrderHandler(placeOrderUC, cancelOrderUC)

    // 5. Framework 层：启动 Web 服务器
    router := gin.Default()
    orderHandler.RegisterRoutes(router)
    router.Run(":8080")
}

优点：

• 零依赖，不需要引入任何 DI 框架
• 编译时检查，类型安全
• 调试直观，依赖关系一目了然

缺点：

• 当依赖超过 20 个时，main.go 变得冗长
• 手动管理依赖顺序，容易出错

方式二：Wire（适合大型项目）

Google 的 Wire 通过代码生成实现依赖注入：

// cmd/server/wire.go
//go:build wireinject

package main

import (
    "myapp/adapter/inbound/http"
    "myapp/adapter/outbound/persistence"
    "myapp/infra/mysql"
    "myapp/usecase"
    
    "github.com/google/wire"
)

func InitializeOrderHandler() (*http.OrderHandler, error) {
    wire.Build(
        // Infrastructure
        mysql.NewConnection,
        
        // Adapters (Outbound)
        persistence.NewMySQLOrderRepo,
        persistence.NewMySQLProductRepo,
        
        // Use Cases
        usecase.NewPlaceOrderUseCase,
        usecase.NewCancelOrderUseCase,
        
        // Adapters (Inbound)
        http.NewOrderHandler,
    )
    return nil, nil
}

运行 wire ./cmd/server 后，Wire 会自动生成 wire_gen.go：

// Code generated by Wire. DO NOT EDIT.

func InitializeOrderHandler() (*http.OrderHandler, error) {
    db, err := mysql.NewConnection()
    if err != nil {
        return nil, err
    }
    orderRepo := persistence.NewMySQLOrderRepo(db)
    productRepo := persistence.NewMySQLProductRepo(db)
    placeOrderUC := usecase.NewPlaceOrderUseCase(orderRepo, productRepo)
    cancelOrderUC := usecase.NewCancelOrderUseCase(orderRepo)
    handler := http.NewOrderHandler(placeOrderUC, cancelOrderUC)
    return handler, nil
}

优点：

• 自动处理依赖顺序
• 编译时检查，类型安全
• 适合大型项目（100+ 依赖）

缺点：

• 需要学习 Wire 的 API
• 代码生成可能影响调试体验

方式三：Uber Fx（运行时注入）

// cmd/server/main.go
package main

import (
    "go.uber.org/fx"
    "myapp/adapter/inbound/http"
    "myapp/adapter/outbound/persistence"
    "myapp/infra/mysql"
    "myapp/usecase"
)

func main() {
    fx.New(
        // Infrastructure
        fx.Provide(mysql.NewConnection),
        
        // Adapters
        fx.Provide(persistence.NewMySQLOrderRepo),
        fx.Provide(persistence.NewMySQLProductRepo),
        
        // Use Cases
        fx.Provide(usecase.NewPlaceOrderUseCase),
        fx.Provide(usecase.NewCancelOrderUseCase),
        
        // HTTP Handler
        fx.Provide(http.NewOrderHandler),
        
        // Start server
        fx.Invoke(func(h *http.OrderHandler) {
            router := gin.Default()
            h.RegisterRoutes(router)
            router.Run(":8080")
        }),
    ).Run()
}

优点：

• 支持生命周期管理（启动/关闭钩子）
• 支持依赖图可视化
• 适合微服务框架

缺点：

• 运行时注入，类型错误要到运行时才能发现
• 学习曲线较陡

推荐选择：

• 小型项目（<50 个依赖）：手动注入
• 中型项目（50-200 个依赖）：Wire
• 大型项目（200+ 个依赖，微服务）：Fx

3.3.9 为什么这一步通常早于 DDD

很多读者会问：既然后面还要引入 DDD，为什么不一步到位？原因是 Clean Architecture 先解决的是一个更基础的问题：先把业务逻辑和技术实现拆开。

在这一步之前，系统最大的问题往往不是“领域模型不够优雅”，而是“业务代码和基础设施绑得太紧”。如果这个问题不先处理，后面即使想引入聚合根、值对象、领域事件，也很容易被外层技术细节拖住，导致模型表达和工程实现互相污染。

所以，从演进顺序上看，先引入 Clean Architecture，往往比直接上 DDD 更稳妥。它为后续的领域建模先清出了一块相对干净的内层空间。

3.3.10 收益：可替换、可测试、可演进

引入 Clean Architecture 之后，最直接的收益通常有三个。

第一，更容易替换基础设施。MySQL、PostgreSQL、Redis、消息中间件都变成外层实现细节，而不是业务层的一部分。

第二，更容易做单元测试。CreateOrderService 可以直接注入 Mock Repository 进行测试，不需要启动数据库。

第三，为后续演进留出空间。当业务复杂度进一步上升时，你可以在内层继续引入更强的领域模型表达，而不必同时和框架、数据库实现纠缠。

当然，代价也很明显：目录更多、抽象更多、依赖注入也更复杂。对于业务非常简单的项目，这一步可能会显得“有点重”。但一旦系统已经出现“换数据库很痛”“单元测试写不动”“业务层越来越黏住基础设施”这些信号，引入 Clean Architecture 往往是值得的。

3.3.11 架构风格对比：Clean vs 六边形 vs 洋葱

在学习 Clean Architecture 时，你可能还会遇到另外两个相似的概念：六边形架构（Hexagonal Architecture） 和 洋葱架构（Onion Architecture）。它们经常被混用，但实际上有细微差别：

graph TB
    subgraph "Clean Architecture"
        direction TB
        CA_E[Entity] 
        CA_U[Use Case] --> CA_E
        CA_A[Adapter] --> CA_U
        CA_F[Framework] --> CA_A
    end
    
    subgraph "Hexagonal"
        direction TB
        H_D[Domain Core]
        H_PI[Inbound Port] --> H_D
        H_PO[Outbound Port] --> H_D
        H_AI[Driving Adapter] --> H_PI
        H_AO[Driven Adapter] --> H_PO
    end

    subgraph "Onion"
        direction TB
        O_DM[Domain Model]
        O_DS[Domain Service] --> O_DM
        O_AS[App Service] --> O_DS
        O_IF[Infrastructure] --> O_AS
    end

实际差异很小，三者在 Go 项目中的落地几乎一样——关键是守住一条线：内层定义接口，外层实现接口。

Port & Adapter 模式的 Go 实现

六边形架构中，**Port（端口）**是接口，**Adapter（适配器）**是实现。在 Go 中天然契合：

// domain/port.go — Outbound Port（领域层定义接口）
package domain

type PaymentGateway interface {
    Charge(ctx context.Context, orderID string, amount Money) (*PaymentResult, error)
}

// adapter/payment/stripe_adapter.go — Driven Adapter（基础设施层实现接口）
package payment

import (
    "myapp/domain"
    "github.com/stripe/stripe-go/v72"
)

type StripeAdapter struct {
    client *stripe.Client
}

func NewStripeAdapter(apiKey string) domain.PaymentGateway {
    return &StripeAdapter{
        client: stripe.NewClient(apiKey),
    }
}

func (a *StripeAdapter) Charge(ctx context.Context, orderID string, amount domain.Money) (*domain.PaymentResult, error) {
    params := &stripe.ChargeParams{
        Amount:   stripe.Int64(amount.Amount),
        Currency: stripe.String(amount.Currency),
    }
    resp, err := a.client.Charges.New(params)
    if err != nil {
        return nil, fmt.Errorf("stripe charge failed: %w", err)
    }
    return &domain.PaymentResult{
        TransactionID: resp.ID, 
        Status:        "success",
    }, nil
}

// adapter/payment/mock_adapter.go — 测试时可替换为 Mock
package payment

type MockPaymentAdapter struct {
    ShouldFail bool
}

func NewMockPaymentAdapter() domain.PaymentGateway {
    return &MockPaymentAdapter{ShouldFail: false}
}

func (a *MockPaymentAdapter) Charge(ctx context.Context, orderID string, amount domain.Money) (*domain.PaymentResult, error) {
    if a.ShouldFail {
        return nil, errors.New("mock payment failure")
    }
    return &domain.PaymentResult{
        TransactionID: "mock-txn-001", 
        Status:        "success",
    }, nil
}

关键理解：

• Port（接口）在领域层定义，表达“我需要什么能力“
• Adapter（实现）在基础设施层提供，表达“我如何提供这个能力“
• 测试时，可以用 Mock Adapter 替换真实的 Stripe Adapter
• 换支付渠道（如从 Stripe 换到支付宝），只需新增一个 Adapter

3.3.12 反模式：常见违规案例

在实际项目中，Clean Architecture 的违规往往不是故意的，而是在时间压力下“顺手“写下的。以下是三个最常见的反模式：

Anti-pattern 1：跨层调用

// ❌ 反例：Handler 直接引用了 MySQL 包（跳过了 domain 和 usecase 层）
package handler

import (
    "database/sql"
    "net/http"
)

func GetOrder(db *sql.DB) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        row := db.QueryRow("SELECT * FROM orders WHERE id = ?", r.URL.Query().Get("id"))
        // 直接在 handler 里写 SQL...
    }
}

问题：

• Handler 直接依赖数据库，无法测试
• 业务逻辑散落在各个 Handler 中，无法复用
• 换数据库需要改动所有 Handler

// ✅ 正例：Handler 只依赖 Use Case 接口
package handler

type OrderQuerier interface {
    GetOrderDetail(ctx context.Context, id string) (*OrderDetailDTO, error)
}

type OrderHandler struct {
    querier OrderQuerier
}

func NewOrderHandler(q OrderQuerier) *OrderHandler {
    return &OrderHandler{querier: q}
}

func (h *OrderHandler) GetOrder(w http.ResponseWriter, r *http.Request) {
    dto, err := h.querier.GetOrderDetail(r.Context(), r.URL.Query().Get("id"))
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    json.NewEncoder(w).Encode(dto)
}

Anti-pattern 2：基础设施泄漏到领域层

// ❌ 反例：领域实体中使用了 sql.NullString（基础设施类型侵入领域）
package domain

import "database/sql"

type Order struct {
    ID       string
    Remark   sql.NullString  // ← 领域层不应该知道 SQL 的存在
    Status   int             // ← 用魔数表示状态
}

问题：

• sql.NullString 是 database/sql 包的类型，领域层不应该依赖基础设施包
• 领域模型变得“贫血“，只是数据容器，没有行为

// ✅ 正例：领域层使用纯 Go 类型，转换在 adapter 层完成
package domain

type Order struct {
    id     OrderID       // 强类型 ID
    remark string        // 空字符串表示无备注
    status OrderStatus   // 枚举类型，不是魔数
    items  []OrderItem
}

func (o *Order) UpdateRemark(remark string) error {
    if len(remark) > 500 {
        return ErrRemarkTooLong
    }
    o.remark = remark
    return nil
}

// adapter/persistence/converter.go — 在 Adapter 层做类型转换
func toDomain(po *OrderPO) *domain.Order {
    remark := ""
    if po.Remark.Valid {
        remark = po.Remark.String
    }
    status := domain.StatusFromInt(po.Status)
    return domain.ReconstructOrder(
        domain.OrderID(po.ID),
        remark,
        status,
        toItemList(po.Items),
    )
}

func toPO(o *domain.Order) *OrderPO {
    return &OrderPO{
        ID:     string(o.ID()),
        Remark: sql.NullString{String: o.Remark(), Valid: o.Remark() != ""},
        Status: o.Status().ToInt(),
    }
}

Anti-pattern 3：循环依赖

❌ domain/order.go imports adapter/notification
   adapter/notification imports domain/order
   → 编译失败：import cycle

问题：

• Go 不允许循环依赖，编译直接报错
• 即使在允许循环依赖的语言（如 C#），也会导致模块耦合

解法：在 domain 层定义 Notifier 接口，adapter 层实现它。方向始终向内。

// domain/notifier.go — 领域层定义接口
package domain

type Notifier interface {
    NotifyOrderPlaced(ctx context.Context, order *Order) error
}

// usecase/place_order.go — Use Case 依赖接口
type PlaceOrderUseCase struct {
    orderRepo order.Repository
    notifier  domain.Notifier  // 依赖抽象
}

func (uc *PlaceOrderUseCase) Execute(ctx context.Context, req PlaceOrderRequest) error {
    // ... 创建订单 ...
    if err := uc.orderRepo.Save(ctx, o); err != nil {
        return err
    }
    // 通过接口调用通知
    return uc.notifier.NotifyOrderPlaced(ctx, o)
}

// adapter/notification/sms_notifier.go — Adapter 层实现接口
package notification

type SMSNotifier struct {
    smsClient *SMSClient
}

func (n *SMSNotifier) NotifyOrderPlaced(ctx context.Context, order *domain.Order) error {
    message := fmt.Sprintf("您的订单 %s 已创建", order.ID())
    return n.smsClient.Send(ctx, order.CustomerPhone(), message)
}

依赖方向：

domain (定义 Notifier 接口)
   ↑
usecase (依赖 Notifier 接口)
   ↑
adapter/notification (实现 Notifier 接口)

3.4 DDD（领域驱动设计）

3.4.1 战略设计：架构层面

DDD 不是一种架构，而是一套方法论。它认为软件的灵魂在于其解决的业务问题（即“领域“）。

DDD 分为两个层面：

• 战略设计：架构层面，关注如何划分领域、如何确定投资策略、如何划分上下文边界
• 战术设计：代码层面，关注如何用聚合、实体、值对象等战术模式编写高质量的领域模型

我们先讲战略设计。

3.4.2 领域分层与投资策略

为什么需要领域分层？

一个中大型系统往往包含十几个甚至几十个子系统。假设你是一家电商平台的 CTO，面对以下子系统：

• 订单系统、支付系统、商品管理、库存管理
• 用户系统、搜索系统、推荐系统、评价系统
• 消息通知、物流跟踪、风控系统、数据报表

核心问题：资源有限（人力、预算、时间），不可能对所有子系统投入同等精力。如何决定：

• 哪些系统必须自研，投入最好的团队？
• 哪些系统可以定制开发，用常规团队？
• 哪些系统直接买现成方案或用开源？

如果投资决策错误：

• ❌ 把资源浪费在通用能力上（如自研消息队列），错失核心业务创新
• ❌ 在核心竞争力上妥协（如用低质量的订单系统），导致业务受限

DDD 的答案：按照业务价值对领域分层，实施差异化投资策略。这就是核心域（Core Domain）、支撑域（Supporting Domain）、通用域（Generic Domain）的由来。

三种领域的定义与特征

核心域（Core Domain）：

• 什么是“核心竞争力“？ 直接影响营收、用户体验、留存率的能力，是公司在市场中胜出的关键
• 特点：频繁变化（紧跟业务创新）、技术复杂、需要领域专家
• 识别标志：如果这个域做不好，公司会输；如果做得特别好，会赢
• 案例：电商的订单系统、金融的交易系统、SaaS 的租户管理

支撑域（Supporting Domain）：

• 为什么“必须有但不差异化“？ 业务依赖但不产生竞争优势，做到 80 分和 95 分对业务影响不大
• 特点：相对稳定、有一定复杂度、需要理解业务
• 识别标志：缺了不行，但不是赢的关键
• 案例：电商的商品管理、金融的账户系统、SaaS 的权限系统

通用域（Generic Domain）：

• 为什么可以采购？ 行业已有成熟方案，无需重复造轮子，自研的投入产出比很低
• 特点：标准化、变化少、技术成熟
• 识别标志：市面上有多个成熟产品可选
• 风险：过度依赖外部服务，但可通过多供应商策略缓解
• 案例：用户认证（Auth0/Keycloak）、消息推送（Twilio）、存储（AWS S3）

领域划分方法论

如何判断一个子域属于哪一类？ 下面提供一套可操作的评分框架。

判断维度与评分模型

评分方法：

• 每个维度打分 1-10 分
• 总分 = 四个维度分数相加（满分 40 分）

总分判断标准：

• 32-40 分 → 核心域（Core Domain）
• 16-31 分 → 支撑域（Supporting Domain）
• 4-15 分 → 通用域（Generic Domain）

注意事项：

• 边界分数（如 31-32 分）需要结合公司战略、团队能力综合判断
• 初创公司可以适当放宽核心域标准（28 分以上即可），聚焦资源
• 成熟公司标准更严格，避免核心域过多导致资源分散

方法论应用：电商系统实战分析

下面选择电商系统的 3 个典型域，应用评分模型进行深度分析。

案例 1：订单域（核心域）

为什么是核心域？

• 订单流程的流畅度直接影响用户下单转化率
• 支持的营销玩法越丰富，平台竞争力越强
• 每个促销活动都可能需要调整订单逻辑
• 技术上涉及多个复杂的分布式系统问题

投资建议：

• 团队配置：最优秀的架构师 + 3-5 名资深后端开发，独立团队
• 技术选型：自研，完全掌控，不依赖外部服务
• 质量要求：99.99% 可用性，全链路监控，灰度发布
• 迭代策略：快速响应业务需求，2 周一个迭代
• 文档要求：完整的设计文档、接口文档、故障预案

案例 2：商品域（支撑域）

为什么是支撑域？

• 商品管理做到 80 分和 95 分，对用户体验影响不大
• SPU/SKU 模型是行业通用方案，没有太多创新空间
• 但又不能没有（缺了商品管理，电商就玩不转）

投资建议：

• 团队配置：常规开发团队 2-3 人，可以与其他支撑域共享资源
• 技术选型：参考业界成熟方案（如有赞、Shopify 的商品模型），适度定制
• 质量要求：99.9% 可用性，降级策略
• 迭代策略：稳定为主，谨慎迭代，充分测试后再上线
• 文档要求：基础设计文档和接口文档

案例 3：用户域（通用域）

为什么是通用域？

• 注册登录不会成为平台的竞争优势
• 市面上有大量成熟的身份认证服务
• 自研的投入产出比很低

投资建议：

• 团队配置：外包或使用 SaaS 服务，内部只需 1 人对接
• 技术选型：采购（Auth0、Keycloak、AWS Cognito）
• 质量要求：依赖服务商 SLA（通常 99.95%+）
• 迭代策略：按需对接新的认证方式（如生物识别），最小投入
• 文档要求：对接文档即可

跨行业对比：方法论的通用性

同样的方法论在不同行业如何应用？下表展示三个典型行业的域划分：

关键洞察：

1. 核心域因行业而异：

   • 电商的核心是「交易流程」和「资金安全」
   • 金融的核心是「买卖撮合」和「风控合规」
   • SaaS 的核心是「多租户」和「订阅计费」
   • → 核心域反映了行业的本质和竞争焦点

2. 通用域高度相似：

   • 用户、消息、存储在各行业都是通用域
   • 这些能力已经高度标准化，有大量成熟方案
   • → 通用域是「不需要重新发明轮子」的领域

3. 支撑域体现业务特点：

   • 电商的商品、库存、计价有一定特色，但不是核心竞争力
   • 金融的账户、清结算是必需的，但各家差异不大
   • SaaS 的权限、审计是基础能力，但实现相对标准
   • → 支撑域是「需要理解业务，但可以参考业界实践」的领域

3.4.3 限界上下文（Bounded Context）

同一个“商品“在不同的上下文中有完全不同的含义：

 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
 │   商品上下文      │     │   订单上下文      │     │   物流上下文      │
 │                  │     │                  │     │                  │
 │  商品 = SKU +    │     │  商品 = 商品快照 + │     │  商品 = 包裹 +    │
 │  价格 + 库存     │     │  购买数量 + 金额   │     │  重量 + 体积      │
 └─────────────────┘     └─────────────────┘     └─────────────────┘

为什么需要限界上下文？

在一个大型系统中，如果所有模块都对“商品“有统一的定义，会导致：

• ❌ 商品模型越来越臃肿（既要支持展示，又要支持下单，还要支持物流）
• ❌ 一个模块的需求变化影响所有其他模块
• ❌ 团队之间沟通成本巨大（每次讨论都要对齐“商品“的定义）

Bounded Context 的解决方案：

• 每个上下文内，“商品“有自己的定义和模型
• 上下文之间通过明确的接口或领域事件通信
• 上下文内部的变化，不会影响其他上下文

电商系统的 Bounded Context 示例：

graph TB
    subgraph 商品上下文
        P1[Product<br/>SKU ID, Name, Price<br/>Stock, Images]
    end
    
    subgraph 订单上下文
        O1[OrderItem<br/>Product Snapshot<br/>Quantity, Price at Order Time]
    end
    
    subgraph 搜索上下文
        S1[SearchDocument<br/>SKU ID, Title, Price<br/>Category, Sales Count]
    end
    
    商品上下文 -->|商品变更事件| 订单上下文
    商品上下文 -->|索引同步| 搜索上下文

不同上下文之间通过防腐层（Anti-Corruption Layer）或领域事件通信，避免概念混淆。我们会在 3.4.4 详细讲解。

3.4.4 上下文映射（Context Map）

限界上下文划分好之后，它们之间如何协作？Context Map（上下文映射）定义了上下文之间的关系模式。

常见的上下文关系模式

电商系统的 Context Map 实例

graph LR
    A[商品上下文] -->|发布领域事件| B[订单上下文]
    B -->|调用防腐层| C[支付上下文]
    B -->|发布领域事件| D[物流上下文]
    A -->|共享内核| E[库存上下文]
    F[供应商系统] -.->|遵奉者模式| B
    A -->|开放主机服务| G[搜索上下文]
    A -->|开放主机服务| H[营销上下文]

关系说明：

1. 商品 → 订单：发布领域事件（ProductPriceChanged），订单上下文异步消费
2. 订单 → 支付：通过防腐层调用支付API，隔离支付系统的变化
3. 订单 → 物流：发布领域事件（OrderShipped），物流上下文异步消费
4. 商品 ↔ 库存：共享内核（共享 SKU 的定义）
5. 供应商 → 订单：遵奉者模式（完全遵循供应商的履约接口）
6. 商品 → 搜索/营销：开放主机服务（提供标准化的商品查询API）

3.4.5 Go 项目中的典型目录映射

当 DDD 落到 Go 项目时，目录结构通常会围绕“限界上下文”和“聚合”展开，而不是围绕数据库表或接口协议展开。以一个订单服务为例，比较常见的组织方式如下：

order-service/
├── cmd/
│   └── server/
│       └── main.go
│
├── domain/
│   ├── order/                      # 订单上下文 / 订单聚合
│   │   ├── aggregate.go
│   │   ├── entity.go
│   │   ├── value_object.go
│   │   ├── repository.go
│   │   ├── event.go
│   │   └── service.go
│   ├── inventory/                  # 库存上下文
│   │   ├── stock.go
│   │   └── repository.go
│   └── payment/                    # 支付上下文
│       ├── payment.go
│       └── gateway.go
│
├── application/
│   ├── service/
│   │   ├── place_order.go
│   │   ├── cancel_order.go
│   │   └── mark_order_paid.go
│   └── dto/
│       ├── request.go
│       └── response.go
│
├── interfaces/
│   ├── http/
│   │   └── order.go
│   ├── rpc/
│   │   └── order.go
│   └── event/
│       └── payment_paid.go
│
└── infrastructure/
    ├── persistence/
    │   ├── order_repo.go
    │   ├── inventory_repo.go
    │   └── payment_repo.go
    ├── mq/
    └── mysql/

和阶段 1 相比，这里的核心变化不是目录变得更深，而是 domain 不再只是“放接口和几个结构体的地方”，而是开始真正承载业务语义。换句话说，阶段 1 的 domain 更像“业务核心的边界”；阶段 2 的 domain 才开始成为“业务规则真正居住的地方”。

3.4.6 从贫血模型到充血模型

阶段 1 中，很多项目虽然已经把 Order 放进了 domain，但这个 Order 仍然只是一个贫血模型：它主要承担数据承载作用，真正的规则依旧写在 application/service 里。例如：

// 阶段 1 的 "贫血模型"
type Order struct {
    ID     string
    Status int     // 用魔数表示状态
    Total  float64 // 用 float 表示金额
}

这类模型的问题在于：它看起来像“领域对象”，但实际上并没有把业务语义和不变量收进去。订单是否允许下单、是否允许取消、金额是否有效、状态能否迁移，仍然需要调用者在外面自己判断。

而在阶段 2 中，Order 会逐渐演进成一个真正的聚合根：

// 阶段 2 的 "充血模型"
type Order struct {
    id     OrderID
    status OrderStatus   // 值对象，枚举约束
    total  Money         // 值对象，精度安全
    items  []OrderItem
}

func (o *Order) Place() ([]DomainEvent, error) {
    if len(o.items) == 0 {
        return nil, ErrEmptyOrder  // 聚合根保护不变量
    }
    o.status = OrderStatusPlaced
    return []DomainEvent{OrderPlacedEvent{...}}, nil
}

这里的关键不只是把字段从公有变成私有，也不只是把 int 改成 OrderStatus。真正重要的是：业务规则开始内聚到模型本身。订单能否下单、状态如何流转、哪些约束必须被保护，不再由外部调用者“记得去做”，而是由聚合根主动维护。

3.4.7 DDD 在这一阶段具体引入什么

阶段 2 最常引入的几个战术设计元素包括：

• 聚合根（Aggregate Root）：例如 Order，它负责维护订单聚合内部的一致性边界
• 实体（Entity）：例如 OrderItem，有身份或生命周期，属于某个聚合的一部分
• 值对象（Value Object）：例如 OrderID、Money、OrderStatus，用来表达语义并约束非法状态
• 领域事件（Domain Event）：例如 OrderPlacedEvent、OrderCancelledEvent，表达“业务事实已经发生”
• 领域服务（Domain Service）：当某条业务规则不自然属于某个单一聚合时，再用领域服务承载

需要强调的是，DDD 不是要求你“把所有东西都做成值对象和事件”。它真正的目的，是让代码结构尽可能贴近业务语言，而不是贴近数据库表结构。

3.4.8 应用层在这一阶段如何变化

引入 DDD 之后，application/service 并不会消失，但它的职责会变得更清晰：它不再自己堆满业务规则，而是更像一个应用服务，负责调度聚合根、协调事务和调用 Port。

也就是说：

• 在阶段 1 中，CreateOrderService 往往自己承担很多规则判断
• 在阶段 2 中，PlaceOrderService 更像一个 orchestrator，它负责加载聚合、调用 order.Place()、保存聚合、发布领域事件

这也是为什么 DDD 不是对 Clean Architecture 的替代，而是对其内层表达能力的增强。

3.4.9 以一个订单服务的调用链为例

如果把 DDD 放到下单场景里，调用链通常会长这样：

HTTP 请求
    -> interfaces/http.OrderHandler
    -> application/service.PlaceOrderService
    -> domain/order.Order 聚合根
    -> domain/order.Repository
    -> infrastructure/persistence.OrderRepo
    -> 发布 OrderPlacedEvent

和三层架构相比，这里最重要的变化不是“步骤变多了”，而是业务规则开始收拢到聚合根内部。

例如：

• Handler 不再自己判断订单状态是否合法
• Application Service 不再堆满状态迁移和金额校验
• Order.Place()、Order.Cancel()、Order.MarkPaid() 这类方法开始成为真正的业务入口

这意味着，当我们讨论“订单能不能取消”“订单支付后能不能再次修改”时，答案主要应该在 domain/order 里找到，而不是散落在多个应用服务和数据库更新逻辑中。

3.4.10 为什么这一步值得做

当业务规则还很少时，把逻辑写在 application/service 里看起来并没有问题；但一旦规则数量和状态迁移开始增多，继续让应用层承担所有判断，很快会出现几个典型症状：

• 一个 application/service 文件动辄数百行，充满 if/else
• 状态迁移规则散落在多个命令处理器里
• 同样的金额校验、状态校验、约束判断在多个地方重复出现
• 新成员很难回答“订单到底有哪些业务规则”

这时，引入 DDD 的最大收益，就是把这些规则收拢回业务概念本身。新成员阅读 Order.Place()、Order.Cancel()、Order.MarkPaid()，就能理解订单生命周期中的核心约束，而不是在多个应用服务文件之间来回跳转。

3.4.11 收益：模型更贴近业务，规则更容易维护

阶段 2 最直接的收益通常有三个。

第一，业务规则开始真正内聚。规则不再散落在各个 application/service 中，而是集中在聚合根和相关值对象里。

第二，模型表达能力更强。Money 不再只是 float64，OrderStatus 不再只是魔数，代码本身开始带有业务语义。

第三，系统更适合继续演进。当后续要引入领域事件驱动、跨上下文协作，或者进一步拆分读写模型时，一个表达清晰的领域模型会成为非常稳固的基础。

当然，代价也很现实：DDD 的学习门槛比前两阶段更高，过度使用聚合、值对象和事件，也很容易把简单业务写得过于复杂。因此，阶段 2 的关键不是“为了 DDD 而 DDD”，而是在业务规则确实已经复杂到值得建模时，再让模型承担它本来就该承担的职责。

3.4.12 通用语言（Ubiquitous Language）

DDD 的战术设计关注的是代码层面的实现：如何用聚合、实体、值对象等战术模式编写高质量的领域模型。

战术设计概述

Go 代码示例：Order 聚合

// domain/order/order.go
package order

import (
    "errors"
    "time"
)

type OrderID string

type Order struct {
    id         OrderID
    customerID string
    items      []OrderItem
    status     OrderStatus
    totalPrice Money
    createdAt  time.Time
}

// 聚合根通过方法保护业务不变量
func (o *Order) AddItem(product Product, qty int) error {
    // 业务规则 1：只有草稿状态的订单才能添加商品
    if o.status != OrderStatusDraft {
        return ErrOrderNotEditable
    }
    // 业务规则 2：数量必须大于 0
    if qty <= 0 {
        return ErrInvalidQuantity
    }
    // 业务规则 3：同一商品不能重复添加（或合并数量）
    for i, item := range o.items {
        if item.ProductID == product.ID {
            o.items[i].Quantity += qty
            o.recalculateTotal()
            return nil
        }
    }
    
    item := NewOrderItem(product, qty)
    o.items = append(o.items, item)
    o.recalculateTotal()
    return nil
}

func (o *Order) Place() ([]DomainEvent, error) {
    // 业务规则 4：订单必须至少有一个商品
    if len(o.items) == 0 {
        return nil, ErrEmptyOrder
    }
    // 业务规则 5：只有草稿状态才能下单
    if o.status != OrderStatusDraft {
        return nil, ErrInvalidOrderStatus
    }
    
    o.status = OrderStatusPlaced
    
    // 发布领域事件
    events := []DomainEvent{
        OrderPlacedEvent{
            OrderID: o.id,
            Total:   o.totalPrice,
            At:      time.Now(),
        },
    }
    return events, nil
}

func (o *Order) recalculateTotal() {
    total := Money{Amount: 0, Currency: "USD"}
    for _, item := range o.items {
        itemTotal, _ := item.Price.Multiply(item.Quantity)
        total, _ = total.Add(itemTotal)
    }
    o.totalPrice = total
}

// Getters（聚合根控制外部访问）
func (o *Order) ID() OrderID { return o.id }
func (o *Order) CustomerID() string { return o.customerID }
func (o *Order) Status() OrderStatus { return o.status }
func (o *Order) Total() Money { return o.totalPrice }

// domain/order/money.go — Value Object（值对象）
package order

import "errors"

type Money struct {
    Amount   int64  // 使用分为单位，避免浮点精度问题
    Currency string
}

func (m Money) Add(other Money) (Money, error) {
    if m.Currency != other.Currency {
        return Money{}, ErrCurrencyMismatch
    }
    return Money{
        Amount:   m.Amount + other.Amount,
        Currency: m.Currency,
    }, nil
}

func (m Money) Multiply(factor int) (Money, error) {
    if factor < 0 {
        return Money{}, errors.New("factor must be positive")
    }
    return Money{
        Amount:   m.Amount * int64(factor),
        Currency: m.Currency,
    }, nil
}

func (m Money) String() string {
    return fmt.Sprintf("%d.%02d %s", m.Amount/100, m.Amount%100, m.Currency)
}

关键设计要点：

1. 业务规则内聚：所有的业务规则都在聚合根的方法中，而不是散落在 Service 层
2. 不变量保护：聚合根保证内部数据的一致性（如 totalPrice 始终是 items 的总和）
3. 领域事件：聚合根发生重要状态变化时，返回领域事件
4. 值对象：Money 是值对象，保证金额计算的精度和货币一致性

开发者和业务专家用同一套词汇交流，代码里的变量名就是业务里的术语：

为什么重要？

在传统的开发模式中，业务专家和开发者之间存在“翻译“过程：

• 业务专家说“用户下单后锁定库存“
• 产品经理翻译成“创建订单后更新库存状态“
• 开发者实现成 updateInventoryStatus(orderId, status=2)

问题：

• 业务术语（锁定库存）→ 技术术语（更新状态 = 2），中间丢失了业务含义
• 代码中的 status=2 没人知道是什么意思
• 业务规则隐藏在魔数和 SQL 中，无法追溯

通用语言的解决方案：

// ✅ 代码直接使用业务术语
func (s *InventoryService) LockStock(ctx context.Context, skuID string, qty int) error {
    stock, err := s.stockRepo.FindBySKU(ctx, skuID)
    if err != nil {
        return err
    }
    
    // 业务术语：锁定库存
    if err := stock.Lock(qty); err != nil {
        return err
    }
    
    return s.stockRepo.Save(ctx, stock)
}

// domain/inventory/stock.go
func (s *Stock) Lock(qty int) error {
    if s.available < qty {
        return ErrInsufficientStock
    }
    s.available -= qty
    s.locked += qty
    return nil
}

对比：

• ❌ updateInventoryStatus(orderId, status=2) — 技术术语，无业务含义
• ✅ stock.Lock(qty) — 业务术语，直接表达意图

3.4.13 聚合设计原则

聚合设计是 DDD 战术层面最难的部分。三条核心原则：

原则一：一个事务只修改一个聚合

// ❌ 反例：一个事务同时修改 Order 和 Inventory 两个聚合
func (s *OrderService) PlaceOrder(ctx context.Context, cmd PlaceOrderCmd) error {
    return s.txManager.RunInTx(ctx, func(tx *sql.Tx) error {
        order := domain.NewOrder(cmd.CustomerID)
        order.AddItem(cmd.ProductID, cmd.Qty)
        order.Place()
        s.orderRepo.SaveTx(tx, order)      // 修改 Order 聚合
        s.inventoryRepo.DeductTx(tx, cmd.ProductID, cmd.Qty) // ← 同时修改 Inventory 聚合
        return nil
    })
}

问题：

• 两个聚合在同一个事务中修改，导致锁粒度过大
• Order 和 Inventory 强耦合，无法独立演进
• 高并发场景下容易死锁

// ✅ 正例：通过领域事件实现跨聚合协作
func (s *OrderService) PlaceOrder(ctx context.Context, cmd PlaceOrderCmd) error {
    order := domain.NewOrder(cmd.CustomerID)
    order.AddItem(cmd.ProductID, cmd.Qty)
    events, err := order.Place()
    if err != nil {
        return err
    }
    
    // 只保存 Order 聚合
    if err := s.orderRepo.Save(ctx, order); err != nil {
        return err
    }
    
    // 发布事件，由 Inventory 服务异步消费
    s.eventBus.Publish(ctx, events...)
    return nil
}

// inventory 服务的事件处理器
func (h *InventoryEventHandler) OnOrderPlaced(ctx context.Context, e OrderPlacedEvent) error {
    return h.stock.Deduct(ctx, e.ProductID, e.Qty)
}

收益：

• Order 和 Inventory 解耦，可以独立扩展
• 事务范围缩小，提高并发性能
• 通过事件实现最终一致性

原则二：小聚合优于大聚合

判断标准：如果两个实体之间没有需要在同一个事务中保护的业务不变量，就应该拆成两个聚合。

示例：

// ❌ 大聚合：Order 聚合包含 Customer 的完整信息
type Order struct {
    id       OrderID
    customer *Customer  // 包含 Customer 的所有信息
    items    []OrderItem
}

// 问题：加载 Order 时被迫加载 Customer 的所有信息（地址、订单历史等）

// ✅ 小聚合：Order 只保存 CustomerID
type Order struct {
    id         OrderID
    customerID CustomerID  // 只存 ID，需要时按需查询
    items      []OrderItem
}

// 需要 Customer 信息时，通过 Repository 查询
func (uc *OrderDetailUseCase) GetOrderDetail(ctx context.Context, orderID string) (*OrderDetailDTO, error) {
    order, err := uc.orderRepo.FindByID(ctx, orderID)
    if err != nil {
        return nil, err
    }
    customer, err := uc.customerRepo.FindByID(ctx, order.CustomerID())
    if err != nil {
        return nil, err
    }
    return &OrderDetailDTO{
        OrderID:      string(order.ID()),
        CustomerName: customer.Name(),
        Items:        order.Items(),
    }, nil
}

原则三：通过 ID 引用其他聚合

// ❌ 聚合内直接持有另一个聚合的引用
type Order struct {
    customer *Customer  // 直接引用 → 加载 Order 时被迫加载 Customer
}

// ✅ 通过 ID 引用
type Order struct {
    customerID CustomerID  // 只存 ID，需要时按需查询
}

收益：

• 聚合边界清晰，加载 Order 不会加载 Customer
• 聚合之间松耦合，可以独立演进
• 减少内存占用和数据库 JOIN

3.4.14 Repository 与 Unit of Work 模式

Repository 是领域模型和持久化之间的桥梁，它提供了类似集合的接口来访问聚合。

标准 Repository 模式

// domain/order/repository.go — 领域层定义接口
package order

type Repository interface {
    Save(ctx context.Context, order *Order) error
    FindByID(ctx context.Context, id OrderID) (*Order, error)
    FindByCustomerID(ctx context.Context, customerID string, limit int) ([]*Order, error)
}

Repository 的职责：

• 提供类似集合的接口（Save, FindByID, Remove）
• 隐藏底层存储细节（MySQL/MongoDB/Redis）
• 保证聚合的完整加载和保存

Unit of Work 模式

标准 Repository 每个操作独立，但有时需要在一个事务中协调多个 Repository（例如保存聚合根 + 写 Outbox 表）。Unit of Work 模式解决这个问题：

// domain/uow.go — 领域层定义接口
package domain

type UnitOfWork interface {
    OrderRepo() order.Repository
    OutboxRepo() OutboxRepository
    Commit(ctx context.Context) error
    Rollback(ctx context.Context) error
}

// infrastructure/uow_impl.go — 基础设施层实现
package infrastructure

type mysqlUnitOfWork struct {
    tx         *sql.Tx
    orderRepo  *MySQLOrderRepo
    outboxRepo *MySQLOutboxRepo
}

func NewUnitOfWork(db *sql.DB) (domain.UnitOfWork, error) {
    tx, err := db.Begin()
    if err != nil {
        return nil, err
    }
    return &mysqlUnitOfWork{
        tx:         tx,
        orderRepo:  &MySQLOrderRepo{tx: tx},
        outboxRepo: &MySQLOutboxRepo{tx: tx},
    }, nil
}

func (u *mysqlUnitOfWork) OrderRepo() order.Repository  { return u.orderRepo }
func (u *mysqlUnitOfWork) OutboxRepo() OutboxRepository { return u.outboxRepo }
func (u *mysqlUnitOfWork) Commit(ctx context.Context) error   { return u.tx.Commit() }
func (u *mysqlUnitOfWork) Rollback(ctx context.Context) error { return u.tx.Rollback() }

// application/command/place_order.go — Use Case 使用 UoW
func (h *PlaceOrderHandler) Handle(ctx context.Context, cmd PlaceOrderCmd) error {
    uow, err := h.uowFactory(ctx)
    if err != nil {
        return err
    }
    defer uow.Rollback(ctx)

    order := domain.NewOrder(cmd.CustomerID)
    events, err := order.Place()
    if err != nil {
        return err
    }

    // 同一个事务中保存聚合和 Outbox
    if err := uow.OrderRepo().Save(ctx, order); err != nil {
        return err
    }
    for _, e := range events {
        if err := uow.OutboxRepo().Save(ctx, toOutboxEntry(e)); err != nil {
            return err
        }
    }
    
    return uow.Commit(ctx)
}

3.4.15 领域事件异步化：Outbox Pattern

问题：保存聚合到数据库后，还要发送事件到 Kafka。这两个操作无法在一个事务中完成（双写问题）。如果先写 DB 再发 Kafka，发送失败则事件丢失；如果先发 Kafka 再写 DB，写 DB 失败则产生幽灵事件。

解法：Outbox Pattern——将事件写入本地数据库的 Outbox 表（与业务数据同一事务），再由独立的 Relay 进程异步发送到 Kafka。

sequenceDiagram
    participant App as Application
    participant DB as MySQL
    participant Relay as Outbox Relay
    participant MQ as Kafka

    App->>DB: BEGIN TX
    App->>DB: INSERT orders (聚合数据)
    App->>DB: INSERT outbox (领域事件)
    App->>DB: COMMIT TX
    
    loop 定期轮询
        Relay->>DB: SELECT * FROM outbox WHERE status='pending'
        Relay->>MQ: Publish(event)
        MQ-->>Relay: ACK
        Relay->>DB: UPDATE outbox SET status='sent'
    end

Outbox 表设计

CREATE TABLE outbox (
    id          BIGINT AUTO_INCREMENT PRIMARY KEY,
    event_type  VARCHAR(128) NOT NULL,
    event_key   VARCHAR(128) NOT NULL,
    payload     JSON NOT NULL,
    status      ENUM('pending', 'sent', 'failed') DEFAULT 'pending',
    created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    sent_at     TIMESTAMP NULL,
    retry_count INT DEFAULT 0,
    INDEX idx_status_created (status, created_at)
);

Relay 实现

package infrastructure

import (
    "context"
    "log/slog"
    "time"
)

type OutboxRelay struct {
    outboxRepo OutboxRepository
    producer   MessageProducer
}

func (r *OutboxRelay) Run(ctx context.Context) {
    ticker := time.NewTicker(500 * time.Millisecond)
    defer ticker.Stop()

    for {
        select {
        case <-ctx.Done():
            return
        case <-ticker.C:
            entries, err := r.outboxRepo.FetchPending(ctx, 100)
            if err != nil {
                slog.Error("fetch outbox failed", "error", err)
                continue
            }
            for _, entry := range entries {
                if err := r.producer.Publish(ctx, entry.EventType, entry.EventKey, entry.Payload); err != nil {
                    slog.Error("publish event failed", "id", entry.ID, "error", err)
                    r.outboxRepo.MarkFailed(ctx, entry.ID)
                    continue
                }
                r.outboxRepo.MarkSent(ctx, entry.ID)
            }
        }
    }
}

关键保证：

• At-least-once delivery：Relay 崩溃后重启会重新发送 pending 的事件，消费者必须做幂等处理
• 顺序保证：按 created_at 顺序拉取，同一 event_key 的事件保持顺序
• 死信处理：retry_count > 5 的事件转入死信表，人工介入

3.5 CQRS（命令查询职责分离）

3.5.1 为什么要读写分离

CQRS 的逻辑非常直白：处理“改变数据“（Command）的逻辑和处理“读取数据“（Query）的逻辑应该完全分开。

在复杂系统中，写的逻辑和读的需求往往是矛盾的：

电商订单详情页的矛盾：

用户打开订单详情页，需要展示：

• 订单基本信息（订单号、状态、总价）
• 商品信息（名称、图片、规格）
• 价格明细（商品价、运费、优惠券）
• 物流信息（快递公司、运单号、物流轨迹）
• 售后信息（退款状态、退货进度）

如果用写模型（范式化）来查询：

-- ❌ 需要 JOIN 5-6 张表，性能差
SELECT o.*, oi.*, p.*, l.*, r.*
FROM orders o
JOIN order_items oi ON o.id = oi.order_id
JOIN products p ON oi.product_id = p.id
JOIN logistics l ON o.id = l.order_id
LEFT JOIN refunds r ON o.id = r.order_id
WHERE o.id = ?

如果用读模型（反范式化）：

// ✅ 一个宽表或一个 ES 文档，性能极佳
{
  "order_id": "123",
  "status": "delivered",
  "total_price": 299.00,
  "items": [
    {"product_name": "iPhone", "image": "...", "price": 299.00}
  ],
  "logistics": {"company": "SF Express", "tracking_no": "SF123"},
  "refund": null
}

3.5.2 DDD 与 CQRS 的关系

如果说阶段 2 的 DDD 解决的是“业务逻辑本身应该如何表达”，那么阶段 3 的 CQRS 解决的则是另一个更现实的问题：这些业务逻辑表达清楚之后，读和写是否还应该继续走同一条路径。

到了这一阶段，系统的主要矛盾往往已经不再是“模型贫血”或“规则散落”，而是“写模型为了保证一致性必须保持克制，但读场景又越来越追求宽表、搜索、排序和高并发”。也就是说，DDD 帮你把写侧建模建清楚了，但读侧未必适合继续共享同一套模型。

这正是 CQRS 和 DDD 的关系。DDD 让命令侧的模型更有表达力，CQRS 则进一步承认：命令侧和查询侧本来就不是一回事。写侧继续走领域模型，读侧则按展示需求单独设计，这样两者才能各自优化。

3.5.3 Go 项目中的典型目录映射

当 CQRS 落到 Go 项目中，最常见的变化不是整个项目推倒重来，而是在原有的应用层和适配层中，把读写路径显式拆开。以订单服务为例，比较常见的组织方式如下：

order-service/
├── cmd/
│   └── server/
│       └── main.go
│
├── domain/
│   └── order/
│       ├── aggregate.go
│       ├── value_object.go
│       ├── repository.go
│       └── event.go
│
├── application/
│   ├── command/                    # 写路径
│   │   ├── place_order.go
│   │   ├── cancel_order.go
│   │   └── mark_order_paid.go
│   └── query/                      # 读路径
│       ├── order_detail.go
│       └── order_list.go
│
├── interfaces/
│   ├── http/
│   │   └── order.go
│   └── rpc/
│       └── order.go
│
├── infrastructure/
│   ├── persistence/                # Write DB
│   │   └── order_repo.go
│   ├── readmodel/                  # Read DB / 宽表 / ES
│   │   ├── order_detail_repo.go
│   │   └── order_list_repo.go
│   ├── projection/                 # Event -> Read Model
│   │   └── order_projector.go
│   ├── mq/
│   └── mysql/

和前面的 DDD 相比，这里的核心变化不是 domain 再次升级，而是 application 和 infrastructure 开始明确区分“命令处理”和“查询处理”。从这个时候开始，大家讨论问题时，不再只是说“订单接口怎么写”，而是会进一步区分“这是一条命令链路，还是一条查询链路”。

3.5.4 以一个订单服务的调用链为例

如果把 CQRS 放到下单和查单场景中，最直观的变化就是系统里开始并存两条调用链。

写路径通常是这样的：

HTTP 请求
    -> interfaces/http.OrderHandler
    -> application/command.PlaceOrderHandler
    -> domain/order.Order 聚合根
    -> infrastructure/persistence.OrderRepo
    -> 发布领域事件

读路径则通常是这样的：

HTTP 请求
    -> interfaces/http.OrderHandler
    -> application/query.OrderDetailHandler
    -> infrastructure/readmodel.OrderDetailRepo
    -> Read DB / 宽表 / ES

这两条链路最重要的区别不只是“目录不同”，而是它们的目标根本不同：

• 写路径 关注的是业务规则、一致性和状态变更
• 读路径 关注的是展示效率、关联结果和查询性能

也正因为如此，CQRS 并不是“把原来的 Service 拆成两个文件”那么简单，而是承认读写两类需求的优化方向从一开始就不一样。

3.5.5 架构全景

flowchart LR
    subgraph 写路径 Command Side
        A[Client] -->|Command| B[Command Handler]
        B --> C[Domain Model / Aggregate]
        C --> D[(Write DB - MySQL)]
        C -->|Domain Event| E[Event Bus]
    end

    subgraph 读路径 Query Side
        E -->|同步/异步投影| F[Read Model Builder]
        F --> G[(Read DB - ES/Redis)]
        H[Client] -->|Query| I[Query Handler]
        I --> G
    end

关键理解：

• Command Side（写路径）：走领域模型，保证业务规则，数据存储在 MySQL
• Query Side（读路径）：绕过领域模型，直接从优化的读库（ES/Redis）返回 DTO
• 同步机制：通过领域事件 + 投影器（Projector）将写模型同步到读模型

3.5.6 Command 与 Query 的设计

Command — 表达意图，不返回业务数据

// application/command/place_order.go
package command

type PlaceOrderCommand struct {
    CustomerID string
    Items      []OrderItemDTO
}

type CommandResult struct {
    Success bool
    ID      string
    Error   error
}

type PlaceOrderHandler struct {
    orderRepo order.Repository
    eventBus  EventBus
}

func (h *PlaceOrderHandler) Handle(ctx context.Context, cmd PlaceOrderCommand) CommandResult {
    order := domain.NewOrder(cmd.CustomerID)
    for _, item := range cmd.Items {
        if err := order.AddItem(item.ProductID, item.Qty); err != nil {
            return CommandResult{Error: err}
        }
    }
    
    events, err := order.Place()
    if err != nil {
        return CommandResult{Error: err}
    }
    
    if err := h.orderRepo.Save(ctx, order); err != nil {
        return CommandResult{Error: err}
    }
    
    h.eventBus.Publish(ctx, events...)
    return CommandResult{Success: true, ID: string(order.ID())}
}

Command 的特点：

• 表达用户的意图（下单、取消、退款）
• 走领域模型，执行业务规则
• 只返回操作结果（成功/失败 + ID），不返回完整的业务数据

Query — 直接返回展示层需要的 DTO

// application/query/order_detail.go
package query

type OrderDetailQuery struct {
    OrderID string
}

type OrderDetailDTO struct {
    OrderID      string    `json:"order_id"`
    CustomerName string    `json:"customer_name"`
    Items        []ItemDTO `json:"items"`
    TotalPrice   string    `json:"total_price"`
    Status       string    `json:"status"`
    CreatedAt    string    `json:"created_at"`
}

type OrderDetailHandler struct {
    readDB ReadModelRepository
}

func (h *OrderDetailHandler) Handle(ctx context.Context, q OrderDetailQuery) (*OrderDetailDTO, error) {
    // 绕过领域模型，直接从读库获取
    return h.readDB.FindOrderDetail(ctx, q.OrderID)
}

Query 的特点：

• 绕过领域模型，不触发任何业务逻辑
• 直接从优化的读库（ES/Redis/宽表）返回 DTO
• 数据结构完全匹配前端需求，减少转换

3.5.7 为什么这一步值得做

当系统还比较简单时，把读和写放在同一套模型里看起来完全没有问题；但一旦查询开始变宽、流量开始倾斜、读写优化目标开始冲突，继续强行共用同一套模型，通常会出现几个典型症状：

• 写模型为了保证一致性保持范式化，查询却不得不频繁做多表关联
• 一个订单详情页需要拼接商品、价格、物流、售后等多个维度，查询越来越重
• 读流量远高于写流量，但系统却只能按同一套方式扩展
• 业务层为了兼顾读写两端，逐渐长成“既不像领域模型，也不像查询模型”的折中结构

这时，引入 CQRS 的最大收益，就是允许“写侧继续为正确性服务，读侧单独为性能服务”。你不再需要让一套模型同时满足两种天然冲突的目标。

3.5.8 核心价值

极致的性能优化。你可以针对写操作使用关系型数据库（保证强一致性），针对读操作使用 Elasticsearch 或 Redis（保证高并发）。读写模型可以独立扩展、独立优化。

电商系统的实际案例：

3.5.9 收益：写侧更稳，读侧更快

引入 CQRS 之后，最直接的收益通常有三个。

第一，写侧模型可以继续保持克制。命令处理依旧围绕聚合根和一致性边界展开，不必为了适配复杂查询去牺牲建模质量。

第二，读侧可以针对场景单独优化。订单详情页、订单列表页、搜索页、报表页，可以分别使用适合自己的读模型，而不必共享同一套查询结构。

第三，读写可以独立扩展。当读 QPS 远高于写 QPS 时，你可以优先扩读模型、缓存和搜索引擎，而不是被迫整体扩容。

当然，代价也很现实：读写分离之后，系统复杂度会上升，读模型同步、最终一致性、幂等处理和投影器维护都需要额外关注。因此，CQRS 不是“默认就该上”的方案，而是在读写矛盾已经明显出现时，才值得付出的复杂性成本。

3.5.10 Event Sourcing：事件溯源

Event Sourcing 经常和 CQRS 一起被提及，但它们是独立的概念，可以单独使用，也可以组合使用。

核心思想

传统方式存储的是当前状态（state），Event Sourcing 存储的是导致状态变化的事件序列（events）。当前状态通过重放事件计算得出。

传统方式：
  orders 表: {id: 1, status: "paid", total: 200, updated_at: "2026-04-07"}

Event Sourcing：
  events 表:
    {seq: 1, type: "OrderCreated",  data: {id: 1, customer: "alice"}}
    {seq: 2, type: "ItemAdded",     data: {product: "shoe", price: 100, qty: 2}}
    {seq: 3, type: "OrderPlaced",   data: {total: 200}}
    {seq: 4, type: "PaymentReceived", data: {amount: 200, method: "credit_card"}}

与 CQRS 的关系

graph LR
    A[CQRS] --- B[可以独立使用]
    C[Event Sourcing] --- B
    A --- D[组合使用效果最佳]
    C --- D
    D --> E[写侧用事件存储<br/>读侧用物化视图]

• 只用 CQRS 不用 ES：写侧用普通数据库，读侧用独立的读模型。最常见的方式。
• 只用 ES 不用 CQRS：事件存储 + 重放计算状态，读写用同一个模型。适合审计场景。
• CQRS + ES：写侧用事件存储，读侧通过投影事件构建物化视图。适合金融、交易系统。

适用与不适用场景

本书立场：电商系统大部分场景只用 CQRS 不用 Event Sourcing。Event Sourcing 适合金融、合规等场景，但对于电商的商品、订单等模块，增加的复杂度超过了收益。

3.5.11 最终一致性处理策略

引入 CQRS 后，写模型和读模型之间存在延迟（通常毫秒到秒级）。这需要在架构层面和用户体验层面同时处理。

架构层面

策略一：幂等消费

投影器可能收到重复事件（at-least-once delivery），必须做幂等处理：

func (p *OrderProjector) Project(ctx context.Context, event DomainEvent) error {
    // 幂等性检查：事件是否已处理
    exists, err := p.readDB.EventProcessed(ctx, event.ID())
    if err != nil {
        return err
    }
    if exists {
        return nil // 已处理过，跳过
    }

    // 处理事件
    switch e := event.(type) {
    case OrderPlacedEvent:
        dto := OrderDetailDTO{
            OrderID:    string(e.OrderID),
            Status:     "placed",
            TotalPrice: e.Total.String(),
            CreatedAt:  e.At.Format(time.RFC3339),
        }
        if err := p.readDB.Upsert(ctx, dto); err != nil {
            return err
        }
    }
    
    // 标记事件已处理
    return p.readDB.MarkEventProcessed(ctx, event.ID())
}

策略二：补偿事务（Saga）

当跨服务操作中某一步失败，通过发布补偿事件回滚前面的步骤：

正向流程：CreateOrder → ReserveStock → ChargePayment
补偿流程：                ReleaseStock ← RefundPayment ← PaymentFailed

我们会在第4章详细讲解 Saga 模式。

用户体验层面

Optimistic UI（乐观更新）：前端在发送 Command 后立即更新 UI，不等待读模型同步。

用户点击"下单" 
  → 前端立即显示"订单已创建"（乐观更新）
  → 后端 Command 异步处理
  → 读模型延迟 200ms 后更新
  → 用户下次刷新时看到真实状态

Read-your-writes：Command 成功后返回版本号，Query 时带上版本号，确保读到的是自己写入之后的数据。

// Command 返回版本号
type CommandResult struct {
    Success bool
    ID      string
    Version int64  // 版本号
}

// Query 时带上版本号
type OrderDetailQuery struct {
    OrderID         string
    MinVersion      int64  // 期望读到的最小版本
}

// Query Handler 检查版本
func (h *OrderDetailHandler) Handle(ctx context.Context, q OrderDetailQuery) (*OrderDetailDTO, error) {
    dto, err := h.readDB.FindOrderDetail(ctx, q.OrderID)
    if err != nil {
        return nil, err
    }
    // 如果读模型版本低于期望版本，返回错误或等待
    if dto.Version < q.MinVersion {
        return nil, ErrReadModelNotReady
    }
    return dto, nil
}

3.5.12 投影器（Projector）实现模式

投影器是 CQRS 架构中将领域事件转化为读模型的组件。

flowchart LR
    A[Event Store / MQ] --> B[Projector]
    B --> C[(Read DB)]
    
    B --> D{事件类型路由}
    D -->|OrderPlaced| E[创建订单读模型]
    D -->|ItemAdded| F[更新商品明细]
    D -->|OrderCancelled| G[标记订单取消]

完整实现

// adapter/projection/projector.go
package projection

type Projector interface {
    Handles() []string // 返回该 Projector 关心的事件类型列表
    Project(ctx context.Context, event DomainEvent) error
}

type OrderReadModelProjector struct {
    readDB ReadModelRepository
}

func (p *OrderReadModelProjector) Handles() []string {
    return []string{"OrderPlaced", "OrderCancelled", "ItemAdded", "PaymentCompleted"}
}

func (p *OrderReadModelProjector) Project(ctx context.Context, event DomainEvent) error {
    switch e := event.(type) {
    case OrderPlacedEvent:
        return p.readDB.Upsert(ctx, OrderReadModel{
            OrderID:   string(e.OrderID),
            Status:    "placed",
            Total:     e.Total.Amount,
            Currency:  e.Total.Currency,
            CreatedAt: e.At,
        })
    case OrderCancelledEvent:
        return p.readDB.UpdateStatus(ctx, string(e.OrderID), "cancelled")
    case PaymentCompletedEvent:
        return p.readDB.UpdateStatus(ctx, string(e.OrderID), "paid")
    default:
        return nil
    }
}

投影器的运行模式

电商系统推荐：异步投影，理由：

• 读写可以独立扩展（写用MySQL，读用ES）
• 故障隔离（读模型崩溃不影响写操作）
• 性能最优（异步处理不阻塞写操作）

3.6 本章小结

本章的核心不是再介绍几个新概念，而是把系统内部结构设计这件事重新排成一条清晰主线：

• 先用三层架构建立最基本的职责秩序
• 再用 Clean Architecture 收紧依赖方向
• 再用 DDD 战术设计把复杂规则收回到模型内部
• 最后在必要时用 CQRS 拆分读写路径

换句话说，系统内部结构设计不是在问“该选哪一种架构”，而是在问：面对职责、依赖、建模和数据流这四类问题时，架构师应该按什么顺序出招。

下一章将继续沿着这条主线往外走：当单个系统内部已经有了秩序之后，多个系统之间又该如何集成，怎样在分布式环境中处理协作与一致性问题。

下一章：第4章 系统集成与一致性设计 将从跨系统调用、事件驱动、最终一致性、Outbox 与 Saga 等角度，讨论系统之间如何协作。

导航：返回目录 | 上一章：第2章 | 书籍主页 | 下一章：第4章

导航：书籍主页 | 完整目录 | 上一章：第3章 | 下一章：第5章

第4章 系统集成与一致性设计

事件驱动、集成模式与最终一致性，解决系统之间的协作问题

本章定位：前两章分别解决了业务边界与系统内部结构，本章开始讨论第三个层面的问题：当多个上下文或多个服务开始协作时，系统应该如何集成，以及不再共享同一本地事务后如何保持一致性。这里的方法论重点不再是分层与建模，而是事件驱动、幂等、补偿、对账、Outbox 与 Saga。

阅读提示：若你更熟悉「一个数据库里用本地事务搞定一切」的单体思维，建议带着三个问题读完全章——第一，分区发生时你更不愿意牺牲哪一项（一致性、可用性、延迟）；第二，失败是可逆还是不可逆（决定补偿语义）；第三，重复请求与重复消息是否已被建模为一等公民（决定幂等与 Outbox 是否值得投资）。

章节衔接：第 1 章给出组合拳全景，第 2 章划边界，第 3 章解决边界之内的结构设计；本章则把视角抬升到边界之间。后续第 7 章到第 16 章在讲商品、库存、营销、计价、购物车、订单与支付时，都会反复回到本章的词汇表与模式库。

写作约定：文中 Go 示例为教学裁剪版，聚焦结构与语义；生产落地请补齐超时、退避、注入、鉴权、观测字段与错误码规范，并把「成功 / 业务失败 / 可重试失败」三类语义贯穿全链路。阅读时建议对照你们公司的网关规范、数据库迁移规范与消息平台手册做二次裁剪，并把示例中的表名与字段名映射到真实审计字段、合规要求与数据留存周期。

6.1 分布式事务挑战

跨服务、跨库、跨供应商的电商链路，本质上是在没有全局锁的前提下完成协作。讨论「分布式事务」之前，先要统一语言：我们追求的往往不是银行核心那种「强一致实时可见」，而是用户可理解的一致性与财务可审计的一致性的组合。

把一致性目标写成 SLO：方法论章节最容易停留在概念层，落地时建议把「一致性」翻译成可监控指标。例如：「创单成功后 99.9% 用户在 1 秒内读到订单详情」「支付成功后 5 分钟内订单状态同步完成」「对账差异在 T+1 日内闭环率」。没有指标，团队就会在事故后争论「这算不算一致」。SLO 也会反向约束集成模式：如果你承诺秒级读己之所写，就不能把关键读路径绑在慢消费者之后。

可观测性是最小一致性保障：跨系统集成里，最大风险不是「短暂不一致」，而是「不知道不一致发生在哪」。因此链路追踪（Trace）、关联 ID（order_id / payment_id / idempotency_key）、以及跨系统日志检索规范，应被视为一致性基础设施的一部分，而不是「运维锦上添花」。当你能在 5 分钟内从用户投诉定位到具体参与方与具体请求，你已经把大量 P1 事故降级为 P3。

6.1.1 CAP 理论在电商中的应用

CAP 指出：在**网络分区（P）**客观存在时，系统只能在 C（线性化一致性） 与 A（可用性：非故障节点可继续响应） 之间做权衡。电商里更务实的表述是：

• P 不可逃避：机架故障、运营商割接、云厂商区域抖动都会制造分区；你的系统要么承认它，要么假装它不存在（后者通常以事故收场）。
• C 与 A 不是 0/1：多数业务选择的是 延迟可接受的一致性（例如订单创建立即可见、搜索索引秒级滞后）与 降级后的可用性（例如暂停个性化推荐但不阻断下单）。

下面的三角图用三个顶点表达「三者不可同时取满」的直觉（示意，非形式化证明）。

flowchart LR
  subgraph CAP[CAP 在分区下的取舍三角]
    C((C\n强一致 / 线性化))
    A((A\n高可用 / 持续服务))
    P((P\n分区容错))
  end
  C ---|分区下难与 A 兼得| A
  A ---|要一致则需限制写入| P
  P ---|承认分区| C

  style C fill:#ffebee
  style A fill:#e8f5e9
  style P fill:#e3f2fd

电商映射示例：

在 CAP 之外，工程讨论里还常用 PACELC：在**正常（Latency）与分区（Partition）**两种状态下，分别在 C 与 A、**C 与 L（延迟）**之间权衡。电商系统的真实矛盾往往不在「选 CP 还是 AP」这种标签，而在「把哪一类不一致暴露给用户」：用户能容忍搜索列表晚 1 秒，但很难容忍「支付成功却订单仍待付款」这种语义断裂。于是产品与技术要共同定义 RPO/RTO 的业务翻译——例如「支付回调最长可延迟多久仍可被用户理解」「库存预占展示与真实可售不一致的上限是多少」。

另一个常见误区是把 「强一致」当成银弹。跨服务的两阶段提交（2PC）与其变体在微服务规模下会放大故障域：协调者不可用、参与者长时间持锁、尾延迟抖动都会被交易洪峰放大。更稳妥的工程路径通常是：在单个聚合 / 单个服务内用数据库事务守住硬约束，跨边界用 Saga / TCC / 可靠消息组合，再用 对账兜住不可避免的外部异步。

6.1.2 一致性分类

从工程师落地角度，建议把「一致性」从口号拆成可见性、容错模型与经济后果三层，再映射到技术策略。

flowchart TB
  subgraph L1[用户可见一致性]
    U1[读己之所写 Read-your-writes]
    U2[单调读 Monotonic reads]
    U3[因果一致 Causal]
  end
  subgraph L2[跨系统事实来源]
    S1[单主库权威 Single source of truth]
    S2[多副本异步复制]
    S3[事件驱动物化视图]
  end
  subgraph L3[财务 / 履约后果]
    F1[强一致账务]
    F2[最终一致业务态]
    F3[对账闭环]
  end
  L1 --> L2
  L2 --> L3

谱系速查：

• 强一致（线性化 / 串行化）：单个分片内靠数据库事务；跨分片靠分布式协调（代价高、故障域大）。
• 会话一致 / 单调读：常见于「用户刚下的单，列表里立刻能看到」——可用主从路由策略与 sticky 读实现。
• 最终一致：允许短暂漂移，但必须有版本、水位、对账与补偿兜住边界。
• 因果一致：适合「评论回复依赖发帖可见」等场景；电商里多用于协作类附属功能，主交易链路仍以订单状态机为准。

为了把「一致性」从论文语言落到排障语言，建议团队在架构评审里强制区分三类问题，并把它们映射到不同手段：

1. 读可见性问题：用户「刚操作完却看不到」——多数是读写路由、缓存、投影延迟；优先查主从延迟、Outbox 堆积、消费者 lag。
2. 跨系统事实冲突：订单说已支付、支付说未成功——多数是回调丢失、幂等键不一致、状态机非法迁移；优先查渠道流水与平台流水对齐。
3. 跨时间窗口的统计不一致：GMV 看板与财务口径对不上——多数是异步汇总、时区、退款冲正口径；优先查离线任务水位与口径文档。

下表给出「用户感知」与「系统手段」的对照，用于和需求方对齐预期（避免把技术极限包装成业务承诺）。

6.1.3 典型场景分析

1. 创单链路（订单、库存、营销、计价）：跨多个限界上下文，同步点越多尾延迟越大；典型解法是「结算页强校验 + 创单 Saga + 异步投影」。
2. 搜索与商品主数据：索引滞后是常态，关键是可观测的延迟与降级展示（第 12 章）。
3. 支付回调与渠道对账：渠道侧状态与平台侧状态异步收敛；必须幂等、必须可对账（第 15 章与 6.5 呼应）。
4. 供应商库存：供应商为权威时，平台侧是快照 + 同步策略；分区时以可解释的拒单 / 延迟确认交换「永不超卖」承诺（第 8 章）。
5. 退款与售后：涉及支付渠道、营销回退、库存回冲、供应商拦截等多参与方，不可逆节点（已打款、已出票）会把「补偿」切换为「工单 / 人工」。这类链路更需要 Saga 日志 + 对账批次号 + 幂等退款单号 三件套，避免重复退款与部分成功。
6. 秒杀与抢购：热点 SKU 的约束是「库存单调递减」与「请求风暴」叠加。工程上通常是 Redis 原子预减 + 异步落库对账，而不是跨服务同步强一致；否则会把尾延迟与失败面扩散到整个站点入口。
7. 清结算与分账：平台、商家、渠道、营销补贴多方账本需要在 T+N 周期收敛。这里的「一致性」更像会计恒等式：借贷平衡、可追溯、可审计，而不是用户请求路径上的毫秒级一致。
8. 跨境与多币种：汇率快照、税费、支付路由使得「金额一致」必须显式引入 snapshot_id / rate_version，否则对账会把产品问题误判为技术故障。

这些场景的共同点，是都要求你在架构文档里写清楚一句话：一致性的责任边界在哪里结束。例如库存预占由库存服务负责语义，订单只保存 reserve_id 凭证；支付金额以支付核心的记账为准，订单侧只保存 pay_amount 快照与引用号。边界写清楚，集成才不会退化成「谁都能改一笔」。

6.2 Saga 编排模式

Saga 把长事务拆为本地事务序列，用补偿事务撤销已提交步骤的可逆效果。它不要求全局锁表，也不要求所有参与方实现预留接口（对比 TCC 的 Try/Confirm/Cancel），因此在跨团队集成中最常见。

很多团队会把「分布式事务」理解成「找一个中间件把多个数据库一次性提交」。在电商微服务里，这种理解往往会把问题推向两个极端：要么 过度依赖全局协调（可用性与尾延迟受损），要么 完全回避一致性话题（只能靠人肉修数）。Saga 的价值在于承认现实：跨服务没有免费的全局原子性，但可以把不确定性收敛到 可测试的本地事务 + 可审计的补偿 + 可对账的凭证。当你能清楚说出「哪一步失败会留下什么外部痕迹」，你就已经比大多数项目更接近可控。

落地时还要区分 业务失败 与 系统失败：库存不足是业务失败，通常不应触发重试；渠道超时是系统失败，需要退避重试与查询对齐。把两者混在一个 if err != nil 里，Saga 会表现为「无意义重试放大雪崩」或「该补偿却不补偿」。建议在错误模型里显式引入 BusinessError 与 TransientError（或等价错误码），编排器据此分支。

6.2.1 Saga 基础概念

• 子事务（Local Transaction）：在一个服务 / 一个库边界内可原子提交。
• 补偿（Compensation）：语义上撤销前一步业务效果；必须幂等，且要能处理「原操作其实失败」的空补偿。
• Saga 日志：记录每一步状态，支撑断点续跑、人工介入与审计。

与 TCC（Try-Confirm-Cancel） 相比，Saga 对参与方的接口要求更低，但业务侧要承担更多「补偿语义」的设计成本。可以用下表做模式选型（不是非此即彼，很多系统会在支付子域用更严格的协议，在营销子域用 Saga）。

6.2.2 编排 vs 协同

flowchart LR
  subgraph Orch[编排 Orchestration]
    O[OrderOrchestrator\n集中状态机]
    O --> I[InventorySvc]
    O --> M[MarketingSvc]
    O --> P[PricingSvc]
  end

  subgraph Cho[协同 Choreography]
    E1[OrderCreated 事件]
    E2[InventoryReserved 事件]
    E3[MarketingLocked 事件]
    OrdSvc[订单服务]
    InvSvc[库存服务]
    MktSvc[营销服务]
    OrdSvc --> E1 --> InvSvc
    InvSvc --> E2 --> MktSvc
    MktSvc --> E3
  end

选型经验：

• 编排：调试路径清晰，适合强流程（创单、退款、结算）；缺点是编排器可能成为热点与变更集中点。
• 协同：解耦参与者，适合弱流程扩展；缺点是全局可观测性与顺序约束更难，需要严格的事件契约与版本治理。

电商创单、退款等有严格顺序与对账要求的链路，业界更常见的是编排为主、事件为辅。

混合形态：编排器完成「强一致点的凭证收集」（试算快照、预占号、营销锁），聚合根提交后再通过 Outbox 广播 OrderCreated 给搜索、推荐、风控等读模型或旁路系统。这样既保留集中调试与审计的主线，又避免把读侧耦合进同步链路。

6.2.3 补偿机制设计

补偿不是「数据库回滚」的同义词，而是业务语义撤销。设计要点：

1. 可逆性分级：库存释放、券解锁可逆；已发货、已出票常不可逆，需要转入人工 / 工单 / 财务流程。
2. 补偿的幂等：网络重试会导致补偿重复执行；应用层用业务幂等键或状态检查保证安全。
3. 失败面分类：业务拒绝（库存不足）与基础设施故障（超时）要分流，后者才触发重试与退避。
4. 超时与悬挂：子调用超时后，编排器要通过查询接口把「未知」落成「成功 / 失败」之一，再决定前进或回滚。

Saga 持久化与恢复：请求线程崩溃、实例重启、发布滚动都会导致「执行到一半」的外部视图。生产系统应至少落一张 saga_instance 表（或等价事件日志），字段建议包含：saga_id、biz_key（幂等键）、current_step、status（running/compensating/succeeded/failed）、payload_json、started_at、updated_at、version（乐观锁）。恢复线程按 status=running 扫描，结合每步的 query 结果把流程推向下一个合法状态。没有这张表，你只能依赖日志拼凑现场，事故复盘成本会指数级上升。

并发与重入：同一个 biz_key 的重复请求不应启动第二个 Saga 实例。常见做法是「数据库唯一约束 + 返回进行中的 saga_id」或「Redis 分布式锁（短 TTL + 续期谨慎）」。锁方案要警惕：锁超时后另一个实例进入，会造成双轨执行；因此最终仍应以 幂等键与 Saga 状态机 作为真相来源。

sequenceDiagram
  participant O as Orchestrator
  participant S as StepService
  O->>S: forward()
  alt 成功
    S-->>O: OK
    O->>O: persist saga step done
  else 明确失败
    S-->>O: FAIL business
    O->>S: compensate previous (idempotent)
    S-->>O: OK
  else 超时 / 未知
    S-->>O: TIMEOUT
    O->>S: query()
    S-->>O: committed? yes/no
    O->>O: reconcile then forward or compensate
  end

6.2.4 订单创建的 Saga 实例

下面给出一个教学裁剪版但结构完整的 Go 示例：三步正向（计价快照绑定、库存预占、营销锁定）与两步补偿（释放库存、解锁营销）。示例省略了真实 RPC、链路追踪与部分错误包装，但保留编排骨架、幂等键透传、补偿逆序等关键结构。

Saga 流程图：

flowchart TD
  Start([开始 CreateOrderSaga]) --> T1[Step1: AttachPriceSnapshot]
  T1 -->|失败| X1([结束: 失败无补偿])
  T1 -->|成功| T2[Step2: ReserveInventory]
  T2 -->|失败| C1[Comp1: 无需库存补偿]
  T2 -->|成功| T3[Step3: LockMarketing]
  T3 -->|失败| C2[Comp2: ReleaseInventory]
  T3 -->|成功| Done([持久化订单\n提交本地事务])
  C2 --> X2([结束: 已回滚库存])

  style Done fill:#e8f5e9
  style X1 fill:#ffebee
  style X2 fill:#fff3e0

Go 编排骨架（单文件可 go run，将下游调用替换为真实 gRPC / HTTP SDK 即可落地）：

Walk-through（对照流程图读代码）：

1. AttachSnapshot 失败时，系统尚未占用库存与营销资源，因此直接返回错误即可，对应流程图左侧「失败无补偿」分支。
2. Reserve 成功后，reserve_id 成为库存侧的外部凭证；后续任何释放都必须携带它，并在库存服务侧以幂等方式处理。
3. LockPromo 失败进入补偿：只释放库存，不解锁营销（因为锁未成功）。若未来某版本 LockPromo 变成「部分成功」（例如锁定成功但写审计失败），必须把补偿扩展为「先查锁是否存在再解锁」，否则会出现补偿空转或补偿遗漏。
4. Run 成功后，订单服务应在单一本地事务中写入订单主表、明细、价格快照引用、外部凭证集合，并写入 Outbox 触发下游投影。不要把「订单持久化」拆到多个没有事务边界的 RPC 里，否则你会重新发明分布式事务。

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"net/http"
	"time"
)

// ---- 端口：生产环境应使用 gRPC / 生成代码 ----

type PricingClient interface {
	AttachSnapshot(ctx context.Context, orderID, snapshotID string) error
}

type InventoryClient interface {
	Reserve(ctx context.Context, idempotencyKey, orderID, sku string, qty int) (reserveID string, err error)
	Release(ctx context.Context, idempotencyKey, reserveID string) error
}

type MarketingClient interface {
	LockPromo(ctx context.Context, idempotencyKey, orderID, promoRef string) (lockID string, err error)
	UnlockPromo(ctx context.Context, idempotencyKey, lockID string) error
}

// ---- 编排器 ----

type CreateOrderCommand struct {
	OrderID        string
	IdempotencyKey string
	PriceSnapshot  string
	SKU            string
	Qty            int
	PromoRef       string
}

type CreateOrderSaga struct {
	Pricing   PricingClient
	Inventory InventoryClient
	Marketing MarketingClient
}

func (s *CreateOrderSaga) Run(ctx context.Context, cmd CreateOrderCommand) error {
	if cmd.OrderID == "" || cmd.IdempotencyKey == "" {
		return errors.New("invalid command")
	}

	// Step 1: 绑定计价快照（失败则无资源占用）
	if err := s.Pricing.AttachSnapshot(ctx, cmd.OrderID, cmd.PriceSnapshot); err != nil {
		return fmt.Errorf("attach snapshot: %w", err)
	}

	// Step 2: 库存预占
	reserveID, err := s.Inventory.Reserve(ctx, cmd.IdempotencyKey+":inv", cmd.OrderID, cmd.SKU, cmd.Qty)
	if err != nil {
		return fmt.Errorf("reserve inventory: %w", err)
	}

	// Step 3: 营销锁定
	lockID, err := s.Marketing.LockPromo(ctx, cmd.IdempotencyKey+":mkt", cmd.OrderID, cmd.PromoRef)
	if err != nil {
		// 补偿：释放库存（逆序）
		if relErr := s.Inventory.Release(ctx, cmd.IdempotencyKey+":inv:rel", reserveID); relErr != nil {
			return fmt.Errorf("lock promo failed: %v; release inventory failed: %w", err, relErr)
		}
		return fmt.Errorf("lock promo: %w", err)
	}

	log.Printf("saga ok order=%s reserve=%s lock=%s", cmd.OrderID, reserveID, lockID)
	// Step 4（示意）：在同一服务的数据库事务里插入订单主表与明细
	return nil
}

// ---- 内存桩：演示幂等 + 成功路径 ----

type memPricing struct{}

func (memPricing) AttachSnapshot(ctx context.Context, orderID, snapshotID string) error {
	return nil
}

type memInventory struct {
	released bool
}

func (m *memInventory) Reserve(ctx context.Context, idempotencyKey, orderID, sku string, qty int) (string, error) {
	return "resv_123", nil
}

func (m *memInventory) Release(ctx context.Context, idempotencyKey, reserveID string) error {
	m.released = true
	return nil
}

type memMarketing struct{}

func (memMarketing) LockPromo(ctx context.Context, idempotencyKey, orderID, promoRef string) (string, error) {
	return "lock_456", nil
}

func (memMarketing) UnlockPromo(ctx context.Context, idempotencyKey, lockID string) error {
	return nil
}

// 将 HTTP 客户端映射为 InventoryClient 的示例（真实项目用专用 SDK）
type httpInventory struct {
	client *http.Client
	url    string
}

func (httpInventory) Reserve(ctx context.Context, idempotencyKey, orderID, sku string, qty int) (string, error) {
	// 伪代码：构造 POST /v1/reservations，Header 携带 Idempotency-Key
	return "", errors.New("not implemented in demo")
}

func (httpInventory) Release(ctx context.Context, idempotencyKey, reserveID string) error {
	return errors.New("not implemented in demo")
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
	defer cancel()

	saga := &CreateOrderSaga{
		Pricing:   memPricing{},
		Inventory: &memInventory{},
		Marketing: memMarketing{},
	}
	err := saga.Run(ctx, CreateOrderCommand{
		OrderID:        "ord_1",
		IdempotencyKey: "idem_user_click_001",
		PriceSnapshot:  "pshot_9f3c",
		SKU:            "sku_a",
		Qty:            1,
		PromoRef:       "promo_x",
	})
	if err != nil {
		log.Fatal(err)
	}
}

落地清单（从示例走向生产）：

• 为每一步引入持久化 Saga 表（saga_id、step、status、payload、error_code）。
• 所有 outbound 调用携带关联 ID（order_id、trace_id、idempotency_key）。
• 对「超时未知」统一走 query + reconcile 状态机，而不是立刻补偿。

Saga 表结构示例（MySQL，示意）：落地时按你们公司的审计规范补全操作者与 trace 字段。

CREATE TABLE saga_instance (
  saga_id       BIGINT PRIMARY KEY AUTO_INCREMENT,
  biz_key       VARCHAR(128) NOT NULL,
  name          VARCHAR(64)  NOT NULL,
  status        VARCHAR(32)  NOT NULL,
  current_step  INT            NOT NULL,
  payload       JSON           NOT NULL,
  version       INT            NOT NULL DEFAULT 0,
  created_at    DATETIME       NOT NULL,
  updated_at    DATETIME       NOT NULL,
  UNIQUE KEY uk_saga_biz (biz_key, name)
);

CREATE TABLE saga_step (
  id         BIGINT PRIMARY KEY AUTO_INCREMENT,
  saga_id    BIGINT NOT NULL,
  step_no    INT    NOT NULL,
  step_name  VARCHAR(64) NOT NULL,
  status     VARCHAR(32) NOT NULL,
  req        JSON,
  resp       JSON,
  err        TEXT,
  created_at DATETIME NOT NULL,
  KEY idx_saga (saga_id, step_no)
);

6.3 事件驱动架构

事件驱动架构（EDA）把系统间的耦合从「知道对方的表结构」变为「订阅对方愿意公布的事实」。它与 DDD 的**领域事件（Domain Event）**天然契合：事件名应是业务过去式（OrderPlaced），而不是命令式（PlaceOrder）。

EDA 并不自动带来解耦：如果事件载荷里塞满下游私有字段，或消费者之间隐式依赖顺序却缺乏分区策略，你只会得到「异步耦合的大泥球」。因此本章强调三件事：契约、顺序边界、可观测的投递语义。与第 16 章的事件发布实践结合时，请把「事件平台能力」与「领域建模能力」分开评估：Kafka 再强也替代不了你对聚合边界的判断。

6.3.1 领域事件

领域事件用于表达聚合内已发生且不可变的事实。好的事件：

• 自描述：携带必要标识与版本（schema_version）。
• 可演进：兼容字段新增，慎改语义。
• 与命令分离：命令可丢弃重试；事件一旦发布，消费者会据此做副作用。

命名与版本：事件名建议稳定且可检索（order.placed.v1），避免把促销规则编码进 topic 名称。载荷里携带 occurred_at、producer、schema_version，消费者才能做 向后兼容 解析。另一个实践是把「业务关键字段」与「展示字段」分层：关键字段用于幂等与投影，展示字段允许缺失并由读模型降级。

聚合边界：领域事件应从聚合根的不变量中自然产生，而不是为了通知某个下游临时「造事件」。后者会导致事件泛滥、顺序难以推理、回放成本失控。若你发现自己需要 SomethingMaybeChanged 这类含糊事件，通常意味着限界上下文边界需要重塑。

6.3.2 事件的发布与订阅

flowchart LR
  subgraph OrderBC[订单限界上下文]
    AR[Order Aggregate]
    AR -->|产生| DE[Domain Events]
    DE --> OB[Outbox Table]
  end
  subgraph Infra[基础设施]
    REL[Outbox Relay / Poller]
    BUS[(Message Bus)]
  end
  subgraph Consumers[订阅方]
    InvProj[库存读模型投影]
    Srch[搜索索引增量]
    Risk[风控评分任务]
  end
  OB --> REL --> BUS
  BUS --> InvProj
  BUS --> Srch
  BUS --> Risk

发布订阅的工程细节：

• Topic 分区键：与顺序性强相关的字段（同一 order_id）应映射到同一分区，避免乱序消费；但分区键过粗会造成热点分区，需要业务侧权衡。
• 消费者组：一组消费者共享进度，实现水平扩展；重平衡（rebalance）会带来短暂停顿，要评估是否影响实时性 SLA。
• 至少一次投递：因此消费者必须 幂等；常见实现是 UNIQUE(consumer, event_id) 或业务唯一键。
• 顺序与并行：能并行就并行（不同聚合互不相关），不能并行就必须把「会改变含义的顺序」收敛到单分区或单线程处理器。
• 背压：投影任务落后时，应有 lag 告警与降级读策略，避免把读路径拖死。

与第 16 章「事件发布」对齐时，把「谁允许发什么事件」纳入治理：事件不是自由文本广播，而是受版本管理的契约。建议在仓库中维护 events/ 目录（或 Buf Schema Registry），把破坏性变更当作发布流程的一部分。

6.3.3 事件溯源（Event Sourcing）

事件溯源（ES）把状态还原为事件流的折叠：state = fold(events)。它带来强大审计与回放能力，但也引入：

• 模型复杂度：投影、快照、版本迁移成本高。
• 查询压力：多数业务仍需要物化读模型（CQRS）。

电商建议：账务、支付指令、库存流水等强审计子域可评估 ES；一般商品展示、搜索索引用物化视图 + Outbox 性价比更高（与第 1 章 CQRS 小节呼应）。

何时值得上 ES：当你明确需要「按时间回放任意业务态」且愿意投入 投影重建、快照策略、事件迁移工具链；否则先用 审计日志表 + 不可变对象存储归档 + 定期校验 往往更划算。ES 不是银弹，它是把复杂度从数据库迁移到了事件存储与投影运维。

快照（Snapshot）：长生命周期聚合（例如会员账户、长期预售订单）如果每次都从头折叠事件，读路径会不可接受。快照本质是「在某版本截断事件流」，需要定义 快照写入频率 与 快照与事件的版本对齐规则。

6.3.4 实践要点与 Outbox 完整实现

Outbox 模式解决的核心矛盾是：数据库事务提交与消息发布难以跨资源原子化。做法是：在同一本地事务中写入业务表与 outbox 表；由独立进程异步投递到消息总线，实现 at-least-once 发布且不丢单（消费者仍需幂等）。

Outbox 时序图：

sequenceDiagram
  participant API as Order API
  participant DB as MySQL
  participant R as Outbox Relay
  participant K as Kafka

  API->>DB: BEGIN
  API->>DB: INSERT orders ...
  API->>DB: INSERT outbox(event_type,payload,status)
  API->>DB: COMMIT
  loop poll
    R->>DB: SELECT ... FOR UPDATE SKIP LOCKED
    R->>K: produce message(idempotent key)
    K-->>R: ack
    R->>DB: UPDATE outbox SET status=published
  end

Go 实现骨架（使用 database/sql；生产环境可替换为 sqlx / ORM，但保持「同事务写两张表」不变）：

package outboxdemo

import (
	"context"
	"database/sql"
	"encoding/json"
	"time"
)

type OutboxEvent struct {
	ID        int64
	Aggregate string
	EventType string
	Payload   json.RawMessage
	Status    string // pending / published / dead
	CreatedAt time.Time
}

type OrderRepository struct {
	DB *sql.DB
}

// CreateOrderWithOutbox 演示：订单写入与 outbox 同事务
func (r *OrderRepository) CreateOrderWithOutbox(ctx context.Context, orderID string, evtType string, payload any) error {
	bytes, err := json.Marshal(payload)
	if err != nil {
		return err
	}

	tx, err := r.DB.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelReadCommitted})
	if err != nil {
		return err
	}
	defer func() { _ = tx.Rollback() }()

	if _, err := tx.ExecContext(ctx, `INSERT INTO orders(id, status) VALUES(?, 'CREATED')`, orderID); err != nil {
		return err
	}
	if _, err := tx.ExecContext(ctx,
		`INSERT INTO outbox(aggregate_id, event_type, payload, status, created_at)
		 VALUES(?,?,?,?,?)`,
		orderID, evtType, bytes, "pending", time.Now().UTC(),
	); err != nil {
		return err
	}
	return tx.Commit()
}

// Relay 轮询投递：演示 SKIP LOCKED 多实例安全
type Relay struct {
	DB *sql.DB
}

func (relay *Relay) PollOnce(ctx context.Context, publish func(ctx context.Context, ev OutboxEvent) error) (int, error) {
	tx, err := relay.DB.BeginTx(ctx, nil)
	if err != nil {
		return 0, err
	}
	defer func() { _ = tx.Rollback() }()

	rows, err := tx.QueryContext(ctx, `
		SELECT id, aggregate_id, event_type, payload, status, created_at
		FROM outbox
		WHERE status='pending'
		ORDER BY id ASC
		LIMIT 50
		FOR UPDATE SKIP LOCKED`)
	if err != nil {
		return 0, err
	}
	defer rows.Close()

	var batch []OutboxEvent
	for rows.Next() {
		var ev OutboxEvent
		var agg string
		if err := rows.Scan(&ev.ID, &agg, &ev.EventType, &ev.Payload, &ev.Status, &ev.CreatedAt); err != nil {
			return 0, err
		}
		ev.Aggregate = agg
		batch = append(batch, ev)
	}
	if len(batch) == 0 {
		return 0, tx.Commit()
	}

	for _, ev := range batch {
		if err := publish(ctx, ev); err != nil {
			return 0, err
		}
		if _, err := tx.ExecContext(ctx, `UPDATE outbox SET status='published' WHERE id=?`, ev.ID); err != nil {
			return 0, err
		}
	}
	return len(batch), tx.Commit()
}

func DemoDDL() string {
	return `
CREATE TABLE IF NOT EXISTS orders (
  id VARCHAR(64) PRIMARY KEY,
  status VARCHAR(32) NOT NULL
);
CREATE TABLE IF NOT EXISTS outbox (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  aggregate_id VARCHAR(64) NOT NULL,
  event_type VARCHAR(128) NOT NULL,
  payload JSON NOT NULL,
  status VARCHAR(16) NOT NULL,
  created_at DATETIME NOT NULL,
  KEY idx_outbox_pending (status, id)
);`
}

工程清单：

• Relay 进程要独立扩容，与 API 进程分离；发布失败应退避重试并将多次失败送入死信队列人工处理。
• 消息体应携带 event_id / aggregate_id / causation_id，与消费者表上的唯一约束联合实现端到端幂等。
• 与第 16 章「事件发布」衔接时，把事件契约（JSON Schema / Protobuf）纳入 CI，避免「字段悄悄改名」造成投影脏写。

Outbox 运维要点：pending 堆积通常不是 Kafka 坏了，而是 Relay 吞吐不足、DB 锁竞争、或下游拒绝消息。建议把以下指标做成仪表盘：outbox_pending_count、relay_lag_seconds、publish_fail_rate、dead_letter_count。出现持续堆积时，优先扩容 Relay 与检查热点 aggregate_id（大单事件风暴）。

顺序投递 vs 批量投递：某些支付相关事件需要严格顺序，Relay 可以按 aggregate_id 分区串行投递；而搜索增量可批量合并，降低总线开销。关键是不要把「所有事件都塞进一个全局顺序」里，否则系统吞吐会被最慢的消费者绑架。

与第 1 章 Outbox 小节的关系：第 1 章强调「领域事件异步化」的动机与边界；本章补齐 实现骨架、时序与运维指标，便于你在第 7–15 章落地到具体服务时直接对照检查清单。

6.4 幂等性设计通用方案

6.4.1 幂等性的本质

幂等性回答的问题是：同一个业务意图被执行多次，是否与只执行一次等价。分布式系统里重复来源包括：用户双击、网关重试、消息重复投递、回调重放。

从接口语义上，幂等还应区分两类返回：

• 语义幂等：第二次调用返回与第一次业务等价的结果（可能 HTTP 状态码不同，但业务码一致），典型是支付创建。
• 严格幂等：第二次调用应尽可能返回同一响应体（含错误），以便客户端无需分支处理；这通常依赖网关或应用侧的 响应缓存。

另一个关键维度是 时间窗口：创单幂等键可能只需 24 小时；支付幂等键可能要跨结算周期。窗口外的重复请求应被明确拒绝还是进入人工？这属于产品策略，但必须在技术方案里写死，否则会出现「以为幂等永远有效」的误用。

6.4.2 实现策略

组合策略才是常态：接口层挡住「明显重复」；服务层用状态机挡住「非法重放」；数据库用唯一约束挡住「并发双插」。任何单层都可能被绕过（例如内部任务不经过网关），因此不要迷信「只加 Header 就安全」。

测试清单：至少覆盖「并发双请求同一幂等键」「第一次超时后重试」「第一次失败第二次成功」「消息重复投递」四类用例；支付与退款还要覆盖「渠道侧已成功但平台超时」的对称场景（与第 15 章联动）。

6.4.3 各层的幂等性保证

flowchart TB
  subgraph Edge[接入层]
    GW[API Gateway\nIdempotency-Key 透传 / 快速去重]
  end
  subgraph App[应用服务层]
    SVC[Service\n幂等表 / 状态机守卫]
  end
  subgraph Data[数据层]
    DB[(MySQL UNIQUE\n业务键 / 请求键)]
    MQ[消息消费者\n消费位点 + 业务唯一键]
  end
  Client[Client] --> GW --> SVC --> DB
  BUS[(Kafka)] --> MQ --> SVC

接口层示例：幂等键落库：

type IdempotencyStore interface {
	// TryBegin 返回 true 表示首次；false 表示重复，应返回缓存响应
	TryBegin(ctx context.Context, key, route string) (bool, error)
	SaveResponse(ctx context.Context, key string, code int, body []byte) error
	GetResponse(ctx context.Context, key string) (code int, body []byte, found bool, err error)
}

func WithCreateOrderIdempotency(store IdempotencyStore, next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		key := r.Header.Get("Idempotency-Key")
		if key == "" {
			http.Error(w, "missing Idempotency-Key", http.StatusBadRequest)
			return
		}
		first, err := store.TryBegin(r.Context(), key, r.URL.Path)
		if err != nil {
			http.Error(w, "idempotency error", http.StatusInternalServerError)
			return
		}
		if !first {
			code, body, found, err := store.GetResponse(r.Context(), key)
			if err != nil || !found {
				http.Error(w, "duplicate without cached response", http.StatusConflict)
				return
			}
			w.WriteHeader(code)
			_, _ = w.Write(body)
			return
		}
		// TODO: 包装 ResponseWriter 捕获状态码与 body，成功后 SaveResponse
		next.ServeHTTP(w, r)
	})
}

服务层：把幂等键与业务键（order_id、payment_id）建立映射；对「处理中」状态设置合理超时，避免永久悬挂。

数据层：对 merchant_order_no、channel_trade_no 等建立 UNIQUE 索引；冲突时读取已有行并返回与首次一致的结果体（支付场景极其关键，见第 15 章）。

消息消费者层：除了业务唯一键，还要注意 at-least-once 带来的「处理成功但 ack 前崩溃」重复。常见做法是：业务写入与「消费记录」同事务，或采用 幂等表 + 业务状态机 组合。Kafka 的幂等 producer 只能保证生产端不重复，不能保证消费端。

与第 13–15 章的衔接：购物车提交、结算创单、支付创建与回调，是幂等设计最密集的区域。请把这些链路里的 Idempotency-Key 来源、TTL、冲突返回码统一成一份「交易接口规范」，否则每个团队会发明一种错误语义，客户端与对账都会被拖垮。

6.5 数据一致性保证

6.5.1 最终一致性

最终一致性不是「暂时不一致然后祈祷」，而是满足三个条件：

1. 收敛性：在无新写入时，系统应到达稳定态。
2. 可观测性：能度量漂移（延迟、差异条数）。
3. 可修复性：通过对账与补偿把漂移拉回业务可接受范围。

最终一致的工程含义：允许短暂不一致，但不允许「永远不一致」。因此必须定义 最大允许漂移时间（MTTD） 与 修复时限（MTTR） 的业务含义。例如「支付回调最多延迟 5 分钟，对账必须在 T+1 日内闭环」，这类指标比对程序员说「我们最终一致」更有约束力。

与缓存的关系：读路径缓存（商品详情、列表价）引入的是另一类一致性。原则是：写路径更新权威，再异步失效 / 刷新缓存；不要反过来用缓存驱动写。库存热路径若使用 Redis，必须与第 8 章一样把 对账与回补 当作一等能力，而不是事后补丁。

6.5.2 对账机制

对账回答的问题是：两份账本是否在说同一件事。电商常见对账维度：

• 平台订单 vs 支付渠道：金额、手续费、状态、退款。
• 库存流水 vs 实物出库：WMS / OMS 对齐。
• 营销预算 vs 实际核销：防止薅羊毛与预算透支。

设计要点（与第 8 章库存、第 15 章支付呼应）：

1. 对账文件与解析：渠道侧日终文件 + 平台侧流水导出；解析必须版本化。
2. 三层匹配：长款（渠道有平台无）、短款（平台有渠道无）、金额不一致。
3. 差错工单：自动修复仅限白名单场景；其余进入人工复核。
4. 幂等与回放：同一对账批次重复跑不产生重复账务分录。

对账批次生命周期（建议）：INIT → PARSED → MATCHED → DIFF_GENERATED → FIXUP_APPLIED → CLOSED。每一步落审计日志，支持监管问询与内部复盘。短款与长款不要混在一个工单模板里：短款更像「钱可能丢了」，长款更像「重复记账风险」，处理 SLA 与审批链往往不同。

平台侧数据准备：对账不只读「业务库」，还要聚合 渠道回调日志、网关请求日志、消息投递记录。否则你会出现「业务状态对，但财务凭证缺角」的尴尬。实践中常用 不可变事件流水 作为对账输入之一，因为它比业务表更抗「事后改字段」。

与第 8 章库存对账的衔接：库存侧常见是 Redis 计数与 MySQL 流水、供应商快照三方对齐。支付侧则是平台支付单与渠道清算文件对齐。两者共享同一套工程套路：差异分类 → 自动白名单修复 → 人工复核 → 复盘入库。

package recon

import (
	"context"
	"database/sql"
	"time"
)

type ChannelRow struct {
	TradeNo     string
	AmountCents int64
	Status      string
	OccurredAt  time.Time
}

type PlatformRow struct {
	PaymentID   string
	ChannelRef  string
	AmountCents int64
	Status      string
}

// ReconcileBatch 演示：以 channel_ref 对齐（生产需处理多币种、多清算周期）
func ReconcileBatch(ctx context.Context, db *sql.DB, ch []ChannelRow, pf []PlatformRow) error {
	pidx := map[string]PlatformRow{}
	for _, p := range pf {
		pidx[p.ChannelRef] = p
	}
	tx, err := db.BeginTx(ctx, nil)
	if err != nil {
		return err
	}
	defer func() { _ = tx.Rollback() }()

	for _, c := range ch {
		p, ok := pidx[c.TradeNo]
		if !ok {
			_, _ = tx.ExecContext(ctx, `INSERT INTO recon_diff(batch_at, kind, ref, detail) VALUES(?,?,?,?)`,
				time.Now().UTC(), "SHORT_PLATFORM", c.TradeNo, "channel has, platform missing")
			continue
		}
		if p.AmountCents != c.AmountCents || p.Status != c.Status {
			_, _ = tx.ExecContext(ctx, `INSERT INTO recon_diff(batch_at, kind, ref, detail) VALUES(?,?,?,?)`,
				time.Now().UTC(), "MISMATCH", c.TradeNo, "amount or status")
		}
	}
	return tx.Commit()
}

差错分类与处理策略（支付对账视角的抽象）：无论渠道是微信、支付宝还是银行卡收单，差异最终都会落到有限几类。

• 状态不一致但金额一致：常见于回调丢失或延迟。处理上优先以渠道终态为准触发状态迁移，并确保迁移动作幂等。
• 金额不一致：高风险，通常需要冻结相关支付单与关联订单，禁止自动发货，进入财务复核；同时要回溯是否存在重复退款、重复记账或币种转换错误。
• 手续费 / 分账字段不一致：多见于规则变更窗口与历史数据混跑。处理上应引入 规则版本号 与 生效时间，避免用新规则解释旧交易。
• 时间窗口不一致：渠道文件是「清算日」，平台流水是「交易发生日」。对账前要先把口径写到 SOP：以哪个时区、哪个切分点为准。

自动化修复的边界：只有满足「可逆、可证明、可回放」三条件的动作才适合自动化。例如「补写缺失的支付回调记录」可以自动化；「直接给用户退款」通常需要更高等级审批与多重校验。自动化的目标是减少人工 机械劳动，不是替代 风险判断。

6.5.3 补偿任务

补偿任务与 Saga 补偿不同：后者在请求生命周期内；前者是异步修复器，用于：

• 回调迟到导致的悬挂单；
• 消息堆积造成的投影落后；
• 对账发现的轻微差异批量冲正。

设计清单：可重入、批大小上限、死信隔离、人工止血的开关。

任务编排建议：补偿任务尽量 幂等、可观测、可暂停。出现大面积渠道故障时，最危险的是「自动修复脚本跑得比人还快」，把差错扩散成二次事故。要有 全局开关 + 分渠道开关 + 最大自动修复笔数阈值。

与支付补偿的差异：Saga 补偿发生在用户请求上下文内，强调快速失败与回滚；异步补偿任务发生在分钟到小时级窗口，强调批处理、限流与审计。两者不要混用同一套重试策略。

案例化走读：支付回调迟到（与第 15 章呼应）：用户支付成功，渠道回调因网络抖动晚到 10 分钟。期间订单可能停留在「待支付」，客服系统可能提示用户重复支付。补偿任务不应「直接改状态为成功」了事，而应执行一条可审计的状态迁移：WAIT_PAY → PAID，并触发 履约消息、发票消息、积分入账 等下游；每一步仍要带幂等键，避免回调重复造成重复履约。

案例化走读：库存 Redis 与 MySQL 漂移（与第 8 章呼应）：热路径扣减在 Redis，权威在 MySQL。对账发现 Redis 小于 MySQL 的可用量，可能意味着回补丢失；反过来可能意味着 Redis 多扣。修复策略应区分「业务可自动纠正」与「需要冻结 SKU 人工介入」。自动纠正必须带 上限 与 来源证据（流水号、操作者、任务批次），否则会把数据修复变成新的数据破坏源。

6.6 集成模式总结

6.6.1 同步调用模式

• 适用：强实时、需要立即失败反馈（试算、库存预占校验）。
• 要点：超时、重试、熔断、幂等键、向后兼容的 API 版本。

常见反模式：把十几个同步调用串成「上帝编排」，任何一个下游抖动都会放大尾延迟；没有 bulkhead（舱壁） 时，还会出现「支付抖动拖垮创单」的级联故障。治理手段包括：并发化可并行步骤、硬超时 + 部分降级、把非关键校验挪到异步。

接口演进：同步集成最怕破坏性变更。建议强制 version 字段或 URL 版本，并在网关层做 灰度路由；同时给客户端明确的 错误码字典（业务拒绝 vs 基础设施失败），否则重试风暴不可避免。

6.6.2 异步消息模式

• 适用：解耦峰值、跨团队广播事实、最终一致投影。
• 要点：Outbox、消费者幂等、严格有序 vs 并行的权衡、死信队列。

典型反模式：业务先写库再「顺手发 Kafka」，崩溃窗口会导致消息丢失；或消费者不做幂等，靠「应该不会重复」的侥幸心理。另一个反模式是 把异步当同步用：通过轮询消息结果阻塞用户请求，这会把消息系统的延迟特性原封不动搬进关键路径。

观测性：异步链路必须能回答三个问题：消息发出去了吗、消息被处理了吗、处理正确吗。分别对应 Outbox 状态、消费者 lag、对账差异。

6.6.3 数据同步模式

• CDC / Binlog 订阅：近实时同步到数仓或搜索；关注 schema 变更治理。
• 定时批量：对账、报表、冷数据归档。
• 双写：高风险，仅在迁移窗口短期使用，需校验任务护航。

CDC 的边界：它擅长复制「事实行变更」，但不自动复制「业务含义」。例如拆表、改主键、把枚举从字符串改成数字，都会让下游投影误读。需要 契约变更流程 与 双读双写过渡期。

定时批量的价值：很多一致性不是实时问题，而是「日终必须平」。批量任务的关键是 可重跑、可分段、可限流，并在大促日提前做 容量演练。

6.6.4 选型决策树

flowchart TD
  Q1{需要立即知道\n下游成功与否?}
  Q1 -->|是| Q2{失败是否必须\n阻断用户?}
  Q1 -->|否| M[异步消息 +\nOutbox / 消费者幂等]

  Q2 -->|是| S[同步 RPC\n+ 超时 / 熔断 / 幂等键]
  Q2 -->|否| Q3{是否可以接受\n秒级最终一致?}
  Q3 -->|是| M
  Q3 -->|否| S

  S --> Q4{是否广播给\n多个订阅方?}
  Q4 -->|是| HY[同步拿到关键凭证\n+ 异步事件分发读模型]
  Q4 -->|否| S

  M --> Q5{是否需要强审计\n可回放?}
  Q5 -->|是| ES[评估事件溯源 /\n不可变日志]
  Q5 -->|否| P[物化视图 +\n对账修复]

  style S fill:#e3f2fd
  style M fill:#e8f5e9
  style HY fill:#fff3e0
  style ES fill:#f3e5f5
  style P fill:#eceff1

如何使用决策树（避免误用）：决策树的每个叶子都不是「唯一正确答案」，而是默认起点。真实系统往往处在叶子之间的灰区：例如创单需要同步拿到 price_snapshot_id，但搜索索引更新可以异步。灰区的处理原则是：把「用户当下要看到的结果」留在同步路径，把「世界最终会知道的结果」放到异步路径，并用对账兜底。

与实时性相关的常见误判：团队容易把「运营后台要立即看到」误认为「用户主链路必须同步」。后台可采用 近实时 CDC + 物化视图，而用户侧主链路仍应保持最小同步半径。把后台需求塞进核心交易链路，是尾延迟与大促故障的高频来源。

与后续章节的关系（阅读地图）：

• 商品、搜索、推荐：AP + 异步投影为主，强调延迟可观测（第 7、12 章）。
• 库存、营销：同步预占 / 锁定 + 异步对账（第 8、9 章）。
• 计价、购物车：读路径可弱一致；写路径谨慎用缓存（第 11、13 章）。
• 订单、支付：幂等 + 对账 + 补偿任务三位一体的资金安全网（第 14、15 章）。

6.7 本章小结

本章建立了系统集成的方法论「四件套」：

1. CAP 与一致性谱系帮助你在分区现实下做可解释的取舍，而不是用「都要」掩盖矛盾。
2. Saga（编排优先）给出跨服务长流程的工程主路径，补偿必须可逆且幂等。
3. 事件驱动 + Outbox 把「写库再发消息」变成可验证的本地事务，为 CQRS 投影与搜索增量提供底座。
4. 幂等与对账 是分布式世界的安全带：前者防重复，后者治漂移；补偿任务负责把系统从边角态拉回主航道。

落地检查清单（建议你复制到评审模板）：

• 每个跨服务写链路是否写明 一致性级别（用户可见 / 财务 / 读模型）？
• 是否存在「先外部成功、后本地提交」的窗口？若有，是否有 query/reconcile？
• 关键接口是否具备 幂等键 与 冲突返回语义？
• 是否避免「双写」作为长期方案？若必须双写，是否有 校验任务？
• 事件是否走 Outbox？Relay 是否有 堆积告警？
• 是否定义 对账批次 与 差错分级？自动修复是否有 阈值与开关？
• Saga / 异步任务是否 可重入？是否能在发布滚动中恢复？

给团队负责人的一句话建议：把「集成复杂度」当作与「业务复杂度」并列的成本项。没有 Outbox、没有对账、没有幂等键的系统也能上线，但它会把成本推迟到 大促夜、监管审计、渠道切流 这些最难的时刻一次性兑现。本章的目的，是把这部分成本前移为 可评审、可测试、可监控 的工程资产。

给一线开发者的一句话建议：写跨服务调用时，默认网络会超时、消息会重复、回调会迟到；把这三条写进单元测试与集成测试的假设里，比写一百行防御性注释更有用。

带着这套语言进入第 7 章之后的各子系统，你会更容易判断：此处该同步还是异步、事件应不应该广播、失败该当场回滚还是记账异步修。下一章（第 7 章）将从商品中心开始，把这些模式落实到具体边界与接口之上。

导航：书籍主页 | 完整目录 | 上一章：第3章 | 下一章：第5章

导航：书籍主页 | 完整目录 | 上一章：第4章 | 下一章：第6章

第5章 编码原则与设计模式

用整洁代码、Pipeline、策略与规则引擎承接架构设计

3.1 复杂业务代码的痛点

第1章解决了「系统如何分层、依赖如何向内」的问题；本章解决「同一层里，代码如何写得可演进、可测试」。电商的下单、库存、营销是典型的长流程 + 多分支 + 高频变更场景，若缺少约束，业务代码会迅速腐化。

3.1.1 千行函数的噩梦

下面这段伪代码浓缩了真实项目中常见的「上帝函数」形态：校验、读用户、查库存、算价、营销、风控、落库、支付、通知全部堆在一个入口里。

// ❌ 反例：单函数承载整条下单链路（职责过多、难以测试）
func CreateOrder(req *CreateOrderRequest) (*Order, error) {
	if req == nil || req.UserID == "" || len(req.Items) == 0 {
		return nil, errors.New("invalid request")
	}
	// 用户信息、库存、价格、券、积分、运费、活动、风控……
	// 数百行嵌套在同一函数中，修改任意一步都可能波及其他步骤
	return &Order{}, nil
}

直接后果：

• 无法为「只改营销校验」写独立单测，只能起全套集成环境；
• Code Review 难以聚焦，合并冲突集中在一个文件；
• 新人需要整段读完才敢改一行。

3.1.2 代码腐化的根因

3.1.3 技术债的累积

技术债不一定是「烂代码」，更多时候是当时合理、后来失配的设计：例如早期用三层 Service 足够，随着营销玩法与多仓库存策略叠加，仍坚持在一个 OrderService 里堆逻辑，债就滚雪球。

可操作的止损线（团队可写入评审清单）：

• 单个导出函数超过约 80～120 行（视团队约定）必须拆分或抽 Pipeline；
• 圈复杂度（McCabe）超过约定阈值必须拆解策略或子函数；
• 同一文件内出现 3 处以上「复制粘贴再改一点」的折扣/库存分支，优先考虑策略或规则表。

flowchart LR
	A[需求变更] --> B{能否局部修改?}
	B -->|否| C[千行函数 / 深层 if-else]
	C --> D[测试困难]
	D --> E[不敢重构]
	E --> C

3.2 函数设计原则

在引入模式之前，先收紧函数级的纪律：这是所有模式能落地的前提。

3.2.1 单一职责

一个函数应回答一个业务问题。例如「校验下单请求」与「持久化订单」不应混在同一函数中。

// ❌ 反例：校验与副作用混在一起
func PlaceOrder(ctx context.Context, req *PlaceOrderRequest, db *sql.DB) error {
	if req.CustomerID == "" {
		return errors.New("customer required")
	}
	_, err := db.ExecContext(ctx, `INSERT INTO orders (...) VALUES (...)`, req.CustomerID)
	return err
}

// ✅ 正例：校验纯函数化，写库由仓储承担
func ValidatePlaceOrder(req *PlaceOrderRequest) error {
	if req.CustomerID == "" {
		return errors.New("customer required")
	}
	if len(req.Lines) == 0 {
		return errors.New("order lines required")
	}
	return nil
}

3.2.2 函数长度控制

经验法则：一屏能读完（含错误处理）较理想。长逻辑不是「拆成很多小函数」就够了，还要让调用方读出业务流程，这正是 3.3 节 Pipeline 的价值。

3.2.3 参数设计

参数过多往往说明缺少「用例级上下文」。把一次下单所需输入收敛为 PlaceOrderInput，中间态收敛为 PlaceOrderState（或下文 OrderPipeContext），Handler 只负责绑定 HTTP → DTO → 用例输入。

// ❌ 反例：参数平面展开
func PriceForCheckout(userID, region, platform string, qty int, skuID string, useCoupon bool, couponCode string) (int64, error) {
	return 0, nil
}

// ✅ 正例：输入聚合为结构体
type CheckoutPriceQuery struct {
	UserID     string
	Region     string
	Platform   string
	SKU        string
	Qty        int
	CouponCode string
}

3.2.4 错误处理

在 Go 中建议：

• 可预期业务失败用哨兵错误或自定义类型，便于上层映射 HTTP 4xx；
• 系统/依赖故障用 %w 包装，保留链路与 errors.Is / As 能力；
• 不要在业务深层 log.Fatal，把决策留在 main 或任务入口。

// ✅ 正例：包装依赖错误
func (r *MySQLOrderRepo) Save(ctx context.Context, o *Order) error {
	if _, err := r.db.ExecContext(ctx, `INSERT INTO orders (id, customer_id) VALUES (?, ?)`, o.ID, o.CustomerID); err != nil {
		return fmt.Errorf("order repo save: %w", err)
	}
	return nil
}

3.3 Pipeline 模式

Pipeline（管道）把阶段化流程显式化：每一步是一个 Processor，共享一个上下文，由 Pipeline 顺序驱动。它与责任链的共同点都是「链式处理」，不同之处在于：Pipeline 更强调数据沿管道变换、阶段职责清晰，常用于下单、结算试算、营销列表组装等。

3.3.1 从嵌套到流水线

flowchart LR
	P1[Validate] --> P2[LoadUser]
	P2 --> P3[ReserveInventory]
	P3 --> P4[ApplyPricing]
	P4 --> P5[PersistOrder]

对比：

3.3.2 实现要点

1. 上下文对象：承载输入、中间结果、错误累积标记；避免用包级变量。
2. 早失败：任一步返回错误即中止管道（或实现可配置的「继续/中止」策略）。
3. 命名：Processor.Name() 便于日志与指标打标签。
4. 与 Clean Architecture：Pipeline 通常落在 Application / Use Case 编排层，领域不变量仍在聚合根内。

3.3.3 订单处理的 Pipeline 实例

下面给出一份可编译思路的精简实现：创建订单流水线——校验 → 加载商品行 → 预留库存 → 写单。

package orderpipe

import (
	"context"
	"errors"
	"fmt"
)

// OrderPipeContext 承载一次「创单」流水线的输入与中间态。
type OrderPipeContext struct {
	Req            PlaceOrderRequest
	ResolvedLines  []OrderLine
	ReservationID  string
	CreatedOrderID string
}

type PlaceOrderRequest struct {
	CustomerID string
	Lines      []LineRequest
}

type LineRequest struct {
	SKU string
	Qty int
}

type OrderLine struct {
	SKU       string
	Qty       int
	UnitCents int64
}

// Processor 单步处理逻辑。
type Processor interface {
	Name() string
	Process(ctx context.Context, c *OrderPipeContext) error
}

// Pipeline 顺序执行。
type Pipeline struct {
	steps []Processor
}

func NewPipeline(steps ...Processor) *Pipeline {
	return &Pipeline{steps: steps}
}

func (p *Pipeline) Run(ctx context.Context, c *OrderPipeContext) error {
	for _, s := range p.steps {
		if err := ctx.Err(); err != nil {
			return err
		}
		if err := s.Process(ctx, c); err != nil {
			return fmt.Errorf("%s: %w", s.Name(), err)
		}
	}
	return nil
}

// --- Processors ---

type validateProcessor struct{}

func (validateProcessor) Name() string { return "validate" }

func (validateProcessor) Process(_ context.Context, c *OrderPipeContext) error {
	if c.Req.CustomerID == "" {
		return errors.New("customer_id required")
	}
	if len(c.Req.Lines) == 0 {
		return errors.New("at least one line")
	}
	return nil
}

type Catalog interface {
	ResolveLines(ctx context.Context, lines []LineRequest) ([]OrderLine, error)
}

type resolveCatalogProcessor struct{ cat Catalog }

func (p resolveCatalogProcessor) Name() string { return "resolve_catalog" }

func (p resolveCatalogProcessor) Process(ctx context.Context, c *OrderPipeContext) error {
	lines, err := p.cat.ResolveLines(ctx, c.Req.Lines)
	if err != nil {
		return err
	}
	c.ResolvedLines = lines
	return nil
}

type Inventory interface {
	Reserve(ctx context.Context, customerID string, lines []OrderLine) (reservationID string, err error)
}

type reserveInventoryProcessor struct{ inv Inventory }

func (p reserveInventoryProcessor) Name() string { return "reserve_inventory" }

func (p reserveInventoryProcessor) Process(ctx context.Context, c *OrderPipeContext) error {
	rid, err := p.inv.Reserve(ctx, c.Req.CustomerID, c.ResolvedLines)
	if err != nil {
		return err
	}
	c.ReservationID = rid
	return nil
}

type OrderRepository interface {
	Insert(ctx context.Context, c *OrderPipeContext) (orderID string, err error)
}

type persistOrderProcessor struct{ repo OrderRepository }

func (p persistOrderProcessor) Name() string { return "persist_order" }

func (p persistOrderProcessor) Process(ctx context.Context, c *OrderPipeContext) error {
	id, err := p.repo.Insert(ctx, c)
	if err != nil {
		return err
	}
	c.CreatedOrderID = id
	return nil
}

组装处（例如在 cmd 或 application 包）一眼读完流程：

func NewPlaceOrderPipeline(cat Catalog, inv Inventory, repo OrderRepository) *Pipeline {
	return NewPipeline(
		validateProcessor{},
		resolveCatalogProcessor{cat: cat},
		reserveInventoryProcessor{inv: inv},
		persistOrderProcessor{repo: repo},
	)
}

3.4 策略模式

当分支维度稳定、而每个分支内部都很厚时，用策略（Strategy）把「选谁」与「怎么做」拆开：注册表负责选择，策略对象负责算法。

3.4.1 消除 if-else

// ❌ 反例：按库存类型硬编码
func ReserveStock(kind string, sku string, qty int) error {
	if kind == "platform" {
		return platformReserve(sku, qty)
	} else if kind == "vendor_realtime" {
		return vendorRealtimeReserve(sku, qty)
	} else if kind == "vendor_async" {
		return vendorAsyncReserve(sku, qty)
	}
	return errors.New("unknown stock kind")
}

新增一种库存来源时，必须修改该函数，违反开闭原则，且冲突面大。

3.4.2 策略的注册与选择

package stockstrategy

import (
	"context"
	"errors"
	"fmt"
)

type ReserveInput struct {
	SKU string
	Qty int
}

// Reserver 库存预留策略。
type Reserver interface {
	Kind() string
	Reserve(ctx context.Context, in ReserveInput) error
}

type Registry struct {
	byKind map[string]Reserver
}

func NewRegistry(rs ...Reserver) (*Registry, error) {
	m := make(map[string]Reserver, len(rs))
	for _, r := range rs {
		k := r.Kind()
		if _, dup := m[k]; dup {
			return nil, fmt.Errorf("duplicate reserver: %s", k)
		}
		m[k] = r
	}
	return &Registry{byKind: m}, nil
}

func (reg *Registry) Reserve(ctx context.Context, kind string, in ReserveInput) error {
	r, ok := reg.byKind[kind]
	if !ok {
		return errors.New("unknown stock kind")
	}
	return r.Reserve(ctx, in)
}

3.4.3 库存策略的实例

type platformReserver struct{}

func (platformReserver) Kind() string { return "platform" }

func (platformReserver) Reserve(ctx context.Context, in ReserveInput) error {
	// 调用平台自有库存服务（Redis + DB 等）
	_ = ctx
	if in.Qty <= 0 {
		return errors.New("qty must be positive")
	}
	return nil
}

type vendorRealtimeReserver struct{}

func (vendorRealtimeReserver) Kind() string { return "vendor_realtime" }

func (vendorRealtimeReserver) Reserve(ctx context.Context, in ReserveInput) error {
	// 同步调用供应商库存 API
	_ = ctx
	return nil
}

type vendorAsyncReserver struct{}

func (vendorAsyncReserver) Kind() string { return "vendor_async" }

func (vendorAsyncReserver) Reserve(ctx context.Context, in ReserveInput) error {
	// 写入待同步队列，由异步任务向供应商确认
	_ = ctx
	_ = in
	return nil
}

classDiagram
	class Reserver {
		<<interface>>
		+Kind() string
		+Reserve(ctx, in) error
	}
	Reserver <|.. platformReserver
	Reserver <|.. vendorRealtimeReserver
	Reserver <|.. vendorAsyncReserver
	Registry --> Reserver : lookup by kind

与 Pipeline 的分工：Pipeline 回答「先做啥后做啥」；策略回答「同一类步骤里用哪套算法」。例如「预留库存」这一步内部再根据 kind 选策略。

3.5 规则引擎

3.5.1 何时需要规则引擎

适合：

• 运营频繁调整的门槛、互斥、叠加（满减、品类券、会员日）；
• 需要按优先级尝试多条规则，并输出可追溯的「命中说明」。

不适合：

• 极少变化且分支很少（直接写在领域服务里更清晰）；
• 强实时、超低延迟且规则解释执行成本高（需编译型或预计算方案）。

3.5.2 轻量级规则引擎设计

核心思想：规则 = 条件（数据） + 动作（数据），引擎负责排序、匹配、互斥与累计。下面示例用内存规则列表演示；生产可替换为从 DB 加载并带版本号缓存。

package rules

import (
	"context"
	"errors"
	"fmt"
	"sort"
	"time"
)

type MarketingContext struct {
	Now       time.Time
	NewUser   bool
	Subtotal  int64 // 分
	VIPLevel  int
	Category  string
}

type Effect struct {
	RuleID   int
	RuleName string
	Discount int64 // 分，正数表示扣减应付
}

type Rule struct {
	ID         int
	Name       string
	Priority   int
	Enabled    bool
	Start, End time.Time
	MutexWith  []int
	When       func(MarketingContext) bool
	Apply      func(*MarketingContext, *Evaluation) error
}

type Evaluation struct {
	Applied []Effect
	used    map[int]struct{}
}

func NewEvaluation() *Evaluation {
	return &Evaluation{used: make(map[int]struct{})}
}

func (e *Evaluation) markUsed(id int) {
	e.used[id] = struct{}{}
}

func (e *Evaluation) hasUsedAny(ids []int) bool {
	for _, id := range ids {
		if _, ok := e.used[id]; ok {
			return true
		}
	}
	return false
}

type Engine struct {
	rules []*Rule
}

func NewEngine(r ...*Rule) *Engine {
	rs := append([]*Rule(nil), r...)
	sort.Slice(rs, func(i, j int) bool { return rs[i].Priority > rs[j].Priority })
	return &Engine{rules: rs}
}

func (eng *Engine) Evaluate(ctx context.Context, mc MarketingContext) (*Evaluation, error) {
	_ = ctx
	out := NewEvaluation()
	for _, rule := range eng.rules {
		if !rule.Enabled {
			continue
		}
		if mc.Now.Before(rule.Start) || mc.Now.After(rule.End) {
			continue
		}
		if out.hasUsedAny(rule.MutexWith) {
			continue
		}
		if rule.When == nil || !rule.When(mc) {
			continue
		}
		out.Applied = append(out.Applied, Effect{RuleID: rule.ID, RuleName: rule.Name})
		if err := rule.Apply(&mc, out); err != nil {
			out.Applied = out.Applied[:len(out.Applied)-1]
			return nil, fmt.Errorf("rule %d: %w", rule.ID, err)
		}
		out.markUsed(rule.ID)
	}
	return out, nil
}

3.5.3 营销规则引擎实例

func DemoRules() *Engine {
	return NewEngine(
		&Rule{
			ID: 1, Name: "新客首单立减", Priority: 100, Enabled: true,
			Start: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
			End:   time.Date(2026, 12, 31, 0, 0, 0, 0, time.UTC),
			When: func(m MarketingContext) bool { return m.NewUser },
			Apply: func(m *MarketingContext, ev *Evaluation) error {
				d := int64(2000)
				m.Subtotal -= d
				if m.Subtotal < 0 {
					return errors.New("subtotal underflow")
				}
				ev.Applied[len(ev.Applied)-1].Discount = d
				return nil
			},
		},
		&Rule{
			ID: 2, Name: "满 100 减 15", Priority: 80, Enabled: true,
			Start: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
			End:   time.Date(2026, 12, 31, 0, 0, 0, 0, time.UTC),
			MutexWith: []int{1},
			When:      func(m MarketingContext) bool { return m.Subtotal >= 10000 },
			Apply: func(m *MarketingContext, ev *Evaluation) error {
				d := int64(1500)
				m.Subtotal -= d
				ev.Applied[len(ev.Applied)-1].Discount = d
				return nil
			},
		},
		&Rule{
			ID: 3, Name: "数码品类满减", Priority: 70, Enabled: true,
			Start: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
			End:   time.Date(2026, 12, 31, 0, 0, 0, 0, time.UTC),
			When: func(m MarketingContext) bool { return m.Category == "digital" && m.Subtotal >= 5000 },
			Apply: func(m *MarketingContext, ev *Evaluation) error {
				d := int64(500)
				m.Subtotal -= d
				ev.Applied[len(ev.Applied)-1].Discount = d
				return nil
			},
		},
	)
}

生产落地时，可将 When / Apply 替换为声明式条件 AST + 有限动作集，配合配置中心热更新；与第9章「营销计算引擎」衔接时，注意资损防控（双写试算、幂等锁券）。

flowchart TB
	subgraph Engine
		R1[按优先级遍历规则]
		R2{时间窗与开关}
		R3{互斥检查}
		R4{条件匹配}
		R5[执行动作 / 累计结果]
		R1 --> R2 --> R3 --> R4 --> R5
	end
	MC[(MarketingContext)] --> Engine
	Engine --> OUT[(Evaluation / 命中说明)]

3.6 依赖注入与测试

3.6.1 接口与依赖反转

Pipeline 的 Processor、策略的 Reserver、规则引擎依赖的「加载器」都应在内层定义接口，由外层适配器实现——这与第1章的 Port-Adapter 一致。

3.6.2 依赖注入模式

推荐顺序（与第1章一致）：

1. 手动构造（依赖数量可控时最清晰）；
2. Wire 生成装配代码（中大型服务）；
3. Fx（需要生命周期与动态插件时）。

Pipeline 本身通过构造函数注入 Catalog、Inventory、OrderRepository，不要在 Processor 内部 sql.Open。

3.6.3 可测试性设计

// ✅ 正例：假库存用于单测 Pipeline
type fakeInventory struct{}

func (fakeInventory) Reserve(ctx context.Context, customerID string, lines []OrderLine) (string, error) {
	_ = ctx
	_ = customerID
	_ = lines
	return "resv_test_1", nil
}

测试用例应覆盖：

• 每步 Processor 的失败路径（确保错误带上 Name）；
• 策略注册表的重复 Kind、未知 Kind；
• 规则引擎的互斥与优先级（同一输入下命中顺序稳定）。

3.7 本章小结

本章从电商落地视角串联了四件事：

1. 痛点：千行函数与深层 if-else 是技术债的外显，要用团队约定的长度与复杂度红线约束。
2. 函数纪律：单一职责、参数对象化、fmt.Errorf 包装错误，是 Pipeline / 策略能读得懂的前提。
3. Pipeline：把「创单」等长流程拆为阶段与共享上下文，编排层即文档。
4. 策略与轻量规则引擎：策略消除「选算法」的 if-else；规则引擎把高频变更从代码挪到数据，并保留优先级与互斥扩展位。
5. 依赖注入：Processor / Reserver / Loader 均通过接口注入，测试以 Fake 替换，延续第1章的整洁架构边界。

与全书的关系：第1章给出组合拳总览，第3章讨论系统内部结构，第4章讨论系统间协作；本章则把这些架构原则继续下沉到代码层，给出同层内的组织手法。下一章将进一步从评审与上线检查角度，防止这些工程纪律在落地中回潮。

导航：返回目录 | 上一章：第4章 | 书籍主页 | 下一章：第6章

导航：书籍主页 | 完整目录 | 上一章：第5章 | 下一章：第7章

第6章 架构质量保障

从设计评审到上线检查，建立架构落地的质量防线

4.1 为什么需要分阶段评审

软件工程里有一句常被引用的话：好的代码是重构出来的，不是一次写出来的。初稿几乎必然欠打磨，真正可靠的质量来自持续、有纪律的迭代。Code Review 把这种迭代前移到合并之前——它把个人习惯拉平到团队标准，把隐性知识显性化，把缺陷拦截在扩散之前。

然而，「随便看看」式的评审往往流于表面：有人只看风格，有人只看有没有明显 bug，有人被 diff 的噪声淹没。结果是：架构层面的失误晚到无法廉价修正，设计层面的模糊在代码里被放大成技术债，上线前才发现性能或可观测性缺口。

4.1.1 单次 PR 评审的认知陷阱

Checklist 的价值在于降低认知负荷：在疲劳、时间压力或上下文切换时，仍有一个外部脚手架防止遗漏。它并不替代经验与判断力——遇到清单未覆盖的灰区，恰恰说明团队应该把新教训反哺进清单或 ADR（Architecture Decision Record）。

4.1.2 四阶段评审：在正确时机问正确问题

本书建议按四个阶段组织评审，而不是在单次 PR 里眉毛胡子一把抓：

1. 架构评审：新项目、新服务、新子域或大规模模块拆分——确认分层、边界、读写路径与技术选型。
2. 设计评审：接口与模型冻结前——核对聚合、命令 / 查询、领域事件与模式选型是否与领域一致。
3. 代码评审：日常 MR——用 SOLID、函数质量、命名、错误处理与依赖方向守住实现细节。
4. 上线前检查：发布窗口——补齐性能、并发、可观测性、测试、回滚与文档。

flowchart LR
  A[架构评审<br/>设计期] --> B[设计评审<br/>详设期]
  B --> C[代码评审<br/>MR 期]
  C --> D[上线前检查<br/>合并期]
  D --> E[发布 / 观测 / 复盘]

4.1.3 运作建议：让清单「活」起来

• 责任人明确：架构项由 Tech Lead / 架构负责人主评；设计项由领域 Owner 主评；PR 项由作者与至少一名熟悉该域的审阅者共担；上线前项与 SRE / On-call 对齐。
• 粒度分层：巨型 MR 可先要求作者附「自审清单」勾选说明，再在评论里对争议点逐条引用章节编号，避免无结构的「感觉不对」。
• 与工具链结合：复杂度、静态检查、依赖图、覆盖率门槛作为门禁；清单作为人工语义层补充（例如：覆盖率够了但测的是 happy path，仍需人眼过业务不变量）。
• 可追溯结论：架构与设计阶段的结论落在 ADR、RFC 或设计文档；Code Review 只核对「实现是否背离结论」。PR 中发现架构级问题应上升到设计讨论，而不是在局部 hack 里修掉症状。

团队实践案例

案例 1：架构评审会的标准流程（某电商团队实践）

时机：新服务立项、重大重构（影响 3+ 服务）、技术选型变更

参与者：

• 必需：Tech Lead、系统负责人、相关团队代表
• 可选：SRE（高可用关注）、DBA（存储关注）、安全（合规关注）

流程（60 分钟）：

1. 背景介绍（5分钟）：系统负责人讲解业务背景、问题域、核心挑战
2. 架构方案宣讲（15分钟）：分层、限界上下文、读写路径、技术选型
3. 质疑与讨论（30分钟）：按 4.2 清单逐项检查，重点追问：
   • 依赖方向是否违反？
   • 边界划分是否合理？（参考第 2 章战略设计）
   • 读写比假设是否量化？
   • YAGNI 检查：是否过度设计？
4. 决策与记录（10分钟）：
   • 通过 / 有条件通过 / 回炉重做
   • 记录到 ADR（Architecture Decision Record）
   • 指定 Follow-up 责任人

输出示例（ADR-015）：

## ADR-015: 订单域引入 CQRS

### 状态
已批准（2026-04-15）

### 背景
订单查询（订单列表、详情、搜索）QPS 是写入的 50 倍；
当前写模型（含 JOIN）拖慢查询性能。

### 决策
引入 CQRS，读模型使用物化视图（MySQL）+ ES 索引。

### 方案
- 写模型：订单聚合 + Outbox 事件
- 读模型：订阅 OrderPlaced / OrderPaid 事件，更新 order_view 表与 ES
- 一致性：最终一致（可容忍 1-2 秒延迟）

### 风险与对策
- 风险：读写数据不一致
- 对策：对账任务（每小时），差异告警

### 评审结论
通过，需在 Q2 上线前完成性能压测。

案例 2：设计评审中发现聚合边界过大

背景：订单团队在设计评审时提交了一个 Order 聚合，包含订单基础信息、明细、支付记录、履约记录、售后记录。

评审意见：

• 问题：聚合过大，任何字段变更都需要加载整个对象，性能差
• 追问：「支付记录」是否需要和订单在同一事务中修改？
• 结论：不需要——支付成功是外部事件触发，可以通过事件异步更新

重构方案：

• Order 聚合：订单基础信息 + 明细（需要强一致性）
• Payment 聚合：支付记录（独立生命周期）
• Fulfillment 聚合：履约记录（独立生命周期）
• 集成：通过领域事件（OrderPlaced、OrderPaid）衔接

收益：订单聚合从平均 2KB 缩小到 500 字节，查询性能提升 4 倍。

案例 3：PR 评审中拦截的架构违规

背景：开发者在 HTTP Handler 中直接写 SQL，绕过了应用层。

评审意见：

// ❌ 违反依赖方向
func HandleCreateOrder(w http.ResponseWriter, r *http.Request) {
    db := mysql.Default() // Handler 直接依赖基础设施
    _, _ = db.ExecContext(r.Context(), "INSERT INTO orders ...")
}

处理流程：

1. 识别问题：违反 4.2.1 依赖方向检查
2. 上升讨论：在 PR 中标记 needs-architecture-review
3. 解决方案：
   • 定义应用层用例：PlaceOrderUseCase
   • 定义领域层端口：OrderRepository
   • Handler 只依赖应用层
4. 后续：将此类问题补充到团队的「评审反模式」文档

经验：当 PR 中出现架构级违规时，不要在代码层面修修补补，而是叫停并重新设计。短期看延迟了交付，长期避免了技术债累积。

4.1.4 何时进入哪一阶段：决策树

flowchart TD
  start([变更进入评审]) --> q1{是否改变系统边界<br/>或核心数据流?}
  q1 -->|是| arch[必须先过架构评审<br/>必要时更新 ADR]
  q1 -->|否| q2{是否改变聚合 / 事件契约<br/>或对外 API 语义?}
  q2 -->|是| design[设计评审 + 契约评审]
  q2 -->|否| code[代码评审 MR]
  arch --> design
  design --> code
  code --> q3{是否进入发布窗口<br/>或影响关键路径 SLO?}
  q3 -->|是| ship[上线前检查]
  q3 -->|否| merge[合并后持续观测]
  ship --> merge

4.2 架构评审阶段

适用时机：立项、新服务、新子域或大规模模块拆分。目标是在写大量代码之前，把分层、边界、一致性、读写特征与技术选型对齐。

4.2.1 分层结构检查

标准：是否明确定义 Domain / Application / Adapter / Infrastructure（或等价四层）？源代码依赖是否一律指向内层（Domain 为最内），外层通过接口向内依赖？

反例（违反依赖方向）：HTTP Handler 直接 import 具体 MySQL 驱动或 ORM 包，绕过应用服务与领域端口。

// BAD: handler depends on concrete DB package
import "github.com/org/repo/infra/mysql"

func HandlePlaceOrder(w http.ResponseWriter, r *http.Request) {
    db := mysql.Default()
    _, _ = db.ExecContext(r.Context(), "INSERT INTO orders ...")
}

合规方向：Handler 只依赖应用层用例；持久化通过 Repository 接口在领域或应用边界声明，由 Infra 实现。

// GOOD: handler -> application port -> domain; infra implements port
type PlaceOrderHandler struct {
    App *application.OrderService
}

func (h *PlaceOrderHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    cmd, err := decodePlaceOrder(r)
    if err != nil {
        http.Error(w, "bad request", http.StatusBadRequest)
        return
    }
    if err := h.App.PlaceOrder(r.Context(), cmd); err != nil {
        http.Error(w, err.Error(), http.StatusConflict)
        return
    }
    w.WriteHeader(http.StatusCreated)
}

评审追问：若团队暂时未引入完整四层，是否至少在包级约定 adapter 不得被 domain import，并在 CI 用 grep / 自定义 linter 守护？

4.2.2 限界上下文验证

标准：是否识别 核心域、支撑域、通用域？每个 BC 是否有清晰的 Ubiquitous Language 与对外契约（API / 事件），避免「一个大而全的领域模型」？

反例：订单子域与库存子域共用同一个 Product 结构体，字段含义在两边互相拉扯。

// BAD: one struct serves two contexts with conflicting meanings
type Product struct {
    ID           string
    Title        string
    PriceCent    int64 // pricing in order context
    WarehouseQty int   // stock in inventory context — coupling contexts
}

合规 sketch：不同 BC 使用不同模型与防腐层翻译；集成通过 API、消息或显式 ACL。

// GOOD: separate models + explicit mapping at boundary
type catalog.ProductView struct{ ID, Title string }

type ordering.OrderLine struct {
    ProductID     string
    UnitPrice     Money
    SnapshotTitle string
}

type inventory.StockUnit struct {
    SKU    string
    OnHand int
}

4.2.3 读写路径分析

标准：是否量化 读写比、延迟与一致性要求？读路径若存在重 JOIN、宽表、复杂筛选，是否考虑 独立读模型 / 投影，而不是全部堆在写模型上？

反例：在命令路径（下单）同步执行多表 JOIN 报表查询，拖慢写入尾延迟。

// BAD: command handler does heavy read for side UI
func (s *OrderService) PlaceOrder(ctx context.Context, cmd PlaceOrderCommand) error {
    _ = s.db.QueryRowContext(ctx, `SELECT ... heavy join for dashboard ...`)
    return s.persistOrder(ctx, cmd)
}

// GOOD: split; async projection or query DB
func (s *OrderService) PlaceOrder(ctx context.Context, cmd PlaceOrderCommand) error {
    if err := s.orders.Save(ctx, newOrderFrom(cmd)); err != nil {
        return err
    }
    return s.outbox.Publish(ctx, OrderPlaced{OrderID: cmd.IdempotencyKey})
}

评审追问：若读是写的两个数量级以上，独立读模型往往是经济解（与第 1 章 CQRS 呼应）。

4.2.4 技术选型审查

标准：存储与中间件是否与 访问模式 匹配（点查、范围扫、全文检索、图关系、流处理）？是否记录选型假设与回退方案？

反例：全文搜索需求用 MySQL LIKE '%keyword%' 扛流量，缺少倒排索引与相关性能力。

过度设计与 YAGNI（纳入技术选型同一关口）

标准：是否仅为已确认的变更点引入抽象？能否用更简单的模型先交付，再演化？

反例：典型 CRUD 后台强行上 DDD + CQRS + Event Sourcing 全家桶，团队无力维护投影与版本化事件。

评审追问：若去掉 Event Sourcing，业务是否仍成立？若答案是肯定的，则 ES 很可能是可选优化而非当前必需。CQRS 是否由观测到的读写不对称驱动，而不是由「流行架构标签」驱动？

4.3 设计评审阶段

适用时机：接口评审、领域模型评审、用例与事件清单冻结前。目标是让 战术设计（聚合、Repo、Command / Query、事件）与战略分层一致。

4.3.1 聚合边界检查

标准：一致性边界是否以聚合为单位设计？是否避免在单个事务中强行修改多个聚合根，除非有显式的领域规则与补偿策略？

反例：一个数据库事务内同时更新 Order 与 Inventory 聚合，绕过领域事件与最终一致性。

// BAD: one transaction mutates two aggregates directly
func SaveOrderAndDeductStock(ctx context.Context, tx *sql.Tx, o *Order, inv *Inventory) error {
    if err := persistOrder(tx, o); err != nil {
        return err
    }
    inv.Quantity -= o.LineItems[0].Qty
    return persistInventory(tx, inv)
}

聚合根识别补充：外部代码禁止绕过根直接改内部实体（如导出 []*OrderLine 被外部改 Qty）。若根方法数量爆炸，区分是聚合过大还是缺少领域服务。

实体与值对象（本小节一并核对）：实体有稳定标识、状态变更走受控方法；值对象不可变、按值相等；Money 等禁止提供可变 setter，对外构造函数保证合法组合。

4.3.2 命令查询分离验证

Command 设计

标准：命令是否表达 业务意图（PlaceOrder、CancelSubscription），而不是贫血 CRUD（UpdateOrder + 任意 map）？

// BAD: command is just a data bag
type UpdateOrderCommand struct {
    OrderID string
    Patch   map[string]any
}

// GOOD: explicit intent
type PlaceOrderCommand struct {
    CustomerID     string
    Items          []OrderItemDTO
    IdempotencyKey string
}

Repository（与命令 / 查询配套检查）：接口定义在领域层；方法名表达业务需要（FindActiveByCustomer）而非表驱动；复杂筛选优先归入 Query 侧，避免 Repository 万能方法膨胀。

Query 设计

标准：查询是否直接返回 DTO / 读模型，不强行加载完整领域图？是否避免在查询路径上触发写模型副作用？

// BAD: query returns rich aggregate for read-only UI
func (s *QueryService) OrderForUI(ctx context.Context, id string) (*domain.Order, error) {
    return s.orders.LoadFullGraph(ctx, id)
}

// GOOD: dedicated read DTO
type OrderSummaryDTO struct {
    OrderID   string
    Status    string
    TotalCent int64
    PlacedAt  time.Time
}

4.3.3 领域事件设计

标准：关键业务状态变更是否发布 领域事件？命名是否使用 过去式（OrderPlaced、PaymentCaptured）并携带必要上下文（版本、发生时间）？

// BAD: imperative name
type PlaceOrder struct{ OrderID string }

// GOOD: past tense, domain vocabulary
type OrderPlaced struct {
    OrderID    string
    OccurredAt time.Time
    Version    int
}

4.3.4 模式选型审查

详设阶段可快速对照下表，避免「每个地方都 if-else」或「每个地方都上框架」。

反例：全系统统一 RuleEngine.Execute(ctx, ruleSetID, facts)，但规则集无人版本化与评审，线上等于「可执行的配置漂移」。

合规：规则变更走 PR + 审计 + 影子流量；核心不变量仍保留在代码与单测中，引擎只编排可变的参数化策略。

4.4 代码评审阶段

适用时机：每次合并请求。把设计约束落到 Go 代码的可观察性质上。

4.4.1 SOLID 原则检查

对每一项，用「一句检查问句」把握核心；争议点再用第 1 章分层与端口对齐。

DIP 延伸——包级依赖方向：domain 不 import adapter / infra；application 不直接引用 HTTP、ORM、消息 SDK；无循环依赖（必要时提取 domain/sharedkernel 最小类型）。go list -deps 或 IDE 依赖图可抽查。

LSP 反例 sketch：

// BAD: implementation surprises caller
type NoOpPaymentGateway struct{}
func (NoOpPaymentGateway) Charge(ctx context.Context, amount int64) error {
    return nil // silently skips payment
}

4.4.2 函数质量审查

gocyclo -over 10 ./...

// GOOD: named steps keep orchestration readable
func (h *PlaceOrderHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    if err := h.ensureAuth(ctx, r); err != nil {
        h.writeErr(w, err)
        return
    }
    cmd, err := h.decode(r)
    if err != nil {
        h.writeErr(w, err)
        return
    }
    if err := h.app.PlaceOrder(ctx, cmd); err != nil {
        h.writeErr(w, err)
        return
    }
    w.WriteHeader(http.StatusCreated)
}

评审追问：context.Context 是否作为 第一个参数 传递 I/O 边界函数，而不是塞进结构体字段隐式携带？

4.4.3 命名与可读性

1. 变量 / 函数名反映业务术语：名称来自 Ubiquitous Language，而非数据库列名机械翻译。
2. 团队内一致：同一概念只有一个词（Customer vs User 要治理）。
3. 避免技术术语代替业务术语：不用 SetStatus(1)，而用 MarkShipped()。

// BAD: magic status
func (o *Order) SetStatus(s int) { o.status = s }

// GOOD: business verb
func (o *Order) MarkShipped(at time.Time) error {
    if o.status != StatusPaid {
        return ErrInvalidStateTransition
    }
    o.status = StatusShipped
    o.shippedAt = at
    return nil
}

4.4.4 错误处理验证

1. 禁止静默忽略错误：是否存在 _ = xxx 或空白 if err != nil { }？
2. 错误 wrap 携带上下文：跨层 fmt.Errorf("place order: %w", err)。
3. 区分业务错误与系统错误：调用方能否区分「库存不足」与「应重试的基础设施错误」？

var ErrOutOfStock = errors.New("out of stock")

func (s *InventoryService) Reserve(ctx context.Context, sku string, qty int) error {
    if qty > available(sku) {
        return fmt.Errorf("reserve %s: %w", sku, ErrOutOfStock)
    }
    return nil
}

DDD 战术与聚合不变量（与错误语义一并核对）

聚合不变量 sketch：

func (o *Order) AddLine(sku string, qty int, unitCent int64) error {
    if qty <= 0 {
        return ErrInvalidQty
    }
    if o.status != StatusDraft {
        return ErrOrderNotEditable
    }
    lineTotal := unitCent * int64(qty)
    if lineTotal < 0 {
        return ErrOverflow
    }
    o.lines = append(o.lines, OrderLine{SKU: sku, Qty: qty, UnitCent: unitCent})
    o.totalCent += lineTotal
    return nil
}

4.5 上线前检查

适用时机：发布分支、灰度前、重大重构合并前。与功能完成度无关的「生产就绪」项在此收敛。

4.5.1 性能与并发

性能：

• 关键路径是否有 benchmark 或压测基线？
• 是否关注 alloc/op、GC 停顿、锁竞争（mutex profile）？
• 异步路径是否避免无界队列导致内存膨胀？

func BenchmarkPlaceOrder(b *testing.B) {
    b.ReportAllocs()
    for i := 0; i < b.N; i++ {
        // exercise hot path
    }
}

并发安全：

// BAD: unsynchronized map writes
var cache = map[string]int{}
func Set(k string, v int) { go func() { cache[k] = v }() }

// GOOD: mutex or single-owner goroutine
type SafeCache struct {
    mu sync.RWMutex
    m  map[string]int
}

4.5.2 可观测性

标准：metrics（RED / USE）、trace（关键 span）、结构化日志（request_id、order_id 等关联字段）。

logger.Info("order_placed",
    "order_id", orderID,
    "customer_id", customerID,
    "duration_ms", elapsed.Milliseconds(),
)

4.5.3 测试覆盖

标准：核心业务规则覆盖率按团队约定（例如 > 80%）；集成测试覆盖仓储、消息、外部 HTTP 的 fake / 容器。

func TestPlaceOrder_OutOfStock(t *testing.T) {
    t.Parallel()
    // arrange: 0 stock -> expect ErrOutOfStock
}

4.5.4 回滚方案

标准：feature flag 或配置开关；数据库迁移可回滚或具备向前兼容的双写 / 双读；事件 schema 向后兼容或双写新字段。

回滚方案检查清单

Feature Flag 实践

// 使用 Feature Flag 控制新功能
package order

import "context"

type FeatureFlags interface {
    IsEnabled(ctx context.Context, feature string) bool
}

func (s *OrderService) PlaceOrder(ctx context.Context, cmd PlaceOrderCommand) error {
    // 旧逻辑
    if err := s.validateBasic(cmd); err != nil {
        return err
    }
    
    // 新功能：风控检查（可通过 Feature Flag 关闭）
    if s.flags.IsEnabled(ctx, "order.fraud_detection") {
        if err := s.fraudDetector.Check(ctx, cmd); err != nil {
            return err
        }
    }
    
    return s.repo.Save(ctx, newOrderFrom(cmd))
}

收益：

• 新功能上线后发现问题，可立即关闭 Feature Flag，无需回滚代码
• 灰度发布：先对 5% 用户开启，观察指标后再逐步放量
• A/B 测试：对不同用户群开启不同策略，对比效果

文档与运维：架构变更（新 BC、事件契约、SLA）同步到 README / ADR / 运维手册；On-call 知道降级、重放消息、解读关键告警；新人能仅凭文档拉起本地依赖（docker-compose / make 目标）。

运维文档模板：

## 服务运维手册

### 关键告警
- `order_create_latency_p99 > 500ms`：订单创建延迟过高
  - **可能原因**：数据库慢查询、库存服务超时
  - **处理步骤**：
    1. 查看 Grafana 面板确认瓶颈（DB/库存/计价）
    2. 若库存服务超时，执行降级：`kubectl set env deployment/order INVENTORY_FALLBACK=true`
    3. 通知库存团队排查

### 降级开关
- `INVENTORY_FALLBACK=true`：库存查询降级，使用本地缓存
- `FRAUD_DETECTION=false`：关闭风控检查（紧急情况）
- `PROMOTION_ENABLED=false`：关闭营销试算（性能问题）

### 回滚流程
1. 确认回滚目标版本：`kubectl rollout history deployment/order`
2. 执行回滚：`kubectl rollout undo deployment/order --to-revision=N`
3. 观察监控：关注错误率、延迟、上下游调用
4. 数据库回滚（如需要）：执行 DOWN 脚本

4.6 本章小结

4.6.1 全阶段总览表（评审清单）

4.6.2 MR 描述区模板（可复制）

## Self review (author)
- [ ] 4.4 SOLID: 新类型职责与扩展点合理
- [ ] 4.4 函数长度 / 复杂度 / 嵌套 / 参数个数
- [ ] 4.4 命名与 glossary 一致
- [ ] 4.4 错误 wrap，无静默 `_ = err`
- [ ] 4.4 依赖方向与 DDD 战术（不变量、VO）

## Release readiness (if applicable)
- [ ] 4.5 Benchmark 或压测链接
- [ ] 4.5 并发 / race 检查
- [ ] 4.5 Metrics + logs + traces
- [ ] 4.5 核心规则测试与集成测试
- [ ] 4.5 回滚 / 迁移 / 双写方案
- [ ] 4.5 文档 / ADR 更新

## Design links
- ADR / RFC: ...

4.6.3 实战案例与反模式

案例 A：库存预占接口「顺手」改了聚合边界（设计评审失效）

背景：结算服务在「创单前预占」需求中，直接在订单聚合的事务内更新库存行，图省事。

症状：大促锁竞争升高；库存与订单发布节奏耦合，回滚困难。

处理：设计评审阶段强制改为 OrderPlaced / ReserveStockRequested 事件驱动或显式 Saga；代码评审拦截「双聚合同一事务」。

案例 B：营销规则 JSON 线上漂移（模式选型 + 运维失守）

背景：规则引擎读取未版本化的 JSON，运营后台可直接保存到生产。

症状：线上行为与测试环境不一致，难以复盘。

处理：规则集 版本号 + PR 审核 + 审计日志；核心不变量仍在单测与代码中；影子流量验证。

案例 C：Handler 直连 DB（架构评审后置到 PR）

背景：原型代码直接进入主干，后续 MR 只在 SQL 层修修补补。

症状：领域规则散落在 SQL；单测必须起库。

处理：上升架构评审，引入 端口 + 用例；本 MR 仅允许「垂直切片」式重构到合规结构，不接受继续堆 SQL。

案例 D：缺少性能测试导致的线上故障

背景：订单服务上线了「批量取消」功能，代码评审通过，但未做性能测试。

线上故障：

• 运营同学一次性取消 5000 个订单
• 服务在循环中逐个发送取消事件到 Kafka，耗时 30 秒
• 期间所有订单查询请求超时（共享同一个 goroutine 池）
• 用户投诉量激增

根因分析：

• 代码评审通过：功能逻辑正确，无明显bug
• 缺失上线前检查：没有性能测试，没有评估「批量场景下的资源占用」

改进方案：

1. 补充 4.5.1 性能检查：批量操作必须有 Benchmark
2. 异步化：批量取消改为后台任务，分批处理（每批 100 个）
3. 限流：批量接口加频控，防止运营误操作

经验：代码评审通过≠生产就绪。上线前检查（4.5）是最后一道防线，必须覆盖性能、并发、可观测性。

案例 E：聚合不变量在 PR 中被破坏

背景：订单聚合有不变量「总价 = 各明细之和」，某次 PR 为了修复 bug，直接修改了 TotalAmount 字段。

代码变更：

// BAD: 直接修改总价，破坏不变量
func (o *Order) ApplyDiscount(amount int64) {
    o.TotalAmount -= amount // ❌ 绕过了明细，破坏一致性
}

后果：

• 订单详情页显示的小计与总价不一致
• 财务对账时发现差异，追溯到这次变更

评审反思：

• 设计评审阶段应明确聚合不变量（4.3.1）
• 代码评审阶段应检查是否有直接修改聚合字段的行为
• 测试应覆盖不变量（如 assert(order.Total == sum(order.Lines))）

正确方案：

// GOOD: 通过明细修改，自动更新总价
func (o *Order) ApplyDiscountToLine(lineIndex int, discountAmount int64) error {
    if lineIndex >= len(o.Lines) {
        return ErrInvalidLineIndex
    }
    o.Lines[lineIndex].UnitPrice -= discountAmount
    o.recalculateTotal() // 重新计算总价，保证不变量
    return nil
}

func (o *Order) recalculateTotal() {
    total := int64(0)
    for _, line := range o.Lines {
        total += line.UnitPrice * int64(line.Qty)
    }
    o.TotalAmount = total
}

案例 F：缺少回滚方案的数据库迁移

背景：库存服务需要新增字段 reserved_qty，开发者提交了 PR 包含数据库迁移脚本。

问题：

• 只有 UP 脚本，没有 DOWN 脚本（无法回滚）
• 没有双写策略：新代码直接依赖新字段，回滚时会报错

线上故障：

• 新版本上线后发现性能问题，需要回滚
• 回滚代码后，服务启动失败（读取不存在的字段）
• 被迫紧急修复：手动删除字段、重新上线旧版本

改进方案（4.5.4 回滚方案）：

1. 三阶段迁移：
   • 阶段 1：加字段，代码双写（写新旧两个字段），读旧字段
   • 阶段 2：代码切换为读新字段
   • 阶段 3：删除旧字段
2. 每阶段可独立回滚：任何一步出问题都能回到上一阶段
3. UP/DOWN 脚本齐全：迁移工具（如 migrate）强制要求两个方向

评审清单补充：

• 数据库迁移是否有 DOWN 脚本？
• 新字段是否通过双写 / 双读策略引入？
• 回滚后服务是否仍能正常启动？

4.6.4 按角色的最小阅读路径

4.6.5 核心要点

系统化的 Code Review 不是挑剔，而是把重构前移到成本最低的阶段。按 架构 → 设计 → 代码 → 上线前 四段清单推进，并与第 1 章方法论、第 2 章战略设计、第 3 章战术实现交叉引用，团队可以在一致语言下讨论分层、边界与实现细节。建议将 4.6.1 嵌入 MR 模板，并在复盘时根据失效案例增补第 21 条——最好的 Checklist 永远是活文档。

导航：返回目录 | 上一章：第5章 | 书籍主页 | 下一章：第7章

导航：书籍主页 | 完整目录 | 上一章：第6章 | 下一章：第8章

第7章 电商系统全景图

本章定位：在读完第一部分的方法论之后，进入第二部分「电商核心系统设计」之前，用一张可落地的全景图把业务能力、应用系统、数据资产与技术基础设施对齐到同一坐标系。后续第 8 章至第 16 章将沿本章划定的边界逐域深入；第 4 章已经从方法论层面讨论了跨系统集成与一致性模式。

阅读建议：若你已熟悉 DDD 战略术语，可快速浏览 5.2 后进入 5.1 的图示；若你更习惯从接口与数据表入手，建议从 5.1.3 数据架构读起，再回到 5.1.1 校正业务语义。无论哪种路径，都请至少完成 5.4 的三条时序走读，因为后续各章的「集成小节」默认你已经知道主链路的参与者与先后次序。

本章产出物（可用于团队对齐）：

1. 一页 限界上下文图（5.1.1）贴在内网架构 wiki。
2. 一张 服务依赖图（5.1.2）导入架构治理工具（如 Backstage / 内部 CMDB）。
3. 一份 主数据清单（5.1.3 表格）作为数据 Owner 会议的输入。
4. 一套 集成模式评审话术（5.3）写进 RFC 模板。
5. 一张 十二系统职责表（5.5.1）作为新人 Onboarding 必读。

5.1 系统全景架构

中大型电商平台的架构讨论，如果只停留在「微服务拆分清单」，很容易失去业务语义；如果只停留在「业务功能列表」，又难以指导工程依赖与数据落点。实践中常用 EA（企业架构）+ 4A 的多视角方法并行：

下面四节分别给出图示与解读要点。图示刻意与后续各章的术语保持一致，便于你在阅读第 7 章至第 15 章时「对照地图」。

与博客文章《电商系统设计（一）：全景概览与领域划分》的关系：原文从 EA + 4A 视角给出了高质量的全景素材与系列文章索引；本书第 5 章在此基础上做了三件事——按书籍目录重排小节编号；把 C 端读路径（搜索、购物车）与结算编排显式画入应用架构；把十二个核心系统与第 7 章至第 15 章的章节锚点一一对齐，便于纸质阅读时的交叉引用。若你在网上已读过该文，可把本章视为其书籍化、边界化、评审化的增强版。

术语对照（避免口语歧义）：

从单体到分布式的认知迁移：在单体时代，模块边界靠包名与 Code Review 维持；在分布式时代，网络边界会放大设计缺陷——原本一次函数调用的地方，变成了超时、重试与部分失败。因此全景章的价值，不在于「数有多少个微服务」，而在于为每个跨边界调用预先分配 一致性语义、超时预算与观测标签。当你在第 14 章阅读订单状态机时，应能指出：某次迁移对应 5.4.2 中的哪一步、失败时由谁补偿。

5.1.1 业务架构（DDD 视角）

从 DDD 战略设计看，电商平台的业务能力应被组织为一组限界上下文（Bounded Context）：每个上下文内部有独立的通用语言与生命周期；上下文之间通过显式关系（客户方 / 供应方、防腐层、发布语言等）协作。下图用「限界上下文 + 域分类」表达业务架构，颜色区分核心域、支撑域、通用域（分类标准与第 2 章 2.5 节一致，此处侧重系统级映射）。

flowchart TB
  subgraph Core["核心域（Core Domain）"]
    BC_Order["限界上下文：订单<br/>契约：订单号、状态机、履约编排"]
    BC_Pay["限界上下文：支付<br/>契约：支付单、渠道、清结算"]
    BC_Checkout["限界上下文：结算<br/>契约：试算、预占、拆单预览"]
    BC_Cart["限界上下文：购物车<br/>契约：行项目、会话合并"]
  end

  subgraph Support["支撑域（Supporting Domain）"]
    BC_Product["限界上下文：商品中心"]
    BC_Inv["限界上下文：库存"]
    BC_Price["限界上下文：计价"]
    BC_Mkt["限界上下文：营销"]
    BC_List["限界上下文：商品上架"]
    BC_Ops["限界上下文：B 端运营"]
    BC_Life["限界上下文：生命周期与供给治理"]
  end

  subgraph Generic["通用域（Generic Domain）"]
    BC_Search["限界上下文：搜索与导购"]
    BC_User["限界上下文：用户与会员（外采/标准能力）"]
    BC_Msg["限界上下文：消息通知（外采/标准能力）"]
  end

  BC_Cart --> BC_Checkout
  BC_Checkout --> BC_Order
  BC_Order --> BC_Pay

  BC_Checkout -.->|试算/ Hydrate| BC_Price
  BC_Checkout -.->|预占| BC_Inv
  BC_Checkout -.->|券与活动校验| BC_Mkt

  BC_Order -.->|快照与金额确认| BC_Price
  BC_Order -.->|库存确认/回退| BC_Inv
  BC_Order -.->|营销锁定与扣减| BC_Mkt
  BC_Order -.->|商品快照| BC_Product

  BC_List --> BC_Product
  BC_List --> BC_Inv
  BC_List --> BC_Price
  BC_Ops --> BC_Product
  BC_Ops --> BC_Inv
  BC_Ops --> BC_Mkt
  BC_Ops --> BC_Price
  BC_Life --> BC_Product
  BC_Life --> BC_List

  BC_Search -.->|发现与列表| BC_Product
  BC_User -.->|身份与权益| BC_Order
  BC_Msg -.->|异步触达| BC_Order

读图要点：

1. 核心域集中了「钱与承诺」相关的上下文：购物车暂存购买意图，结算把意图推进为可支付的约束集合（价格、库存、优惠），订单把承诺持久化为合同，支付完成资金侧的闭环。
2. 支撑域提供可售性、可算价、可营销、可供给四类「规则与主数据」能力；它们高度影响交易，但行业模式相对可参照。
3. 通用域中的搜索本书会深入（第 12 章），因其在工程上与商品、计价、库存的 Hydrate 编排强耦合；用户与消息等更常采购标准方案，在全景中保留接口位即可。

上下文映射（与第 2 章衔接）：上图中实线箭头多表示「客户方依赖供应方」的下游调用关系；虚线表示「通过发布语言（Published Language）或 ACL 防腐」的弱耦合。落地时建议显式标出：

• 供应方（Upstream）：商品中心对「商品快照 ID」、计价系统对「价格快照版本」、库存对「预占凭证」拥有定义权。
• 客户方（Downstream）：订单与结算消费上述契约，但不应要求供应方暴露内部表结构。
• 防腐层（ACL）：对接供应商、旧单体或外采营销引擎时，把外部模型挡在边界之外，避免污染核心域通用语言。

答辩提示：业务架构图的表述模板已统一收录到附录B。

5.1.2 应用架构（微服务视角）

应用架构关注可部署单元之间的依赖。原则是：依赖方向自上而下、由稳定侧指向易变侧，避免出现「基础数据服务回调订单服务」这类环。下图在博客原文分层思路上，补全 C 端读路径（搜索、购物车）与结算编排，并标注后续章节编号，便于索引。

flowchart TB
  subgraph L0["接入与 BFF"]
    GW[API Gateway / BFF]
  end

  subgraph L_read["读路径与暂存"]
    SearchSvc["搜索与导购服务<br/>第12章"]
    CartSvc["购物车服务<br/>第13章"]
  end

  subgraph L_data["主数据与规则基座"]
    ProductSvc["商品中心<br/>第7章"]
    InvSvc["库存系统<br/>第8章"]
    MktSvc["营销系统<br/>第9章"]
    PriceSvc["计价系统<br/>第11章"]
  end

  subgraph L_trade["交易编排与资金"]
    CheckoutSvc["结算编排服务<br/>第13章"]
    OrderSvc["订单系统<br/>第14章"]
    PaySvc["支付系统<br/>第15章"]
  end

  subgraph L_supply["供给与运营"]
    ListingSvc["商品上架<br/>第10章"]
    OpsSvc["供给与运营管理<br/>第10章"]
    LifeSvc["生命周期协调<br/>第10章"]
  end

  GW --> SearchSvc
  GW --> CartSvc
  GW --> CheckoutSvc
  GW --> OrderSvc
  GW --> PaySvc
  GW --> ListingSvc
  GW --> OpsSvc

  SearchSvc --> ProductSvc
  SearchSvc --> InvSvc
  SearchSvc --> PriceSvc
  CartSvc --> ProductSvc

  CheckoutSvc --> PriceSvc
  CheckoutSvc --> InvSvc
  CheckoutSvc --> MktSvc
  CheckoutSvc --> OrderSvc

  OrderSvc --> ProductSvc
  OrderSvc --> InvSvc
  OrderSvc --> MktSvc
  OrderSvc --> PriceSvc
  OrderSvc --> PaySvc

  ListingSvc --> ProductSvc
  ListingSvc --> InvSvc
  ListingSvc --> PriceSvc
  OpsSvc --> ProductSvc
  OpsSvc --> InvSvc
  OpsSvc --> MktSvc
  OpsSvc --> PriceSvc
  LifeSvc --> ProductSvc
  LifeSvc --> ListingSvc

依赖解读：

• 商品中心是多数读路径与订单快照的事实来源（System of Record for catalog）；库存、计价、营销在各自上下文内维护规则，但在创单链路上被订单编排调用。
• 结算服务常实现为独立部署的「长事务 / Saga 编排器」，在应用层与购物车解耦：购物车偏会话与展示，结算偏资源锁定与一致性门槛（详见第 13 章）。
• 上架、运营、生命周期在应用层可能合并为一个「供给平台」团队维护的多个服务，逻辑上仍建议按限界上下文拆分数据与发布节奏（第 10 章展开）。

典型调用链（便于与 5.4 对照）：

循环依赖治理：若发现「商品中心回调订单」一类需求，优先改为事件订阅或查询倒置（由订单侧拉取快照），而不是在数据层打开反向通道。

5.1.3 数据架构

数据架构回答三件事：主数据放哪、派生数据如何构建、事件与缓存如何对齐。下图描述一条典型的「写主库、异步投影、读多路」路径，与第 1 章 CQRS 与 Outbox 思路衔接。

flowchart LR
  subgraph Writers["写入侧（Command Path）"]
    SVC_W[业务服务<br/>订单/商品/库存等]
    DB[(MySQL 集群<br/>事务边界内)]
    Outbox[(Outbox 表<br/>同库事务)]
  end

  subgraph Bus["集成与解耦"]
    MQ[Kafka / Pulsar<br/>领域事件总线]
    CDC[CDC 可选<br/>Binlog 流]
  end

  subgraph Readers["读取侧（Query Path）"]
    ES[(Elasticsearch<br/>搜索索引)]
    Redis[(Redis<br/>库存热点/购物车)]
    DW[(数仓 / OLAP<br/>分析投影)]
  end

  SVC_W -->|本地事务| DB
  SVC_W -->|同事务写入| Outbox
  Outbox -->|Relay| MQ
  DB -.->|可选| CDC
  MQ -->|商品变更订阅| ES
  MQ -->|库存变更| Redis
  MQ -->|订单事实| DW
  CDC --> ES

落地要点：

1. 订单、支付、商品主档等强一致实体以 MySQL（或同类）为权威存储；跨聚合协作优先 Outbox + 消息（见第 1 章 1.3.9），避免「双写」在故障时无法对账。
2. 搜索索引、推荐特征、报表属于派生视图，允许最终一致；延迟由业务容忍度与补偿任务共同约束。
3. 库存常见「Redis 扛热点 + MySQL 审计」的双存储形态，必须单写者（Single Writer）与周期对账（第 8 章）。

主数据与派生数据清单（评审用）：

数据所有权一句话：谁对「业务不变量」负责，谁就拥有该数据的写入 API；其余路径只能投影或引用。

离线数仓与实时数仓的边界：订单与支付事件进入数仓后，用于分析与风控建模，不得反向写回在线交易库作为业务依据；若运营需要「实时看板」，应通过专用 OLAP 或流式聚合服务读取消息总线，而不是直接查询订单主库拖垮 P99。若确需运营干预线上数据，应走带审批的正式 API 与审计日志，而不是「数仓导表回灌」。这类约束也是第 4 章上线前检查中「数据变更路径」的必审项。

5.1.4 技术架构

技术架构把应用服务映射到运行时与平台能力：流量入口、服务通信、数据存储、异步集成、可观测性与零信任边界。下图为参考拓扑，实际规模会按环境裁剪。

flowchart TB
  subgraph Edge["边缘与接入"]
    CDN[CDN / WAF]
    LB[负载均衡]
    GW2[API Gateway<br/>鉴权 限流 mTLS]
  end

  subgraph Runtime["服务运行时"]
    SVC_POD[Kubernetes Pods<br/>Go 微服务]
    Mesh[可选 Service Mesh<br/>重试 熔断 流量镜像]
  end

  subgraph Data["数据与中间件"]
    MY2[(MySQL)]
    RD2[(Redis)]
    ES2[(Elasticsearch)]
    KF2[Kafka]
  end

  subgraph Platform["平台能力"]
    REG[服务注册发现]
    CFG[配置中心]
    SEC[密钥管理]
    LOG[日志聚合]
    MET[指标与告警]
    TRACE[分布式追踪]
  end

  CDN --> LB --> GW2 --> SVC_POD
  GW2 --> Mesh
  Mesh --> SVC_POD
  SVC_POD --> MY2
  SVC_POD --> RD2
  SVC_POD --> ES2
  SVC_POD --> KF2
  SVC_POD --> REG
  SVC_POD --> CFG
  SVC_POD --> SEC
  SVC_POD --> LOG
  SVC_POD --> MET
  SVC_POD --> TRACE

与后续章节的关系：第 7 章至第 15 章主要在应用与数据架构层面展开；当你评估「是否需要 Service Mesh」「Kafka 分区策略」时，应回到本节检查观测性是否先于网格、消息是否已成为事实管道等平台前提。

非功能需求（NFR）与全景的对应关系：

• 可用性：网关限流与服务熔断保护核心交易路径；搜索与报表故障不得拖垮创单。
• 性能：读路径大量使用缓存与索引；写路径控制扇出深度，结算页试算可合并批量 RPC（第 13 章）。
• 安全：密钥不进仓库；支付回调验签在独立模块；内部服务 mTLS 或网络策略隔离。
• 可观测性：以 trace_id 贯穿网关、结算、订单、支付；对 Saga 每一步有结构化日志与业务指标（转化率、预占失败率）。
• 合规与审计：订单与支付字段变更可追溯；营销补贴与实付金额可对账。

渐进式演进建议：早期可用「单体 + 清晰包边界」模拟上图拓扑；当团队规模与发布冲突上升时，再按限界上下文拆出独立部署单元，避免「先拆微服务、后补边界」的高成本路径。

容灾与多活（点到为止）：技术架构图未展开「单元化 / 多 Region」，但在全景阶段应预留认知：订单与支付数据往往要求 Region 内强一致 + 跨 Region 异步复制；搜索索引与购物车会话更适合 就近读取。若在多活场景下仍沿用单 Region 的强同步调用链，容灾切换时容易遭遇「依赖未起、核心不可用」；因此第 4 章在谈 Saga 时也会隐含「地理边界上的超时预算」问题。

5.2 核心域与支撑域

DDD 强调：不是所有子域都值得同等投入。战略设计的产出之一，是一张「域分类表」，用于指导组织排兵布阵与技术选型（自研 / 定制 / 采购）。

5.2.1 核心域：交易与支付

核心域承载差异化与最高业务风险，典型包括：

本书将订单、支付、购物车与结算作为交易链路主轴（第 14 章至第 16 章），并在第 4 章从一致性模式上把它们串成可复用的集成语言。

投资与组织策略（与第 2 章 2.5 节对照）：

常见误区：把「购物车」当成纯前端本地存储。实际上购物车是高并发有状态服务，涉及登录合并、库存展示与营销提示，与结算的边界必须在 API 契约上划清（第 13 章）。

5.2.2 支撑域：商品、库存、营销、定价与供给

支撑域是核心域的「地基」：没有可售商品与可算价格，订单与支付无从谈起；没有库存与营销约束，结算编排也会失去输入。

第 7 章至第 11 章分别深入各支撑系统；第 10 章从组织上常合并「上架 + 运营 + 生命周期」，但限界上下文仍建议在模型层分开，以避免「一个上帝服务」拖垮发布节奏。

为什么支撑域也值得深度自研：支撑域虽非「卖点」，却是故障的放大器。例如库存超卖、计价错误、营销叠加漏洞，都会在订单层集中爆发。架构评审中常问：「若该支撑域宕机 30 分钟，核心域能否优雅降级？」——答案决定缓存策略、兜底价、降级开关的设计深度。

与核心域的集成契约（摘要）：

• 商品中心输出：快照 ID、类目路径、禁售标签。
• 库存输出：预占凭证、可售数量区间、渠道库存类型（第 8 章二维模型）。
• 营销输出：可叠加规则集、锁定 token、预算占用凭证。
• 计价输出：试算结果哈希或版本号，供创单时校验「结算页所见即所得」。

5.2.3 通用域：用户、搜索、消息等

通用域标准化程度高，通常采购或薄封装即可；例外是搜索与导购：虽然模式成熟，但在中大型平台中与商品、价格、库存的实时编排深度交织，本书第 12 章单独成章。

反模式提醒：把「通用域 = 可以随便写」等同于降低质量要求。正确做法是：减少自研范围，但不降低 SLO 与可观测性要求。

关于搜索域的「重要性升级」：从严格 DDD 分类看，搜索常被归为通用域（技术方案成熟）；但从业务入口与 GMV 贡献看，它又接近核心体验。本书采取工程折中：在域分类上保留通用属性，在章节权重上按核心链路对待（第 12 章），因其失败模式会直接影响列表价、库存态与活动标签的呈现。

用户与消息：用户域提供主体标识与会员等级，消息域消费订单与支付事件做触达。二者与交易链的耦合主要是读侧鉴权与异步通知，应避免在下单同步路径强依赖外部推送可用性。

5.3 系统间的交互模式

跨系统协作可归纳为三类：同步 RPC、异步事件、数据同步（批式或流式）。它们不是互斥的，同一链路常组合使用；选型取决于一致性语义、延迟上限与故障隔离需求。

5.3.1 同步调用

典型场景：结算页试算、创单前库存确认、支付创建。特征是调用方阻塞等待结果，语义接近「读己之写」或强校验。

优点：实现直观、调试路径短。
风险：级联故障、线程占用、超时风暴；需配合超时、重试、熔断、舱壁与清晰的错误契约（第 4 章相关小节）。

工程要点（Go 服务常见落地）：为出站 RPC 设置上下文超时与每依赖独立超时；重试仅对幂等读或带幂等键的写开放；对核心交易路径实施舱壁线程池或并发上限，避免试算扇出把进程拖死。返回错误时区分业务可预期错误（如券不可用）与基础设施错误（如超时），前者映射为 4xx 与明确 code，后者触发降级与告警。

电商实例：结算页打开时，编排服务并行调用计价、库存、营销；只要任一关键依赖超时，应整体返回「请稍后重试」或切换至缓存兜底价 + 延迟锁券策略，而不是无限等待（第 13 章详述降级矩阵）。

5.3.2 异步事件

典型场景：订单已创建、支付已成功、商品变更。特征是最终一致，通过消息中间件解耦峰值与异构消费者。

优点：吞吐与弹性好，天然适合多订阅者（搜索索引、数仓、营销统计）。
风险：重复消息、乱序、滞后；需幂等消费、版本号、可补偿流程（第 1 章 Outbox、第 4 章事件驱动）。

工程要点：事件体应携带聚合 ID、版本号、发生时间、幂等键；消费者使用「处理表」或唯一索引实现 at-least-once 下的精确一次业务效果。对支付成功类事件，建议以支付系统 Outbox 为唯一发布源，避免订单与支付双写双发导致重复记账。

电商实例：ProductChanged 发布后，搜索索引、推荐特征、运营看板可能各自消费；它们失败不应阻塞商品主事务，但需要通过死信队列与可观测面板暴露积压，防止索引长期陈旧引发客诉。

5.3.3 数据同步

典型场景：搜索索引重建、报表 T+1、跨机房冗余。实现路径包括定时批处理、CDC、双写（谨慎）。

优点：对在线路径侵入小。
风险：延迟与对账；CDC 需处理 schema 演进与回放。

工程要点：优先 CDC + 消息 或 Outbox 形成可回放管道，避免业务代码里手写双写。若必须双写，应配置对账任务比较主从差异并自动修复。搜索全量重建应走蓝绿索引别名切换，避免重建期间查询抖动。

同步 / 异步 / 数据同步对比总览：三者回答的是不同维度的问题——同步保障「此刻的正确」，异步保障「吞吐与解耦」，数据同步保障「派生视图的规模构建」。架构评审可用下图作开场白板，再落到具体接口与 SLA。

flowchart TB
  subgraph Sync["同步 RPC（Request/Response）"]
    S1["一致性：强一致读 / 即时校验"]
    S2["延迟：毫秒级 P99 约束"]
    S3["故障：调用链扩散 → 需熔断舱壁"]
    S4["典型：试算 创单校验 支付创建"]
  end

  subgraph Async["异步事件（Message/Event）"]
    A1["一致性：最终一致 + 补偿"]
    A2["延迟：秒级可接受 / 削峰"]
    A3["故障：隔离好 → 消费者独立重试"]
    A4["典型：订单已支付 商品变更广播"]
  end

  subgraph DataSync["数据同步（Batch / CDC）"]
    D1["一致性：以快照或日志为准"]
    D2["延迟：分钟级 ~ 小时级"]
    D3["故障：可回放 / 对账修复"]
    D4["典型：搜索索引 数仓 跨库复制"]
  end

  Q["选型提问：调用方能否接受短暂不一致？失败能否补偿？是否必须占用用户请求线程？"]
  Q --> Sync
  Q --> Async
  Q --> DataSync

Go 侧抽象示例：在应用层用接口表达三种出口，避免在业务代码里散落 HTTP 客户端细节。

package integration

import "context"

// SyncPricing 同步计价试算（RPC）：强一致读、可返回明确业务错误码。
type SyncPricing interface {
	QuoteCheckout(ctx context.Context, req CheckoutQuoteRequest) (*CheckoutQuoteResult, error)
}

// AsyncPublisher 异步领域事件（Outbox relay 之后投递）。
type AsyncPublisher interface {
	PublishOrderPaid(ctx context.Context, evt OrderPaidEvent) error
}

// ProductIndexProjector 数据同步投影（可由 Kafka consumer 或 CDC worker 实现）。
type ProductIndexProjector interface {
	ApplyProductChanged(ctx context.Context, change ProductChangedLog) error
}

结算编排中的幂等键（与第 13、14 章衔接）：同一用户多次点击「提交订单」时，应以客户端或服务端生成的 idempotency_key 贯穿结算会话与创单请求，避免重复扣减与重复订单。下面展示在 Go 中的最小承载方式（字段名可按公司规范调整）：

package checkout

import "time"

// CheckoutSession 表示结算页的一次编排会话。
type CheckoutSession struct {
	SessionID        string
	UserID           string
	IdempotencyKey   string
	QuoteVersion     int64
	ExpiresAt        time.Time
}

5.4 数据流转全景

本节用三条完整时序链把 5.1 至 5.3 的静态结构串成动态故事线。图中参与者命名与后续章节标题一致，便于对照。

三条链路的共同模式（背诵版）：每条链路都同时存在 同步确认（保证局部不变量）与 异步传播（放大读模型与运营可见性）两类步骤。设计时请先标出「哪一步失败会导致资损或客诉」——这些步骤应尽量落入短事务 + 明确幂等键；其余步骤尽量推出消息总线。另一个共同点是 Hydrate：搜索与列表在 C 端读路径上，往往需要二次拉取商品、价格、库存以修补索引延迟；这与订单创单时的「快照固化」是同一思想的不同形态——用显式版本与快照对抗时间差。

与大促场景的关系：商品流在大促前表现为「批量改价、改库存、改活动」的洪峰；订单流在秒杀瞬间表现为「创单与扣减」的尖峰；支付流在峰值表现为「渠道限流与回调延迟」。全景上需要预留 降级开关与异步化边界：例如列表页短时跳过非关键 Hydrate、支付回调与订单状态更新解耦等（细节分散在第 8、12、13、15 章）。

5.4.1 商品数据流

覆盖从 B 端提交到 C 端可搜、可算、可卖的闭环。

sequenceDiagram
  autonumber
  actor Merchant as 商家/运营
  participant Listing as 商品上架
  participant Life as 生命周期管理
  participant Product as 商品中心
  participant Inv as 库存系统
  participant Price as 计价系统
  participant Bus as 消息总线
  participant ES as 搜索索引
  participant Search as 搜索与导购

  Merchant->>Listing: 提交上架申请
  Listing->>Listing: 审核/风控策略
  Listing->>Product: 创建/更新 SPU SKU
  Listing->>Inv: 初始化/同步可售库存
  Listing->>Price: 配置基础价与费用模板
  Product->>Bus: ProductChanged 事件
  Inv->>Bus: InventoryChanged 事件
  Price->>Bus: PriceSheetChanged 事件
  Bus-->>ES: 投影商品文档
  Note over ES: 异步最终一致
  Merchant->>Life: 发起下架/同步修正
  Life->>Product: 状态迁移与编辑边界控制
  Life->>Listing: 回流审核/发布任务
  Search->>ES: 列表/搜索召回
  Search->>Product: Hydrate 缺失字段（可选）
  Search->>Price: 列表价 Hydrate（可选）
  Search->>Inv: 可售状态 Hydrate（可选）

阶段解读：步骤 1～5 属于 B 端写路径，强一致要求集中在「商品主档 + 初始库存 + 基础价」三者是否同事务可见；多数平台会拆成多个本地事务 + Saga，用补偿保证最终一致。步骤 6～8 属于 异步投影，搜索可见略滞后于库表写入是预期行为，但应对运营提供「索引就绪率」指标。步骤 9～12 体现 生命周期对上架与主数据的回流：下架、供应商同步修正、违规处罚都会触发再次审核或索引失效。

伏笔：第 7 章讲清商品模型与快照；第 8 章区分预占与实物库存；第 10 章拆解上架与运营编辑的权限与状态机；第 12 章展开 Hydrate 编排与降级。

5.4.2 订单数据流

从结算页到订单持久化，强调编排、快照与回滚责任。

sequenceDiagram
  autonumber
  actor User as 用户
  participant GW as API Gateway
  participant Cart as 购物车
  participant Checkout as 结算编排
  participant Price as 计价系统
  participant Inv as 库存系统
  participant Mkt as 营销系统
  participant Product as 商品中心
  participant Order as 订单系统
  participant Bus as 消息总线

  User->>GW: 进入结算页
  GW->>Checkout: 打开结算会话
  Checkout->>Price: 试算（基础价+营销+费用）
  Checkout->>Inv: 库存预占（或预校验策略）
  Checkout->>Mkt: 券/活动可用性校验
  Price->>Product: 读取商品主数据
  User->>GW: 提交订单
  GW->>Order: 创单请求（携带试算令牌/版本）
  Order->>Product: 拉取/确认商品快照
  Order->>Price: 固化价格快照
  Order->>Inv: 确认预占或二次扣减
  Order->>Mkt: 锁定或扣减营销资源
  Order->>Order: 持久化订单与状态机
  Order->>Bus: OrderCreated 事件
  Bus-->>Cart: 提示清理已下单行（异步）

阶段解读：结算阶段（打开结算页）与创单阶段（提交订单）必须对试算结果有明确版本策略：常见做法是计价返回 quote_version 或签名摘要，订单持久化时校验，防止「页面价与实付不一致」引发纠纷。库存侧若已在结算预占，创单多为确认；若仅在结算校验、创单时才预占，则需评估高峰下的重试风暴（第 8 章）。营销锁定与扣减宜拆成「锁定 → 确认 / 释放」两阶段，与订单状态机对齐，避免券冻结长期占用。

异常路径（图中未展开但工程必备）：创单任一步失败应沿 Saga 反向释放预占与券锁定；若订单已写库但后续异步失败，应依赖订单状态机驱动补偿任务，而不是人工改库。

伏笔：第 12 章定义试算与快照边界；第 14 章给出 Saga 步骤与超时释放；第 15 章深入状态机与补偿；第 4 章把这些步骤抽象为可复用的一致性模式。

5.4.3 支付数据流

聚焦支付单生命周期与订单回写、清结算衔接。

sequenceDiagram
  autonumber
  actor User as 用户
  participant Order as 订单系统
  participant Pay as 支付系统
  participant Chan as 支付渠道
  participant Ledger as 账务/清结算
  participant Bus as 消息总线

  User->>Order: 去支付
  Order->>Pay: 创建支付单（order_id 幂等键）
  Pay->>Pay: 路由渠道路由/风控标签
  Pay->>Chan: 调用渠道下单接口
  Chan-->>User: 收银台/重定向
  Chan-->>Pay: 异步支付结果通知
  Pay->>Pay: 验签 幂等 状态机推进
  Pay->>Order: 同步支付结果（或订单轮询）
  Pay->>Ledger: 记账/分账指令
  Pay->>Bus: PaymentSucceeded 事件
  Bus-->>Mkt: 实付触达营销核算（可选）
  Note over Pay,Order: 失败/关单需可补偿：关支付单、回滚营销、释放库存（与各域策略绑定）

阶段解读：支付创建应以 order_id（或业务侧支付请求号）做天然幂等键，渠道侧重复调用不产生重复扣款。回调处理必须「先记账、后通知订单」或采用可对账的两阶段状态：确保账务系统（Ledger）与支付核心状态一致。PaymentSucceeded 事件驱动营销核算、分润、积分等下游时，仍应坚持 Outbox 语义，避免在回调线程堆叠扇出。

与订单的边界：订单系统关心「应付金额与履约状态」；支付系统关心「渠道收单结果与资金事实」。订单不应直接保存渠道原始报文全字段，应由支付系统规范化后回写支付结果摘要。

伏笔：第 16 章展开渠道适配、对账与退款；第 4 章讨论跨系统幂等与补偿事务编排。

5.5 系统边界总览

5.5.1 各系统的职责边界（十二个核心系统）

下表给出本书采用的十二个核心可部署系统（与 5.1.2 应用架构及第 7 章至第 15 章对应）。「不负责」列用于架构评审时的负面清单，防止边界侵蚀。

说明：第 10 章在目录上合并了上架、运营与生命周期；在工程上可拆为多服务，但在边界表中仍建议分开陈述职责，以便治理。

十二系统「一句话职责」扩展（评审口播版）：

• 商品中心：维护「卖得是什么」——结构化商品、类目约束与面向订单的快照能力；对外暴露稳定读模型与快照创建接口。
• 库存系统：维护「还能卖多少」——把可售量、渠道库存、预占凭证与对账闭环收敛在库存库表与热点缓存中。
• 营销系统：维护「怎么促卖」——圈品、券活动、补贴预算与叠加互斥规则；不负责把最终应付金额写入订单。
• 计价系统：维护「收多少钱」的规则引擎与快照——对接商品基础价与营销减免，输出可校验的试算版本。
• 搜索与导购：维护「怎么找得到」——索引与排序是手段，Hydrate 与场景识别是业务核心；索引永远晚于主库一秒是常态而非事故。
• 购物车：维护「用户想买什么」——会话级行项目与合并逻辑，不承担资金与库存的最终承诺。
• 结算编排：维护「现在能不能付」——把试算、预占、营销校验收敛为短窗口内的可执行计划，再交给订单持久化。
• 订单系统：维护「合同与履约状态」——状态机、拆单、快照引用与对外协调接口；不保存渠道密钥与支付通道报文。
• 支付系统：维护「资金事实」——支付单、渠道、回调、账务分录与对账；不反向驱动商品编辑。
• 商品上架：维护「供给侧流程」——审核、发布、异步补偿与状态机；它是编排器而非商品主数据的越权写入者。
• 供给与运营管理：维护「运营效率」——批量导入导出、配置工具、权限审计；所有落库应通过正式领域 API。
• 生命周期与供给治理：维护「时间与责任的边界」——上下架、同步冲突、编辑互斥与跨系统回滚策略的协调者。

按价值链聚类（便于向业务方解释）：

5.5.2 边界不清的常见问题

1. 商品中心写库存流水：库存的并发语义与对账域应收敛在库存上下文，否则易出现双写不一致。
2. 营销系统直接改订单金额：优惠「算出来」与订单「记下来」应分离；否则退款与审计难以追溯。
3. 搜索索引当主库：索引延迟会导致「搜得到但买不了」，必须在 Hydrate 或结算侧再次以权威服务为准。
4. 支付系统承载订单状态机：资金状态与履约状态相关但不同；混写会导致渠道回调与拆单场景难以治理。
5. 计价系统写订单行：计价负责「算」与试算令牌；订单负责「记」与版本校验。混写会让退款金额拆分失去依据。
6. 购物车持有库存预占：预占属于资源锁定，应落在结算或订单编排；购物车仅存意图与展示缓存。
7. 运营后台直连生产库改价：绕过计价与审计，极易产生监管与对账风险；应走审批流 + 正式 API。
8. 搜索服务在召回阶段调用支付：读路径不应触碰资金系统；价格与活动以 Hydrate 调用计价与营销只读接口为界。

5.5.3 边界划分原则（落地检查清单）

1. 单一事实来源（SSOT）：每个聚合只有一个权威上下文持久化。
2. 编排与状态分离：编排服务可以无状态或仅存会话；合同状态由订单上下文持有。
3. 读模型可替换：搜索、推荐、报表可重建；不可重建的是资金流水与订单合同。
4. 跨域用契约，不用隐式共享表：表连接是反模式；用 API、事件与明确 DTO。
5. 把「能不能买」的最后一次校验放在离钱最近且可审计的一步（通常是创单或支付创建）。
6. 明确「编排」与「领域服务」：编排负责步骤顺序与超时；领域服务负责业务规则判定。二者勿混在同一「上帝类」中。
7. 每个跨系统接口都有 SLI：例如试算 P99、索引延迟上限、支付回调处理延迟；无指标的接口等于无边界。
8. 用例驱动的边界测试：为每个系统维护「本系统拒绝处理的请求样例」，在 CI 或契约测试中固定下来，防止回归侵蚀。

5.6 本章小结

本章是全书的总领章，目标不是替代后续各章的深度，而是建立三样东西：同一套词汇（限界上下文与十二个系统）、同一张依赖图（应用与数据架构）、同一套交互纪律（同步 / 异步 / 数据同步的组合拳）。

你可以带走的关键结论：

1. 四视角对齐：BA 决定投资与语义边界，AA 决定可部署单元与依赖方向，DA 决定权威数据与投影路径，TA 决定规模化运行时能力。缺任一视角，评审容易出现「各说各话」。
2. 十二个核心系统：商品中心、库存、营销、计价、搜索、购物车、结算编排、订单、支付、商品上架、供给与运营、生命周期治理——分别对应第 7 章至第 15 章的主体叙事；其中第 10 章在工程上常合并多个部署单元，但在治理上仍建议按职责拆分讨论。
3. 域分类指导排兵：核心域（订单、支付、结算、购物车）追求正确性与可审计性；支撑域追求稳定与可替换的集成契约；通用域追求成本与 SLO 的平衡。搜索处于「通用技术 + 核心体验」的交叉带，第 12 章会展开其 Hydrate 与降级策略。
4. 交互模式不可偏科：只有同步会导致故障传播；只有异步会拉长不一致窗口；只有批式同步无法满足实时导购。实际架构是在 SLA、成本、团队成熟度 约束下的组合。
5. 三条主链路是阅读地图：商品流回答「货怎么进来并被发现」；订单流回答「承诺如何形成」；支付流回答「资金如何闭环」。后续章节均可挂载到这三条链上自检：本章的哪个小节、哪张图覆盖了当前话题。

与第 4 章的衔接：第 4 章将把 5.3 的交互模式上升为 Saga、幂等、对账、事件驱动 等一致性语言，并把 CAP 折中讲透。建议在读第 4 章前，先用 5.4 的时序图遮住文字，尝试口述一遍每条箭头上的失败与补偿，检验是否已建立全景肌肉记忆。

与第 7 章至第 15 章的衔接：进入任一系统章时，建议先回答四个问题——谁是上游、谁是下游、我的 SSOT 是什么、我发布哪些事件。答不上来则回到 5.5.1 边界表补齐。

面向架构师的自检清单（离开本章前）：能否在 10 分钟内手绘 5.1.2 依赖图并标出三条可能形成环的依赖？能否用业务语言向非技术干系人解释「为什么搜索不是订单的一部分」？能否列举支付回调失败时的三个系统状态组合及各自补偿动作？若尚不能，建议在笔记中重画一遍 5.4 时序图，再进入第 4 章。

建议阅读顺序：若你更熟悉业务，可按 5.4 节三条链路走读，再回看 5.1.1 的限界上下文；若你更熟悉工程，可从 5.1.2 与 5.3 节开始，把依赖与交互模式对齐后再进入各系统章节。若你正在准备架构评审，可携带 5.1.3、5.3.3 与 5.5.3 作为一页纸附录。

导航：书籍主页 | 完整目录 | 上一章：第6章 | 下一章：第8章

导航：书籍主页 | 完整目录 | 上一章：第7章 | 下一章：第9章

第8章 商品中心系统

本章定位：商品中心不是供给后台，也不是商家上传系统。商品中心是平台的正式商品主数据中心和交易前契约中心，负责沉淀已经发布生效的 Resource、SPU/SKU、Offer、库存配置、履约规则、退款规则、发布版本和商品快照。第 11 章讨论商品如何从 Draft、Staging、QC 进入平台；本章讨论商品一旦发布后，平台如何稳定、可追溯、可交易地表达“卖什么、怎么卖、如何履约、历史订单如何解释”。

商品中心最容易被设计成一个“大后台 CRUD”。早期这样做问题不大，但当平台开始支持本地生活、酒店、票务、充值、礼品卡、账单缴费、供应商同步和商家自助上传后，商品中心如果继续直接承接草稿、审核、导入、供应商拉取、搜索刷新、订单快照，就会迅速变成不可维护的大泥球。

更合理的边界是：

供给与运营平台
  → Draft / Staging / QC / Task / DLQ
  → Publish Command
  → 商品中心正式主数据
  → 商品快照 / Outbox / 读模型
  → 搜索、缓存、库存、计价、订单、履约

本章回答五个问题：

1. 商品中心到底负责什么？ 正式商品主数据、交易前契约、发布版本和稳定读模型。
2. 为什么不能把 Draft、QC、Rejected 放到商品正式表？ 因为这些是供给流程状态，不是正式商品生命周期状态。
3. Resource、SPU/SKU、Offer 如何建模？ 用资源层、商品定义层、销售承诺层拆清楚异构品类。
4. 发布版本和商品快照解决什么问题？ 解决回滚、对账、搜索一致性和历史订单解释。
5. 商品中心如何和库存、计价、搜索、订单集成？ 通过交易前契约、Outbox 事件和版本化读模型形成最终一致。

完整的供给治理链路见：

• 第11章：商品供给与运营管理和生命周期管理
• 附录G：商品供给与运营治理平台
• 附录F：供应商数据同步链路

8.1 系统定位与边界

8.1.1 商品中心是什么

商品中心是平台对“商品事实”的正式表达。它不关心商家正在编辑哪份草稿，也不关心某条 Excel 第几行是否解析失败；它关心的是已经发布生效的商品版本。

商品中心至少要回答：

一句话：

商品中心负责正式商品和交易前契约，不负责供给过程。

8.1.2 商品中心不是什么

商品中心不应该承接所有 B 端流程状态。下面这些内容应该属于第 11 章的供给与运营平台：

商品正式表不应该出现这些状态：

DRAFT
QC_PENDING
QC_REVIEWING
REJECTED
WITHDRAWN
PARSING
VALIDATING

正式商品表应该出现的是线上资产状态：

PUBLISHED
ONLINE
OFFLINE
ENDED
BANNED
ARCHIVED

这个边界非常重要。新建商品在 Draft、Staging、QC 阶段还没有正式 item_id，只有发布成功后才进入商品中心。如果商品中心提前生成正式商品并把状态设为 DRAFT，后面会出现两个问题：

1. 未审核商品容易被搜索、缓存或内部查询误读为正式商品。
2. Draft、QC、正式商品的生命周期混在一起，状态机很快失控。

8.1.3 与供给平台的关系

第 11 章的供给平台负责“如何把商品送进来”，商品中心负责“已经发布的商品如何被交易系统稳定使用”。

供给平台：
  Draft
  Staging Ticket
  QC Review
  Change Request
  Publish Record

商品中心：
  Resource
  Product Item
  SPU / SKU
  Offer / Rate Plan
  Stock Config
  Input Schema
  Fulfillment Rule
  Refund Rule
  Publish Version
  Product Snapshot

两者通过发布命令连接：

PublishProductVersionCommand
  → 商品中心校验 base_publish_version
  → 写正式商品主数据
  → 生成 publish_version
  → 生成商品快照
  → 写 Outbox 事件

商品中心可以保存 last_publish_id、last_operation_id、source_type 等审计引用，但不应该反向保存供给侧的完整流程状态。

8.2 总体架构

8.2.1 架构分层

商品中心建议拆成五层：

Command API
  → Domain Model
  → Versioned Write Model
  → Snapshot / Outbox
  → Read Model / Cache / Search Projection

更完整的架构如下：

flowchart LR
    subgraph Supply["供给与运营平台"]
        Draft["Draft / Staging / QC"]
        PublishCmd["Publish Command"]
    end

    subgraph ProductCenter["商品中心"]
        Command["Command API"]
        Domain["Resource / Item / SPU / SKU / Offer"]
        Contract["Stock Config / Input Schema / Fulfillment / Refund"]
        Version["Publish Version"]
        Snapshot["Product Snapshot"]
        Outbox["Outbox Event"]
        Query["Query API / Read Model"]
    end

    subgraph Downstream["下游系统"]
        Search["搜索"]
        Cache["缓存"]
        Pricing["计价"]
        Inventory["库存"]
        Order["订单"]
        Fulfillment["履约"]
        Data["数据平台"]
    end

    Draft --> PublishCmd
    PublishCmd --> Command
    Command --> Domain
    Command --> Contract
    Domain --> Version
    Contract --> Version
    Version --> Snapshot
    Version --> Outbox
    Snapshot --> Query
    Outbox --> Search
    Outbox --> Cache
    Outbox --> Pricing
    Outbox --> Inventory
    Outbox --> Data
    Query --> Order
    Query --> Fulfillment

这张图的关键点是：商品中心的写入口不是运营后台的表单提交，而是供给平台发布出来的命令。这样可以保证所有商品变更都经过 Draft、Staging、Validation、QC 或自动准入策略，再进入正式商品。

8.2.2 读写分离

商品中心的写入链路强调一致性和可追溯：

Publish Command
  → 版本校验
  → 正式表事务写入
  → 快照生成
  → Outbox

商品中心的读取链路强调低延迟和稳定：

详情页
  → Redis / Local Cache
  → 商品中心 Query API
  → DB 回源

列表页
  → Search
  → 商品中心批量 Hydrate

创单页
  → 商品中心版本化快照
  → 库存确认
  → 计价试算

不要让搜索列表直接扫商品中心 MySQL，也不要让商品中心在详情接口里临时计算复杂优惠价和实时库存。商品中心提供交易前契约，计价和库存由各自领域负责。

8.2.3 核心原则

商品中心设计要坚持几个原则：

8.3 核心领域模型

8.3.1 三层商品模型

传统电商常用 SPU/SKU 就够了，但数字商品平台会遇到酒店、票务、账单、充值、本地服务、礼品卡等异构场景。只靠 SPU/SKU 容易把资源、销售单元、交易契约混在一起。

更稳的模型是三层：

资源层 Resource
  → 商品定义层 SPU / SKU / Product Item
  → 销售承诺层 Offer / Rate Plan / Contract

这个拆法的好处是：

1. 同一个 Resource 可以挂多个商品。
2. 同一个 SKU 可以有多个 Offer。
3. 同一个 Offer 可以切换库存、履约、退款策略。
4. 供应商同步可以优先沉淀 Resource，运营再决定如何售卖。

8.3.2 Resource

Resource 表达“现实或外部世界里的资源对象”。它不是一定可售的商品，而是商品的承载对象。

Resource 的状态不等于商品状态。酒店资源可以是有效的，但某个房型 Offer 暂时不可售；门店可以营业，但某张券可以下架。

8.3.3 Product Item

Product Item 是商品中心对 C 端“一个可展示商品”的正式聚合。它通常对应前台一个详情页或一张商品卡。

它和 SPU 的关系取决于品类：

为什么需要 item_id？因为 C 端、商家端、订单、搜索通常需要一个统一的商品入口 ID。SPU/SKU 偏商品定义，Resource 偏资源对象，Offer 偏销售承诺；item_id 是把这些内容组合成“前台商品”的聚合根。

8.3.4 SPU / SKU

SPU 表达商品共性定义，SKU 表达可下单的规格单元。

不是所有数字商品都需要复杂多 SKU，但建议保留默认 SKU。这样订单、库存、计价、履约都能使用统一结构。

8.3.5 Offer / Rate Plan

Offer 表达销售承诺。它不是简单价格字段，而是一组交易前条件：

Offer =
  销售对象
  + 渠道
  + 销售期
  + 价格/价格引用
  + 库存来源
  + 输入要求
  + 履约规则
  + 退款规则

酒店和票务等品类还需要 Rate Plan：

例如酒店：

Resource: Bangkok Hotel A
SPU: Deluxe Room
SKU: Deluxe Room + 2 Breakfast
Offer: Shopee App Channel + TH Site
Rate Plan: refundable before T-1, pay now, supplier plan RP_001

8.4 类目模板与异构品类

8.4.1 为什么需要类目模板

商品中心不能为每个品类硬编码一套表单和校验。类目模板要定义：

1. 需要哪些 Resource。
2. 是否需要 SPU/SKU。
3. 必填属性和枚举。
4. 是否需要库存配置。
5. 是否需要 Input Schema。
6. 支持哪些履约方式。
7. 支持哪些退款规则。
8. 哪些字段可索引、可筛选、可展示。

category_template
  → resource_schema
  → spu_schema
  → sku_schema
  → offer_schema
  → contract_schema

类目模板既服务供给平台，也服务商品中心。供给平台用它做表单、校验、QC 风险识别；商品中心用它约束正式数据和生成读模型。

8.4.2 属性分类

商品属性至少分四类：

不要把所有属性都塞进一个 ext_info。适合搜索、筛选、风控、计价、履约使用的字段，要结构化存储或生成专门投影；纯展示和低频字段可以放 JSON 扩展。

8.4.3 扩展字段策略

扩展字段有三种方式：

推荐组合：

核心交易字段
  → 结构化列

品类核心字段
  → 垂直扩展表

长尾展示字段
  → JSON

搜索筛选字段
  → 搜索投影

8.5 正式商品状态与版本

8.5.1 Item 状态

正式商品的生命周期状态建议放在 product_item_tab.item_status：

它不应该包含 DRAFT、QC_PENDING、REJECTED。这些状态属于供给侧对象。

8.5.2 Sellable 状态

item_status 表达商品资产状态，sellable_status 表达当前是否可交易：

这两个状态可以不同。例如商品 ONLINE，但库存为 0 时 sellable_status=SOLD_OUT。列表页可以展示该商品，但下单按钮不可用。

8.5.3 Publish Version

每次发布都要生成新的 publish_version：

item_id = item_80001
publish_version: 3 → 4

版本用于：

1. 防止旧编辑覆盖新版本。
2. 支持回滚和审计。
3. 让搜索、缓存、订单按版本幂等处理。
4. 让历史订单能解释当时看到的商品。

编辑发布前必须校验：

staging.base_publish_version == product_item.current_publish_version

如果不相等，说明线上商品已经变化，当前提交应进入版本冲突，不能静默覆盖。

8.5.4 商品状态机

stateDiagram-v2
  [*] --> PUBLISHED: Publish Version Created
  PUBLISHED --> ONLINE: Hit Sale Rule
  PUBLISHED --> OFFLINE: Not Saleable Yet
  ONLINE --> OFFLINE: Merchant/Ops Offline
  ONLINE --> ENDED: Sale Ended
  ONLINE --> BANNED: Platform Ban
  OFFLINE --> ONLINE: Reactivate
  ENDED --> ONLINE: Extend Sale Period and Publish
  BANNED --> OFFLINE: Unban
  OFFLINE --> ARCHIVED: Archive
  ENDED --> ARCHIVED: Archive
  ARCHIVED --> [*]

注意：这个状态机只描述正式商品。Draft、Staging、QC 的状态机在第 11 章。

8.6 核心表模型

商品中心表模型围绕“正式主数据 + 交易前契约 + 发布版本 + 快照”设计。

8.6.1 Resource 表

CREATE TABLE resource_tab (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    resource_id VARCHAR(64) NOT NULL,
    resource_type VARCHAR(32) NOT NULL COMMENT 'HOTEL/STORE/EVENT/CARRIER/BILLER',
    category_code VARCHAR(32) NOT NULL,
    resource_name VARCHAR(256) NOT NULL,
    country_code VARCHAR(32) DEFAULT NULL,
    city_code VARCHAR(64) DEFAULT NULL,
    address VARCHAR(512) DEFAULT NULL,
    geo_lat DECIMAL(10, 7) DEFAULT NULL,
    geo_lng DECIMAL(10, 7) DEFAULT NULL,
    status VARCHAR(32) NOT NULL COMMENT 'ACTIVE/INACTIVE/ARCHIVED',
    ext_info JSON DEFAULT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    UNIQUE KEY uk_resource_id (resource_id),
    KEY idx_type_city (resource_type, city_code),
    KEY idx_category_status (category_code, status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='平台资源主表';

Resource 是平台沉淀资源的主表。供应商同步通常先映射到 Resource，再由供给平台决定是否生成商品和 Offer。

8.6.2 Product Item 表

CREATE TABLE product_item_tab (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    item_id VARCHAR(64) NOT NULL,
    category_code VARCHAR(32) NOT NULL,
    item_type VARCHAR(32) NOT NULL COMMENT 'STANDARD/VIRTUAL/LOCAL_SERVICE/HOTEL/TICKET/BILL',
    resource_id VARCHAR(64) DEFAULT NULL,
    title VARCHAR(256) NOT NULL,
    subtitle VARCHAR(512) DEFAULT NULL,
    main_image VARCHAR(512) DEFAULT NULL,
    item_status VARCHAR(32) NOT NULL COMMENT 'PUBLISHED/ONLINE/OFFLINE/ENDED/BANNED/ARCHIVED',
    sellable_status VARCHAR(32) NOT NULL COMMENT 'SELLABLE/UNSELLABLE/NOT_STARTED/SOLD_OUT/EXPIRED/RISK_BLOCKED',
    current_publish_version BIGINT NOT NULL DEFAULT 1,
    sale_start_at DATETIME DEFAULT NULL,
    sale_end_at DATETIME DEFAULT NULL,
    source_type VARCHAR(32) DEFAULT NULL COMMENT 'LOCAL_OPS/MERCHANT/SUPPLIER/SYSTEM',
    last_publish_id VARCHAR(64) DEFAULT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    UNIQUE KEY uk_item_id (item_id),
    KEY idx_resource (resource_id),
    KEY idx_category_status (category_code, item_status),
    KEY idx_sellable (sellable_status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='正式商品聚合根';

product_item_tab 是 C 端商品入口。它不保存 Draft 和 QC 状态，只保存正式商品的线上状态和当前发布版本。

8.6.3 SPU 表

CREATE TABLE product_spu_tab (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    spu_id VARCHAR(64) NOT NULL,
    item_id VARCHAR(64) NOT NULL,
    category_code VARCHAR(32) NOT NULL,
    spu_name VARCHAR(256) NOT NULL,
    brand_id BIGINT DEFAULT NULL,
    spec_schema JSON DEFAULT NULL,
    attr_payload JSON DEFAULT NULL,
    status VARCHAR(32) NOT NULL COMMENT 'ACTIVE/INACTIVE/ARCHIVED',
    publish_version BIGINT NOT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    UNIQUE KEY uk_spu_id (spu_id),
    KEY idx_item (item_id),
    KEY idx_category_status (category_code, status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品 SPU 定义';

SPU 承载共性信息和规格定义。对于单规格商品，可以只有一个默认 SKU。

8.6.4 SKU 表

CREATE TABLE product_sku_tab (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    sku_id VARCHAR(64) NOT NULL,
    item_id VARCHAR(64) NOT NULL,
    spu_id VARCHAR(64) NOT NULL,
    sku_name VARCHAR(256) DEFAULT NULL,
    spec_values JSON DEFAULT NULL,
    barcode VARCHAR(128) DEFAULT NULL,
    sku_status VARCHAR(32) NOT NULL COMMENT 'ACTIVE/INACTIVE/ARCHIVED',
    publish_version BIGINT NOT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    UNIQUE KEY uk_sku_id (sku_id),
    KEY idx_item (item_id),
    KEY idx_spu (spu_id),
    KEY idx_status (sku_status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品 SKU 定义';

SKU 是订单行、库存配置和计价试算常用的锚点。即使是虚拟品，也建议保留默认 SKU 来统一交易链路。

8.6.5 Offer 表

CREATE TABLE product_offer_tab (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    offer_id VARCHAR(64) NOT NULL,
    item_id VARCHAR(64) NOT NULL,
    spu_id VARCHAR(64) DEFAULT NULL,
    sku_id VARCHAR(64) DEFAULT NULL,
    resource_id VARCHAR(64) DEFAULT NULL,
    offer_type VARCHAR(32) NOT NULL COMMENT 'NORMAL/PACKAGE/RATE_PLAN/PRESELL',
    site_code VARCHAR(32) NOT NULL,
    channel_code VARCHAR(32) DEFAULT NULL,
    currency VARCHAR(16) NOT NULL,
    list_price DECIMAL(18, 4) DEFAULT NULL COMMENT '标价或基础价，不等同最终成交价',
    offer_status VARCHAR(32) NOT NULL COMMENT 'ACTIVE/INACTIVE/ARCHIVED',
    sale_start_at DATETIME DEFAULT NULL,
    sale_end_at DATETIME DEFAULT NULL,
    publish_version BIGINT NOT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    UNIQUE KEY uk_offer_id (offer_id),
    KEY idx_item_status (item_id, offer_status),
    KEY idx_sku (sku_id),
    KEY idx_site_channel (site_code, channel_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品销售 Offer';

Offer 里的价格字段只能表达基础价或标价。最终成交价应该由计价系统根据活动、优惠、会员、渠道和风控规则试算。

8.6.6 Rate Plan 表

CREATE TABLE product_rate_plan_tab (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    rate_plan_id VARCHAR(64) NOT NULL,
    offer_id VARCHAR(64) NOT NULL,
    supplier_id BIGINT DEFAULT NULL,
    supplier_rate_plan_code VARCHAR(128) DEFAULT NULL,
    plan_name VARCHAR(256) DEFAULT NULL,
    plan_type VARCHAR(32) DEFAULT NULL COMMENT 'REFUNDABLE/NON_REFUNDABLE/PAY_NOW/PAY_LATER',
    cancellation_policy_ref VARCHAR(128) DEFAULT NULL,
    meal_plan VARCHAR(64) DEFAULT NULL,
    ext_info JSON DEFAULT NULL,
    status VARCHAR(32) NOT NULL COMMENT 'ACTIVE/INACTIVE/ARCHIVED',
    publish_version BIGINT NOT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    UNIQUE KEY uk_rate_plan_id (rate_plan_id),
    KEY idx_offer (offer_id),
    KEY idx_supplier_plan (supplier_id, supplier_rate_plan_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='价格计划或供应商 Rate Plan';

Rate Plan 适合酒店、票务、活动等复杂供给。简单商品可以不建独立 Rate Plan，只使用 Offer。

8.6.7 库存配置表

CREATE TABLE product_stock_config_tab (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    stock_config_id VARCHAR(64) NOT NULL,
    item_id VARCHAR(64) NOT NULL,
    sku_id VARCHAR(64) DEFAULT NULL,
    offer_id VARCHAR(64) DEFAULT NULL,
    stock_type VARCHAR(32) NOT NULL COMMENT 'PLATFORM_STOCK/CODE_POOL/SUPPLIER_REALTIME/NO_STOCK',
    inventory_ref VARCHAR(128) DEFAULT NULL,
    deduct_timing VARCHAR(32) DEFAULT NULL COMMENT 'CREATE_ORDER/PAY_SUCCESS/FULFILL_SUCCESS',
    oversell_policy VARCHAR(32) DEFAULT NULL COMMENT 'FORBID/ALLOW_WITH_LIMIT/SUPPLIER_CONFIRM',
    status VARCHAR(32) NOT NULL COMMENT 'ACTIVE/INACTIVE',
    publish_version BIGINT NOT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    UNIQUE KEY uk_stock_config_id (stock_config_id),
    KEY idx_item (item_id),
    KEY idx_offer (offer_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品库存配置';

这张表保存库存“如何接入”和“扣减时机”，不保存实时库存事实。实时库存属于库存系统或供应商实时确认。

8.6.8 输入 Schema 表

CREATE TABLE product_input_schema_tab (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    input_schema_id VARCHAR(64) NOT NULL,
    item_id VARCHAR(64) NOT NULL,
    offer_id VARCHAR(64) DEFAULT NULL,
    schema_version BIGINT NOT NULL,
    schema_payload JSON NOT NULL,
    status VARCHAR(32) NOT NULL COMMENT 'ACTIVE/INACTIVE/ARCHIVED',
    publish_version BIGINT NOT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    UNIQUE KEY uk_input_schema_id (input_schema_id),
    KEY idx_item_offer (item_id, offer_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='下单输入 Schema';

充值需要手机号，账单缴费需要账单号，酒店需要入住人，机票需要乘机人证件。Input Schema 必须发布为正式契约，否则订单系统无法稳定校验用户输入。

8.6.9 履约规则表

CREATE TABLE product_fulfillment_rule_tab (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    fulfillment_rule_id VARCHAR(64) NOT NULL,
    item_id VARCHAR(64) NOT NULL,
    offer_id VARCHAR(64) DEFAULT NULL,
    fulfillment_type VARCHAR(32) NOT NULL COMMENT 'TOPUP/ISSUE_CODE/BOOKING/SUPPLIER_ORDER/MANUAL',
    supplier_id BIGINT DEFAULT NULL,
    fulfillment_params JSON DEFAULT NULL,
    timeout_seconds INT DEFAULT NULL,
    retry_policy JSON DEFAULT NULL,
    status VARCHAR(32) NOT NULL COMMENT 'ACTIVE/INACTIVE/ARCHIVED',
    publish_version BIGINT NOT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    UNIQUE KEY uk_fulfillment_rule_id (fulfillment_rule_id),
    KEY idx_item_offer (item_id, offer_id),
    KEY idx_supplier (supplier_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品履约规则';

履约规则是交易前契约的一部分。订单创建时要保存对应快照，避免商品后续修改供应商参数后影响历史订单。

8.6.10 退款规则表

CREATE TABLE product_refund_rule_tab (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    refund_rule_id VARCHAR(64) NOT NULL,
    item_id VARCHAR(64) NOT NULL,
    offer_id VARCHAR(64) DEFAULT NULL,
    refund_type VARCHAR(32) NOT NULL COMMENT 'REFUNDABLE/NON_REFUNDABLE/PARTIAL/CONDITIONAL',
    rule_payload JSON NOT NULL,
    status VARCHAR(32) NOT NULL COMMENT 'ACTIVE/INACTIVE/ARCHIVED',
    publish_version BIGINT NOT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    UNIQUE KEY uk_refund_rule_id (refund_rule_id),
    KEY idx_item_offer (item_id, offer_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品退款规则';

退款规则变更属于高风险变更。它应在第 11 章供给平台中经过 Diff、风险识别和 QC 或强权限确认，再发布到商品中心。

8.6.11 发布版本表

CREATE TABLE product_publish_version_tab (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    item_id VARCHAR(64) NOT NULL,
    publish_version BIGINT NOT NULL,
    publish_id VARCHAR(64) NOT NULL,
    publish_type VARCHAR(32) NOT NULL COMMENT 'CREATE/EDIT/OFFLINE/ONLINE/BAN/UNBAN/ROLLBACK',
    source_type VARCHAR(32) DEFAULT NULL COMMENT 'LOCAL_OPS/MERCHANT/SUPPLIER/SYSTEM',
    source_ref_id VARCHAR(64) DEFAULT NULL COMMENT '供给侧 publish_id、operation_id 或 sync batch',
    payload_hash VARCHAR(64) NOT NULL,
    status VARCHAR(32) NOT NULL COMMENT 'ACTIVE/ROLLED_BACK/ARCHIVED',
    created_at DATETIME NOT NULL,
    UNIQUE KEY uk_item_version (item_id, publish_version),
    UNIQUE KEY uk_publish_id (publish_id),
    KEY idx_item_time (item_id, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品发布版本';

发布版本是商品中心的核心版本轴。供给侧的 product_publish_record 记录发布动作，商品中心的 product_publish_version_tab 记录正式版本事实。

8.6.12 商品快照表

CREATE TABLE product_snapshot_tab (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    snapshot_id VARCHAR(64) NOT NULL,
    item_id VARCHAR(64) NOT NULL,
    publish_version BIGINT NOT NULL,
    snapshot_type VARCHAR(32) NOT NULL
        COMMENT 'FULL/PRODUCT/OFFER/STOCK_CONFIG/INPUT_SCHEMA/FULFILLMENT/REFUND',
    snapshot_payload JSON NOT NULL,
    payload_hash VARCHAR(64) NOT NULL,
    payload_ref VARCHAR(512) DEFAULT NULL,
    created_at DATETIME NOT NULL,
    UNIQUE KEY uk_snapshot_id (snapshot_id),
    UNIQUE KEY uk_item_version_type (item_id, publish_version, snapshot_type),
    KEY idx_item_version (item_id, publish_version)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品发布快照';

快照是订单系统解释历史订单的基础。订单不应该回读最新商品表，而应该保存或引用创单时的快照。

8.6.13 Outbox 表

CREATE TABLE product_outbox_event (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    event_id VARCHAR(64) NOT NULL,
    aggregate_type VARCHAR(64) NOT NULL COMMENT 'PRODUCT_ITEM/PUBLISH_VERSION',
    aggregate_id VARCHAR(64) NOT NULL,
    event_type VARCHAR(128) NOT NULL
        COMMENT 'ProductPublished/ProductOnline/ProductOffline/ProductSnapshotCreated',
    item_id VARCHAR(64) DEFAULT NULL,
    publish_version BIGINT DEFAULT NULL,
    payload JSON NOT NULL,
    status VARCHAR(32) NOT NULL DEFAULT 'PENDING'
        COMMENT 'PENDING/SENDING/SENT/FAILED/DLQ',
    retry_count INT NOT NULL DEFAULT 0,
    next_retry_at DATETIME DEFAULT NULL,
    last_error_message VARCHAR(1024) DEFAULT NULL,
    created_at DATETIME NOT NULL,
    sent_at DATETIME DEFAULT NULL,
    updated_at DATETIME NOT NULL,
    UNIQUE KEY uk_event_id (event_id),
    KEY idx_status_retry (status, next_retry_at),
    KEY idx_item_version (item_id, publish_version)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品中心 Outbox 事件';

正式表写入、版本表、快照表、Outbox 必须在同一个事务里完成。搜索和缓存刷新失败时，不回滚商品发布，而是通过 Outbox 重试和补偿。

8.7 发布写入链路

8.7.1 只接受发布命令

商品中心写接口不应该暴露成通用 CRUD：

POST /product/updateTitle
POST /sku/updatePrice
POST /offer/updateRefundRule

更合理的是命令式接口：

PublishProductVersion
OfflineProduct
ReactivateProduct
BanProduct
UnbanProduct
ArchiveProduct
RollbackProductVersion

原因很简单：商品变更不是字段修改，而是交易前契约变更。每次变更都需要版本、快照、事件和审计。

8.7.2 Publish Command

发布命令需要包含完整的发布上下文：

{
  "publish_id": "pub_20260427_0001",
  "operation_id": "op_20001",
  "source_type": "MERCHANT",
  "publish_type": "EDIT",
  "item_id": "item_80001",
  "base_publish_version": 3,
  "category_code": "LOCAL_SERVICE",
  "resource": {},
  "spu_list": [],
  "sku_list": [],
  "offer_list": [],
  "stock_config_list": [],
  "input_schema_list": [],
  "fulfillment_rule_list": [],
  "refund_rule_list": []
}

新建商品时 item_id 可以为空，由商品中心在发布事务中生成正式 item_id。编辑商品时必须带 item_id 和 base_publish_version。

8.7.3 发布前校验

商品中心发布前要做最后一道强校验：

1. publish_id 是否幂等。
2. 新建商品是否没有重复外部对象映射。
3. 编辑商品的 base_publish_version 是否匹配当前版本。
4. Resource、SPU、SKU、Offer 关系是否完整。
5. 库存配置、输入 Schema、履约规则、退款规则是否满足类目模板。
6. 商品是否被封禁、归档或锁定。
7. 发布 payload hash 是否已经发布过。

如果校验失败，商品中心应该返回结构化错误给供给平台，由供给平台记录 DLQ 或展示给运营。

8.7.4 发布事务

发布事务的典型流程：

BEGIN
  → 幂等检查 publish_id
  → 新建商品生成 item_id，编辑商品锁定 item_id 当前版本
  → 写 resource_tab
  → 写 product_item_tab
  → 写 product_spu_tab
  → 写 product_sku_tab
  → 写 product_offer_tab
  → 写 product_stock_config_tab
  → 写 product_input_schema_tab
  → 写 product_fulfillment_rule_tab
  → 写 product_refund_rule_tab
  → 生成 new_publish_version
  → 写 product_publish_version_tab
  → 写 product_snapshot_tab
  → 写 product_outbox_event
COMMIT

不要在发布事务里刷新 ES、删除 Redis、通知营销系统。那些动作通过 Outbox 异步执行。

8.7.5 幂等与并发

发布幂等建议使用：

编辑并发使用版本 CAS：

UPDATE product_item_tab
SET current_publish_version = ?,
    updated_at = NOW()
WHERE item_id = ?
  AND current_publish_version = ?;

rows_affected = 0 说明线上版本已经变化，本次发布必须失败并返回版本冲突。

8.8 读取模型与查询接口

8.8.1 详情页读模型

详情页需要的信息通常横跨多张表：

item
  + resource
  + spu / sku
  + offer
  + stock config
  + input schema
  + fulfillment rule
  + refund rule

在线上高 QPS 场景，不建议每次详情请求都做多表实时 Join。可以生成详情读模型：

ProductDetailView
  item_id
  publish_version
  title
  images
  resource_info
  sku_options
  offer_summary
  input_schema
  fulfillment_summary
  refund_summary
  sellable_status

读模型可以存 Redis、文档库或宽表。它是正式表的投影，不是新的事实源。

8.8.2 列表页与搜索

列表页通常从搜索系统召回商品，再批量补充商品中心的轻量信息：

Search Query
  → item_id list
  → batch get product summary
  → merge price / inventory / campaign hint

搜索索引建议保存：

item_id
publish_version
title
category
resource_location
tags
display_price
sellable_status
updated_at

搜索索引不是商品事实源。索引里的 publish_version 必须能和商品中心对账。

8.8.3 创单前读取

创单前读取和详情页读取不同。详情页可以为了体验返回缓存，创单前必须重新确认交易安全：

Create Order
  → 读取商品当前 publish_version
  → 读取商品快照
  → 库存确认
  → 计价试算
  → 供应商实时确认（如果需要）
  → 保存订单快照

对酒店、机票、电影票这类动态品类：

列表页可以缓存
详情页尽量刷新
创单前必须实时确认

8.8.4 批量查询

商品中心必须提供批量查询接口，否则搜索、购物车、订单、营销会在高峰期打出 N+1 查询。

推荐接口：

BatchGetProductSummary(item_ids)
BatchGetProductSnapshot(item_id, publish_version)
BatchGetOfferContract(offer_ids)
BatchGetInputSchema(item_ids)

批量接口要支持部分失败和降级：

{
  "success_items": [],
  "missing_items": ["item_001"],
  "stale_items": ["item_002"]
}

8.9 商品快照与订单契约

8.9.1 为什么订单只信快照

商品会持续变化：标题、图片、价格、退款规则、履约参数、供应商映射都可能调整。如果历史订单回读最新商品表，就会出现：

1. 用户下单时看到可退款，售后时变成不可退款。
2. 下单时是供应商 A，履约时商品映射变成供应商 B。
3. 下单时价格计划为 RP_001，后续改成 RP_002，订单对账无法解释。
4. 商品下架后历史订单详情无法展示。

所以订单创建时必须保存商品上下文快照。

8.9.2 快照内容

订单至少需要保存或引用：

商品中心负责商品、Offer、输入、履约、退款等交易前契约快照；计价系统负责价格快照；库存系统负责库存预占或扣减记录。

8.9.3 快照生成策略

快照可以在发布时生成，也可以在创单时按版本读取。

推荐：

发布时生成版本化商品快照
  → 创单时引用 item_id + publish_version + snapshot_id
  → 订单保存必要字段冗余

这样既能减少创单时组装成本，也能保证历史解释稳定。

8.10 与库存、计价、搜索、订单的边界

8.10.1 与库存系统

商品中心保存库存配置，不保存实时库存事实。

例如：

product_stock_config.stock_type = CODE_POOL
inventory_ref = code_pool_10001

商品中心只告诉订单系统这个商品使用券码池，真正券码是否可用由库存或券码系统判断。

8.10.2 与计价系统

商品中心可以保存基础价、标价、Offer 规则引用，但最终成交价属于计价系统。

商品中心：
  list_price
  currency
  offer_id
  rate_plan_id

计价系统：
  channel price
  campaign price
  coupon
  service fee
  settlement amount
  final payable amount

不要把活动价、券后价、会员价直接写死在商品表里，否则退款、对账和营销成本会失去来源。

8.10.3 与搜索系统

搜索系统是商品中心的读投影。商品中心通过 Outbox 发送：

ProductPublished
ProductContentChanged
ProductOnline
ProductOffline
ProductSellableChanged

搜索消费事件后更新索引。索引要保存 publish_version，方便巡检：

product_item.current_publish_version
  vs
search_index.publish_version

如果不一致，生成补偿任务重建索引。

8.10.4 与订单系统

订单系统使用商品中心的方式是：

1. 创单前读取商品当前版本和快照。
2. 校验商品状态和基础交易契约。
3. 调库存系统确认可售。
4. 调计价系统确认金额。
5. 必要时调供应商实时确认。
6. 保存订单快照。

订单不应该直接依赖商品中心最新表解释历史订单。

8.10.5 与履约系统

履约系统需要的不是最新商品详情，而是订单创建时的履约规则快照。

fulfillment_type
supplier_id
supplier_product_code
rate_plan_code
timeout_seconds
retry_policy

商品发布后的履约规则变更只影响新订单，不影响旧订单。

8.11 缓存、索引与一致性

8.11.1 缓存策略

商品详情适合多级缓存：

Local Cache
  → Redis
  → DB / Read Model

缓存 key 要带版本：

product:detail:{item_id}:{publish_version}

这样新版本发布后可以直接读新 key，旧版本仍可供历史订单或短期页面使用。

8.11.2 缓存失效

发布成功后，不建议同步删除所有缓存。更稳的方式：

写新版本缓存
  → Outbox 通知缓存失效
  → 旧版本自然过期

如果使用不带版本的热 key：

product:detail:{item_id}

则必须通过 Outbox 事件失效或刷新，并让消费者按 publish_version 幂等，避免旧事件覆盖新缓存。

8.11.3 搜索最终一致

商品中心 DB 和搜索索引天然是最终一致。关键不是强行同步刷新，而是：

1. 事件不丢。
2. 消费可重试。
3. 消费按版本幂等。
4. 有巡检发现索引落后。
5. 有补偿任务重建索引。

巡检公式：

索引落后 = product_item.current_publish_version > search_index.publish_version

8.11.4 Outbox 补偿

Outbox 失败不应影响商品发布成功。失败事件进入重试：

PENDING
  → SENDING
  → SENT

SENDING / FAILED
  → retry
  → DLQ

常见补偿任务：

1. 重建搜索索引。
2. 刷新商品详情缓存。
3. 重放商品发布事件。
4. 校验营销圈品是否同步。
5. 校验订单创单快照是否可读取。

8.12 供应商同步与商品中心

供应商同步属于供给链路，不属于商品中心内部执行链路。商品中心不应该知道某个供应商全量同步跑到哪个城市、哪个 page、哪个 cursor。

正确关系：

Supplier Sync
  → Raw Snapshot
  → Normalize
  → Mapping
  → Diff
  → Product Supply Staging
  → Publish Command
  → Product Center

商品中心只接收发布后的正式结果：

Resource 更新
SPU/SKU 更新
Offer 更新
Rate Plan 更新
履约/退款契约更新

但商品中心要支持供应商同步带来的特殊要求：

8.13 商品中心 API 设计

8.13.1 Command API

Command API 面向供给平台和内部治理系统。

Command API 要求：

1. 强幂等。
2. 带 operator 和 source_ref。
3. 带 base_publish_version。
4. 返回结构化错误。
5. 写操作必须产生版本、快照和事件。

8.13.2 Query API

Query API 面向前台、订单、搜索 Hydrate 和内部系统。

Query API 要区分：

C 端展示读取
  → 可以走缓存和读模型

创单交易读取
  → 必须读取版本化快照并做状态校验

8.13.3 事件 API

商品中心对外发布事件：

ProductPublished
ProductContentChanged
ProductOfferChanged
ProductContractChanged
ProductOnline
ProductOffline
ProductBanned
ProductArchived
ProductSnapshotCreated

事件 payload 至少包含：

{
  "event_id": "evt_001",
  "event_type": "ProductPublished",
  "item_id": "item_80001",
  "publish_version": 4,
  "changed_fields": ["title", "refund_rule"],
  "occurred_at": "2026-04-27T10:00:00Z"
}

下游必须按 event_id 幂等，按 publish_version 防乱序。

8.14 质量治理与可观测性

8.14.1 商品质量维度

商品中心要参与发布后质量巡检，但质量问题的修复流程仍然回到供给平台。

常见质量问题：

8.14.2 监控指标

8.14.3 排查链路

线上商品问题建议从 item_id 和 publish_version 开始排查：

item_id
  → product_item_tab
  → product_publish_version_tab
  → product_snapshot_tab
  → product_outbox_event
  → search_index publish_version
  → order snapshot

如果要追溯商品是怎么进入平台的，再通过 source_ref_id 回到第 11 章供给平台：

publish_id / operation_id
  → product_supply_operation_log
  → draft / staging / qc / publish_record

8.15 答辩材料

本章相关问题、总结话术和追问要点已统一收录到附录B。

延伸阅读建议：

• 第9章：库存系统
• 第10章：营销系统
• 第11章：商品供给与运营管理和生命周期管理
• 附录G：商品供给与运营治理平台
• 附录F：供应商数据同步链路

导航：书籍主页 | 完整目录 | 上一章：第7章 | 下一章：第9章

导航：书籍主页 | 完整目录 | 上一章：第8章 | 下一章：第10章

第9章 库存系统

本章定位：库存是交易链路的硬约束之一。本章先从通用库存系统出发，解释库存为什么不是一个简单数字，而是一种可承诺供给能力；再用库存对象、库存范围、事实来源、单元形态和扣减时机抽象多品类差异，最后落到虚拟商品库存的券码、充值、供应商实时生成、Redis 原子扣减、账本对账与补偿实践。

9.1 背景与挑战

9.1.1 库存系统的本质

库存系统管理的不是一个简单数字，而是平台对用户的一种可承诺供给能力：

某个售卖对象
  在某个库存范围
  某个时间窗口
  某种业务约束下
  还能承诺给用户多少

这句话比“SKU 还有多少件”更接近真实电商。实物电商要考虑仓库、门店、调拨、发货；本地生活要考虑门店、券码、活动名额；酒店要考虑日期、房型、供应商确认；票务要考虑场次、座位、出票；虚拟商品要考虑卡密、充值、供应商实时生成和不可逆履约。

因此，库存系统的第一原则不是“扣一个数”，而是：

在高并发、可重试、可能失败的交易链路里，稳定地回答“能不能卖”，并把每一次承诺、占用、确认、释放、补偿都记录清楚。

从通用库存视角看，库存至少有五种状态语义：

库存语义混淆的答辩提示已统一收录到附录B。

9.1.2 从通用库存到虚拟商品库存

通用库存系统先解决“可售承诺”的建模问题，再针对不同品类选择不同策略。虚拟商品没有传统仓库和物流，但它不是更简单，而是把仓储复杂度换成了履约和一致性复杂度：券码不能重复发，充值提交后不能随便撤回，供应商实时生成可能超时，卡密泄露会变成资损。

所以这一章的叙事顺序应该是：先建立通用库存系统，再过渡到虚拟商品库存类型。后文的 Redis Lua、供应商同步、对账补偿，本质上都是服务于这些难点，而不是为了展示某个技术组件。

9.1.3 核心难点与解决手段

库存系统的技术含量集中在“高并发下把承诺做对，失败后能修回来”。

这张表也决定了本章的技术主线：账本模型保证可追溯，原子扣减保证并发安全，幂等状态机保证可重试，对账补偿保证最终修复，供应商适配保证外部不确定性可控。

9.1.4 设计目标

容量与并发视角的补充：库存系统往往是交易洪峰的第一扇闸门。当创单 QPS 在短时间内抬升一个数量级时，最先暴露的通常不是 CPU，而是热 Key、连接池、消息堆积与下游供应商配额。因此在需求阶段就要区分两类指标：对用户承诺的创单成功率，以及对内部承诺的库存服务自身 SLO，例如 Reserve P99、对账修复时延、补偿积压量。两者混谈会导致“系统看起来没挂，但用户体验已经崩了”。

9.2 通用库存模型与分类体系

9.2.1 四个建模问题

设计库存系统时，不应该先问“用 Redis 还是 MySQL”，而应该先问四个建模问题：

这四个问题共同决定库存 Key、数据表唯一键、缓存 Key、扣减策略和对账维度。缺少“库存范围”时，系统很容易只支持虚拟商品数量制，一旦接入仓库、门店、酒店日期或活动独占库存，就会开始堆 if category == xxx。

9.2.2 库存范围：从 SKU 到可售承诺

通用库存的核心 Key 不是单纯 sku_id，而是：

inventory_key =
  sku_id
  + scope_type / scope_id
  + calendar_date / time_slot
  + batch_id
  + channel_id
  + supplier_id

不同业务可以裁剪维度，但不能把范围概念抹掉。

工程上建议把库存范围抽象成 scope_type + scope_id，再把日期、批次、渠道作为显式字段。这样既能保持查询可控，也能让业务表达足够清晰。

9.2.3 账本、聚合与热视图

一个可恢复的库存系统通常至少有四类数据：

最重要的设计原则是：

Redis 是热路径投影，不是最终账本。库存事故恢复时，应以 MySQL 账本、预占记录、订单状态和供应商最终态为准。

通用模型可以这样组织：

CREATE TABLE inventory_config (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  inventory_key VARCHAR(128) NOT NULL,
  item_id BIGINT NOT NULL,
  sku_id BIGINT NOT NULL DEFAULT 0,
  scope_type VARCHAR(32) NOT NULL DEFAULT 'GLOBAL'
    COMMENT 'GLOBAL/WAREHOUSE/STORE/CITY/CHANNEL/DATE/SUPPLIER',
  scope_id VARCHAR(64) NOT NULL DEFAULT '0',
  management_type INT NOT NULL COMMENT '1=自管理,2=供应商,3=无限',
  unit_type INT NOT NULL COMMENT '1=券码,2=数量,3=时间,4=组合',
  deduct_timing INT NOT NULL DEFAULT 1 COMMENT '1=下单,2=支付,3=发货,4=供应商确认',
  supplier_id BIGINT NOT NULL DEFAULT 0,
  sync_strategy INT NOT NULL DEFAULT 0 COMMENT '1=定时,2=实时,3=推送',
  oversell_allowed TINYINT NOT NULL DEFAULT 0,
  low_stock_threshold INT NOT NULL DEFAULT 100,
  status INT NOT NULL DEFAULT 1,
  UNIQUE KEY uk_inventory_key (inventory_key),
  KEY idx_item_sku (item_id, sku_id)
);

CREATE TABLE inventory_balance (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  inventory_key VARCHAR(128) NOT NULL,
  item_id BIGINT NOT NULL,
  sku_id BIGINT NOT NULL,
  scope_type VARCHAR(32) NOT NULL,
  scope_id VARCHAR(64) NOT NULL,
  batch_id BIGINT NOT NULL DEFAULT 0,
  calendar_date DATE DEFAULT NULL,
  total_stock INT NOT NULL DEFAULT 0,
  available_stock INT NOT NULL DEFAULT 0,
  booking_stock INT NOT NULL DEFAULT 0,
  locked_stock INT NOT NULL DEFAULT 0,
  sold_stock INT NOT NULL DEFAULT 0,
  supplier_stock INT NOT NULL DEFAULT 0,
  supplier_sync_time BIGINT NOT NULL DEFAULT 0,
  version BIGINT NOT NULL DEFAULT 0,
  updated_at DATETIME NOT NULL,
  UNIQUE KEY uk_inventory_key (inventory_key),
  KEY idx_sku_scope (sku_id, scope_type, scope_id),
  KEY idx_date (calendar_date)
);

CREATE TABLE inventory_reservation (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  reservation_id VARCHAR(64) NOT NULL,
  inventory_key VARCHAR(128) NOT NULL,
  order_id VARCHAR(64) NOT NULL,
  qty INT NOT NULL,
  status VARCHAR(32) NOT NULL
    COMMENT 'RESERVED/CONFIRMED/RELEASED/EXPIRED/CANCELLED',
  expire_at DATETIME DEFAULT NULL,
  idempotency_key VARCHAR(128) NOT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  UNIQUE KEY uk_reservation_id (reservation_id),
  UNIQUE KEY uk_order_inventory (order_id, inventory_key),
  UNIQUE KEY uk_idempotency (idempotency_key)
);

CREATE TABLE inventory_ledger (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  ledger_id VARCHAR(64) NOT NULL,
  inventory_key VARCHAR(128) NOT NULL,
  order_id VARCHAR(64) DEFAULT NULL,
  event_id VARCHAR(64) DEFAULT NULL,
  change_type VARCHAR(32) NOT NULL
    COMMENT 'INBOUND/RESERVE/CONFIRM/RELEASE/REFUND/LOCK/UNLOCK/ADJUST',
  qty_delta INT NOT NULL,
  before_payload JSON DEFAULT NULL,
  after_payload JSON DEFAULT NULL,
  reason VARCHAR(256) DEFAULT NULL,
  operator_type VARCHAR(32) NOT NULL COMMENT 'SYSTEM/ORDER/OPS/SUPPLIER/RECONCILE',
  created_at DATETIME NOT NULL,
  UNIQUE KEY uk_ledger_id (ledger_id),
  UNIQUE KEY uk_event_id (event_id),
  KEY idx_inventory_time (inventory_key, created_at),
  KEY idx_order (order_id)
);

对于券码制，还要单独增加 inventory_code_pool_XX 分表。这个表不是普通库存表的附属字段，而是虚拟商品、卡密、兑换券、权益码等「唯一资源」的权威账本：一码一行、状态机驱动，Redis LIST 只保存 code_id 热数据，权威仍在 MySQL。

券码池分表：inventory_code_pool_XX

数量制库存扣减的是 available_stock，券码制库存扣减的是某一条真实存在的码。只要业务需要向用户交付一个不可重复的串码，就不能把 Redis LIST 里的字符串当成事实来源，否则会遇到三类严重问题：

• Redis 宕机、回滚或误删后，无法解释哪些码已经分配给哪个订单；
• LIST 里直接存明文券码，内存、日志、监控和排障链路都可能泄漏敏感资源；
• 取消、支付确认、发码失败、售后和过期处理没有统一状态机，极易重复发码或把已交付的码放回可售池。

推荐模型如下：

CREATE TABLE inventory_code_pool_00 (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  code_id BIGINT NOT NULL,
  batch_id VARCHAR(64) NOT NULL,
  inventory_key VARCHAR(128) NOT NULL,
  sku_id BIGINT NOT NULL,
  code_cipher VARBINARY(1024) NOT NULL COMMENT '加密后的券码或卡密',
  code_hash VARCHAR(64) NOT NULL COMMENT '去重与排查使用，不保存明文',
  status VARCHAR(32) NOT NULL
    COMMENT 'AVAILABLE/BOOKING/SOLD/LOCKED/EXPIRED/INVALID',
  reservation_id VARCHAR(64) DEFAULT NULL,
  order_id VARCHAR(64) DEFAULT NULL,
  user_id BIGINT DEFAULT NULL,
  booked_at DATETIME DEFAULT NULL,
  sold_at DATETIME DEFAULT NULL,
  expire_at DATETIME DEFAULT NULL,
  version BIGINT NOT NULL DEFAULT 0,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  UNIQUE KEY uk_code_id (code_id),
  UNIQUE KEY uk_batch_hash (batch_id, code_hash),
  KEY idx_batch_status_id (batch_id, status, id),
  KEY idx_order (order_id),
  KEY idx_reservation (reservation_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='库存券码池分表00';

分表路由通常按 batch_id 或 code_id 做一致性哈希，也可以按 inventory_key + batch_id 固定到某个分片。关键原则是：活动开始后不要改变路由规则；补货、锁码、支付确认、取消释放、对账修复都必须命中同一个权威分片。批次维度可以配合 inventory_code_batch 保存供应商、面值、有效期、导入批次、加密密钥版本、总码量和当前水位。

券码池的状态机建议收敛为：

AVAILABLE --reserve--> BOOKING --confirm/pay--> SOLD
BOOKING --cancel/timeout--> AVAILABLE
AVAILABLE --ops/supplier--> LOCKED
AVAILABLE --expire--> EXPIRED
AVAILABLE --quality_check--> INVALID

这里有一个重要约束：已发给用户或已核销链路可见的 SOLD 码，不能简单回到 AVAILABLE。退款、补发、作废应走售后和履约状态，而不是把同一串码再次投入可售池。这个约束能显著降低重复发码、用户投诉和供应商对账争议。

高并发出码链路可以这样设计：

1. 大促前按批次把可售 code_id 预热到 Redis LIST：
   inventory:code:pool:{batch_id}:{shard}

2. 下单预占时从 Redis LIST 弹出一批 code_id。

3. 应用逐个执行 MySQL CAS：
   UPDATE inventory_code_pool_XX
   SET status='BOOKING',
       reservation_id=?,
       order_id=?,
       user_id=?,
       booked_at=NOW(),
       version=version+1,
       updated_at=NOW()
   WHERE code_id=? AND status='AVAILABLE';

4. 更新成功才算锁码成功，同时写 inventory_reservation 与 inventory_ledger。

5. 更新失败说明 Redis 中是陈旧 code_id，丢弃后继续取下一个，不把 Redis 结果视为成功。

6. 支付成功后 BOOKING -> SOLD；订单取消或超时后 BOOKING -> AVAILABLE，并通过 Outbox 或补偿任务把 code_id 回填到 Redis LIST。

因此 Redis 的角色只是「热队列」：只放 code_id，不放明文码；只提升吞吐，不承担库存权威职责。Redis LIST 为空时，补货 Worker 按 idx_batch_status_id 用 id 游标分页扫描 MySQL 可用码并回填；Redis 故障后，也可以从 MySQL 的 AVAILABLE 状态全量重建热队列。监控上要同时看 MySQL 可用码数量、Redis LIST 长度、锁码 CAS 失败率、BOOKING 超时释放量和 SOLD 重复告警。

9.2.4 多维分类模型

统一库存的关键，是把品类差异拆成几个正交维度，而不是让每个品类复制一套服务。

// ManagementType：谁拥有库存事实来源
const (
	SelfManaged      = 1 // 平台自管：平台维护可用量与流水
	SupplierManaged  = 2 // 供应商管理：平台保存快照 + 同步策略
	Unlimited        = 3 // 无限库存：不维护可用量，但保留审计与风控
)

// UnitType：库存如何被扣减与表达
const (
	CodeBased     = 1 // 券码制：最小粒度为唯一 code
	QuantityBased = 2 // 数量制：最小粒度为整数数量
	TimeBased     = 3 // 时间维度：按日期 / 时段切片
	BundleBased   = 4 // 组合型：多子项联动扣减
	SeatBased     = 5 // 座位制：场次 + 座位 / 舱位
)

// DeductTiming：什么时候改变库存承诺
const (
	DeductOnOrder           = 1 // 下单预占
	DeductOnPay             = 2 // 支付后确认
	DeductOnFulfillment     = 3 // 发货 / 发码 / 出票时确认
	DeductOnSupplierConfirm = 4 // 供应商确认后确认
)

四个维度的组合决定策略路由：

InventoryStrategy =
  ManagementType
  + UnitType
  + ScopeType
  + DeductTiming

例如：

自管理 + 数量制 + GLOBAL + 下单预占
  → Redis Lua 数量扣减策略

自管理 + 券码制 + BATCH + 下单预占
  → Redis LIST 取码 + MySQL 码池状态机

供应商管理 + 时间维度 + DATE + 供应商确认
  → 本地快照 + 下单实时刷新 + supplier_booking 轮询

无限库存 + 无范围 + 支付后履约
  → 不扣库存，但写履约审计和风控流水

9.2.5 品类分类矩阵

下表将常见品类映射到通用模型。它不是为了枚举业务，而是为了帮助团队识别“这类库存难在哪里，应该选哪组技术手段”。

下面的矩阵图用“事实来源 × 单元形态”表达组合空间，具体落地时再叠加库存范围和扣减时机。

flowchart TB
  subgraph D1[事实来源 ManagementType]
    M1[SelfManaged 平台自管]
    M2[SupplierManaged 供应商管理]
    M3[Unlimited 弱库存约束]
  end

  subgraph D2[单元形态 UnitType]
    U1[Quantity 数量]
    U2[Code 券码 / 卡密]
    U3[Time 日期 / 时段]
    U4[Seat 座位 / 场次]
    U5[Bundle 组合]
  end

  M1 --> C1[实物 SKU / 本地服务 / 秒杀]
  M1 --> C2[预采购券码 / 礼品卡]
  M2 --> C3[酒店 / 票务 / 充值供应商]
  M2 --> C4[实时生成卡密]
  M3 --> C5[话费等弱库存商品]

  U1 --> C1
  U2 --> C2
  U3 --> C3
  U4 --> C3
  U5 --> C6[套餐：子项各自路由]

  style M1 fill:#e8f5e9
  style M2 fill:#e3f2fd
  style M3 fill:#fff3e0

与营销库存的关系：商品库存回答“有没有货”，营销库存回答“活动名额 / 补贴预算够不够”。秒杀等场景往往需要双扣减（商品 + 营销），本章在 9.7 节说明集成边界；营销细节见第 10 章。

9.2.6 库存创建：从商品发布到库存实例

库存系统不能只设计扣减，还要设计 库存从哪里来、什么时候创建、创建到什么粒度、失败后如何重放。商品发布只说明“这个 SKU 可以售卖”，不一定说明“库存实例已经准备好”。库存创建的目标，是把商品中心的销售契约转成库存域可扣减、可对账、可恢复的实例。

库存创建通常来自五类入口：

工程上建议把库存创建做成命令和任务，而不是在商品发布事务里直接写完所有库存行：

ProductPublished / OpsImportSubmitted / SupplierSnapshotReady
  → InventoryCreateCommand
  → inventory_create_task
  → InventoryInitWorker
  → inventory_config / inventory_balance / inventory_code_pool_XX
  → Redis 热视图预热
  → InventoryReady / InventoryCreateFailed

创建命令至少包含这些字段：

CreateInventoryCommand
├── source_type：PRODUCT_PUBLISH / OPS_IMPORT / SUPPLIER_SYNC / CODE_GENERATION
├── source_id：发布版本、导入任务、供应商批次或生码任务
├── item_id / sku_id / offer_id
├── management_type：平台自管 / 供应商管理 / 无限库存
├── unit_type：数量 / 券码 / 时间 / 座位 / 组合
├── scope_type / scope_id：GLOBAL / STORE / CITY / WAREHOUSE / DATE / CHANNEL
├── batch_id：券码批次或货品批次
├── calendar_date / time_slot：日期或时段
├── initial_quantity：初始数量
├── code_source：IMPORTED / SYSTEM_GENERATED / SUPPLIER_GENERATED
└── idempotency_key：防重复创建

任务表可以这样设计：

CREATE TABLE inventory_create_task (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  task_id VARCHAR(64) NOT NULL,
  source_type VARCHAR(32) NOT NULL
    COMMENT 'PRODUCT_PUBLISH/OPS_IMPORT/SUPPLIER_SYNC/CODE_GENERATION/CALENDAR_MATERIALIZE',
  source_id VARCHAR(128) NOT NULL,
  item_id BIGINT NOT NULL,
  sku_id BIGINT NOT NULL,
  inventory_key VARCHAR(128) NOT NULL,
  create_mode VARCHAR(32) NOT NULL
    COMMENT 'QUANTITY/CODE_IMPORT/CODE_GENERATE/TIME_STORE/SUPPLIER_SNAPSHOT',
  payload JSON NOT NULL,
  status VARCHAR(32) NOT NULL
    COMMENT 'PENDING/RUNNING/SUCCESS/FAILED/PARTIAL_SUCCESS/CANCELLED',
  retry_count INT NOT NULL DEFAULT 0,
  error_code VARCHAR(64) DEFAULT NULL,
  error_message VARCHAR(1024) DEFAULT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  UNIQUE KEY uk_task_id (task_id),
  UNIQUE KEY uk_source_inventory (source_type, source_id, inventory_key),
  KEY idx_status_updated (status, updated_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='库存创建任务';

不同库存形态的创建方式不同：

数量库存最简单，但也不应该直接改一个 stock 字段。推荐流程是：

1. 校验 SKU / Offer 是否已经发布并可售。
2. 根据 scope 生成 inventory_key。
3. 幂等创建 inventory_config。
4. Upsert inventory_balance：
   total_stock += initial_quantity
   available_stock += initial_quantity
5. 写 inventory_ledger(change_type=INBOUND 或 INIT)。
6. 刷新 Redis 热视图和搜索可售标签。

券码库存要多一个批次对象：

inventory_code_batch
├── batch_id
├── inventory_key / sku_id
├── code_source：IMPORTED / SYSTEM_GENERATED / SUPPLIER_GENERATED
├── generation_mode：PRE_GENERATED / ON_DEMAND
├── total_count / available_count
├── expire_at
├── encrypt_key_version
├── route_shard
└── status：CREATING/READY/LOCKED/EXHAUSTED/FAILED

如果是运营或供应商导入券码，Worker 要逐行做格式校验、去重、加密、哈希、分表落库，再把 code_id 批量灌入 Redis LIST。如果是系统自己生成券码，有两种模式：

• 预生成：活动开始前生成一批随机不可猜测的券码，全部进入 inventory_code_pool_XX，适合大促高并发发码。
• 按需生成：支付或履约阶段按 order_id + sku_id 幂等生成，先写入码池权威行，再展示给用户，适合低峰值或强个性化券码。

无论哪种模式，都不能只把生成出来的字符串返回给用户而不落库。正确顺序是：生成 / 导入 → 加密落 MySQL → 状态机进入 AVAILABLE 或 BOOKING → 必要时预热 Redis code_id → 发码时再解密展示。

门店、日期和时段库存则要关注“物化范围”。例如本地生活门店券可以是：

inventory_key =
  sku_id
  + scope_type=STORE
  + scope_id=store_1001
  + calendar_date=2026-05-01
  + time_slot=DINNER

平台可以提前物化未来 30 天或 90 天的库存行，也可以在首次查询 / 首次预约时懒创建。前者查询快但写放大明显；后者节省存储但需要处理并发首次创建。推荐对高流量品类提前物化，对长尾门店懒创建，并用唯一键保证同一门店同一天同一时段只创建一行。

库存创建的成功标准不是“任务跑完”，而是这些对象都进入可解释状态：

1. inventory_config 能解释策略路由；
2. inventory_balance 或 inventory_code_pool_XX 能解释可售资源；
3. inventory_ledger 能解释库存从哪里来；
4. Redis 热视图可从 MySQL 重建；
5. 搜索 / 商品聚合读模型能感知可售状态；
6. 创建失败可以按 inventory_create_task 重试、部分成功回滚或人工修复。

9.2.7 虚拟商品库存的特化

虚拟商品库存可以复用通用库存模型，但需要额外突出四个风险：

1. 发货不可逆：充值、出票、发码一旦提交供应商或展示给用户，不能简单回滚。
2. 唯一资源泄露：卡密、券码属于敏感资产，不能在日志、消息、搜索索引里明文扩散。
3. 供应商最终态晚到：平台支付成功不代表供应商履约成功，必须有 pending、confirmed、failed、manual 状态。
4. 空池与补货：预采购券码可能卖空，补货既要高效又不能重复装载同一码。

一句话总结：

虚拟商品不是“没有库存”，而是库存从仓库货架变成了数量承诺、唯一凭证、供应商额度和不可逆履约状态。

9.2.8 可售库存计算

库存系统对外暴露的不是 total_stock，而是可售判断。可售库存的计算要分管理类型：

SelfManaged:
  sellable = total_stock - booking_stock - locked_stock - sold_stock

SupplierManaged:
  sellable = min(platform_snapshot, supplier_latest_confirmation)

Unlimited:
  sellable = business_limit_or_sentinel

对于自管理库存，要维护恒等式：

total_stock = available_stock + booking_stock + locked_stock + sold_stock

对于供应商库存，平台本地的 supplier_stock 只是最后一次可见快照，不一定代表下单瞬间真实库存。因此供应商管理品类通常采用两段式：

列表页 / 详情页：
  读本地快照 + 短 TTL 缓存

创单 / 支付前：
  实时刷新或创建 supplier_booking

这样可以把“展示性能”和“交易安全”分开，避免为了列表页性能牺牲创单正确性。

9.3 库存扣减策略

9.3.1 扣减时机

扣减时机是交易体验与资损风险的权衡轴：

• 下单预占（Reserve / Book）：用户体验好（下单即锁货），但占用时长内库存不可用，需要可靠的超时释放。
• 支付后扣减（Sell on pay）：减少无效占用，更适合供应商成本高或确认链路长的品类。
• 发货扣减：实物电商更常见；数字商品平台多用前两者的组合。

工程上建议把时机写入 inventory_config.deduct_timing，由订单 / 结算编排读取，而不是散落在订单代码的 switch。

配置值与交易编排的契约：deduct_timing 只是标签，真正决定行为的是订单状态机与库存 API 的组合。推荐在内部文档中固定一张「状态 × 库存动作」表，例如：PENDING_PAYMENT → Release、PAID → Confirm、CLOSED → Release(幂等)。当同一品类在不同国家 / 不同供应商合同中扣减时机不同，用配置驱动可以避免为每个市场复制一套订单服务。

9.3.2 预占与确认

预占（Reserve） 的本质：把「可售」迁移到「已占用（booking）」状态，并保证操作原子、可幂等、可追踪。

确认（Confirm / Sell） 的本质：把「占用」迁移到「已售（sold / issued）」，并与支付成功事件对齐。

自管理数量制的状态迁移（Redis HASH 字段视角）：

available --(reserve)--> booking --(confirm)--> issued
available <---(release)--- booking

券码制则是 AVAILABLE → BOOKING → SOLD 的状态机，失败路径需要可逆。

策略模式落地（路由与编排解耦）：业务层只依赖统一的 InventoryManager（或应用服务），由它读取 inventory_config 后选择策略实现。这样「新品类接入」优先体现为 配置 + 策略类，而不是修改订单核心代码。

// InventoryStrategy 抽象了库存生命周期中可被统一编排的动作集合。
type InventoryStrategy interface {
	CheckStock(ctx context.Context, req *CheckStockReq) (*CheckStockResp, error)
	BookStock(ctx context.Context, req *BookStockReq) (*BookStockResp, error)
	UnbookStock(ctx context.Context, req *UnbookStockReq) error
	SellStock(ctx context.Context, req *SellStockReq) error
	RefundStock(ctx context.Context, req *RefundStockReq) error
}

type StrategyRouter struct{}

func (StrategyRouter) MustStrategy(cfg *InventoryConfig) (InventoryStrategy, error) {
	switch cfg.ManagementType {
	case SelfManaged:
		return NewSelfManagedStrategy(cfg), nil
	case SupplierManaged:
		return NewSupplierManagedStrategy(cfg), nil
	case Unlimited:
		return NewUnlimitedStrategy(), nil
	default:
		return nil, fmt.Errorf("unknown management_type=%d", cfg.ManagementType)
	}
}

与「营销锁定」的关系：数量制 Redis HASH 常会增加 locked 以及按 promotion_id 维度的动态字段，用于表达「活动独占库存」。商品详情页展示的可售量，与下单强校验使用的可售量，可能不是同一个聚合口径——务必在接口契约里写清楚，避免运营配置误解导致客诉。

9.3.3 超时释放

超时释放至少要回答三个问题：谁来触发？以什么为准？失败如何兜底？

常见实现组合：

1. Redis TTL / 预占记录过期：快速回收「短期锁」。
2. 延时队列：在创单时投递 delay=15m 的任务，到点检查订单是否已支付。
3. 定时扫描：扫描 PENDING_PAYMENT 且超时的订单，幂等调用库存释放接口。

下面的时序图展示「下单预占 → 支付确认 / 超时释放」的主路径（商品库存服务视角）。

sequenceDiagram
  autonumber
  participant O as 订单系统
  participant I as 库存服务
  participant R as Redis
  participant Q as 延时队列
  participant P as 支付系统

  O->>I: ReserveStock(order_id, sku, qty, ttl=15m)
  I->>R: EVAL Lua 原子扣减 available 并增加 booking
  R-->>I: OK
  I-->>O: reserved
  O->>Q: schedule ReleaseStock(order_id) @T+15m

  alt 用户在 TTL 内完成支付
    P-->>O: PaymentSuccess
    O->>I: ConfirmStock(order_id)
    I->>R: booking -= qty; issued += qty
    I-->>O: confirmed
    Note over Q: 可选：取消延时任务（若支持精确去重）
  else 超时未支付
    Q-->>I: ReleaseStock(order_id) 幂等
    I->>R: booking -= qty; available += qty
    I-->>O: released
    O-->>O: CloseOrder(timeout)
  end

与上时序图互补，建议再用 状态机 固化「预占记录」本身的生命周期（尤其是 Redis 侧 reservation:{order_id} 与 DB 影子行并存时）。下图把「可重复进入的幂等终态」标出，避免研发在「重复回调 / 重复释放」上各写一套语义。

stateDiagram-v2
  [*] --> NONE: 未创单 / 未预占
  NONE --> RESERVED: Reserve 成功\n(available↓ booking↑)
  RESERVED --> CONFIRMED: Confirm\n(booking↓ issued↑)
  RESERVED --> RELEASED: Release / 超时\n(booking↓ available↑)
  CONFIRMED --> [*]: 终态（可审计重复 Confirm）
  RELEASED --> [*]: 终态（可审计重复 Release）
  note right of RESERVED
    幂等键：order_id
    并发护栏：Lua / 版本号 / 行锁择一
  end note

关键细节：

• 幂等键：order_id 贯穿 Reserve / Confirm / Release，重复调用必须安全。
• 顺序依赖：若营销与商品双预占，失败回滚顺序应与成功顺序相反（Saga 补偿语义）。

9.3.4 超卖防护

超卖防护应分层：

1. 热路径原子性：Redis Lua 或单分片事务，保证「检查 + 扣减」不可分割。
2. 业务幂等：同一 order_id 重复确认只生效一次。
3. 冷路径校验：支付回调后，在确认库存前读取 MySQL 侧汇总做二次校验（容忍更高延迟）。
4. 对账兜底：周期任务发现 available + booking + sold 恒等式破坏或 Redis / MySQL 偏差过大，自动冻结商品并告警（见 9.5.2）。

CheckStock 与 ReserveStock 为什么要拆开？ 只读 Check 适合列表页、加购前的快速失败；但它不能保证并发下的正确性。正确做法是：创单路径必须以 Reserve 这种「读改写原子操作」为准，Check 只是辅助。否则会出现「校验时还有货，下单时被抢走」的经典竞态。

秒杀场景的 Facade（可选优化）：当商品库存与营销库存必须同事务化编排时，常规做法是订单 Saga 两步调用；在极端 QPS 下可以引入 FlashSaleInventoryFacade.CheckAndReserve 聚合接口，把限流、热点治理、重复请求拦截收敛到库存域的专用入口。注意：Facade 是性能与风控的「窄接口」，不要让它反向吞噬订单领域的编排职责。

9.4 供应商集成

供应商集成本质是 把「外部库存事实」映射为平台可售视图，并在预订 / 取消时调用供应商 API 对齐状态。

9.4.1 实时查询

适用：变化快、对超卖极度敏感（机票、部分热门票务）。

模式：

• 读路径：短 TTL 缓存 + 超时控制 + 熔断降级。
• 写路径：同步预订或异步预订（供应商返回 pending 时需轮询，见博客原文异步 booking 状态机）。

读路径的 Go 骨架（与第 16 章风格一致：先缓存、后供应商、再回写、可观测）：

// CheckSupplierStock 演示：实时查询 + 短缓存 + 异步快照（示意代码）
func (s *SupplierManagedStrategy) CheckStock(ctx context.Context, req *CheckStockReq) (*CheckStockResp, error) {
	cacheKey := fmt.Sprintf("inventory:supplier:%d:%d:%s", req.ItemID, req.SKUID, req.Date)

	// 1) 先读 Redis 缓存（例如 30s TTL：机票可更短，酒店可更长）
	if v, err := s.rdb.Get(ctx, cacheKey).Int(); err == nil {
		return &CheckStockResp{Available: int32(v), FromCache: true}, nil
	}

	// 2) 供应商调用必须带超时；失败要映射为可重试/不可重试
	ctx, cancel := context.WithTimeout(ctx, 800*time.Millisecond)
	defer cancel()

	resp, err := s.supplier.QueryStock(ctx, &SupplierQuery{
		SupplierID: req.SupplierID,
		ProductID:  req.ExternalProductID,
		Date:       req.Date,
	})
	if err != nil {
		return nil, MapSupplierErr(err) // Retryable / Fatal / Unknown
	}

	// 3) 回写缓存 + 异步落快照（快照用于运营后台、对账与熔断时的最后成功视图）
	_ = s.rdb.Set(ctx, cacheKey, resp.Stock, 30*time.Second).Err()
	go func() {
		bg, cancel := context.WithTimeout(context.Background(), 2*time.Second)
		defer cancel()
		_ = s.snapshot.Save(bg, req.ItemID, req.SKUID, req.Date, resp.Stock, "api")
	}()

	return &CheckStockResp{Available: resp.Stock, FromCache: false}, nil
}

工程要点（把「实时」变成可运营能力）：

• 缓存击穿：热点航线/场次在缓存过期瞬间会把供应商 QPS 顶满；需要单飞（singleflight）、随机抖动 TTL、以及网关层按 supplier_id 配额限流。
• 错误语义：Unknown 不要当作「0 库存」返回，否则会把用户引导到错误决策；应显式返回「暂不可校验」并由前端降级展示。
• 观测：必须记录 from_cache、supplier_latency_ms、supplier_error_class，否则线上只能看到「库存服务慢」，无法判断是供应商还是自研逻辑。

9.4.2 定时同步

适用：变化中等、可接受分钟级延迟（部分酒店库存）。

模式：

• 定时任务拉取供应商库存，写入本地 inventory 快照字段（如 supplier_stock、supplier_sync_time）。
• 读路径优先读本地快照，必要时触发「刷新任务」。

9.4.3 推送模式

适用：供应商能力较强，主动推送房态 / 价格变更。

要点：

• Webhook 入口必须鉴权、幂等、重放安全。
• 推送与定时拉取可并存：推送负责快变字段，拉取负责兜底对齐。

9.4.4 降级策略

下面的架构图对比 实时查询 与 定时同步 在读路径上的差异（简化）。

flowchart LR
  subgraph RT[实时查询路径]
    A1[用户请求] --> B1[库存服务]
    B1 --> C1{Redis 缓存命中?}
    C1 -->|是| Z1[返回缓存库存]
    C1 -->|否| D1[供应商 API]
    D1 --> E1[回写 Redis 短 TTL]
    E1 --> Z1
  end

  subgraph SCH[定时同步路径]
    J1[定时任务] --> K1[供应商批量接口]
    K1 --> L1[更新 MySQL 快照字段]
    L1 --> M1[可选：刷新 Redis 视图]
    A2[用户请求] --> B2[库存服务]
    B2 --> Z2[读本地快照 / 缓存]
  end

实践建议：同一家供应商也可能混用（例如酒店：列表页用快照，下单页强刷一次实时），关键是把策略写进配置中心而非写死在代码分支。

礼品卡横跨多种模式的启示：预采购卡密（Self + Code）、实时生成卡密（Supplier + Code）、无限库存（Unlimited）往往并存于同一业务线。统一模型的价值在于：团队可以用同一张「策略决策表」讨论边界，而不是在三个服务里分别口述规则。

异步预订（pending → confirmed）的工程清单：当供应商只能异步确认时，至少补齐以下构件：supplier_booking 映射表、可重入的轮询 worker、超时与人工介入队列、订单侧状态机联动、对账任务对「平台已占 / 供应商未确认」的专项扫描。否则极易出现「钱扣了但供应商没单」或「供应商有单但平台没单」的双向不一致。

9.5 数据一致性保证

9.5.1 Redis 与 MySQL 同步

典型路径是 「Redis 同步执行，MySQL 异步落库」：

• 同步：Lua 脚本更新 Redis 中的 available/booking/issued 或券码池。
• 异步：发送 InventoryEvent 到 Kafka，消费者批量写 inventory_balance 与 inventory_ledger。