简介方案文档围绕电商平台分布式架构设计全面梳理从需求分析到技术落地的完整链路面向系统架构师、后端开发及技术负责人等需要处理高并发、海量数据的从业者。文档先说明架构设计的必要条件和优势再梳理购物、支付、物流、客服、评论等业务需求并明确核心与非核心子系统的拆分原则随后重点介绍技术架构的演进路径涵盖应用与服务器分离、缓存中间件引入、应用集群与分布式通信、数据库读写分离与分库分表、消息队列异步解耦等关键策略同时配有清晰的架构示意图。压缩包中共1个docx文档大小1.46MB内容结构完整适合按章节对照学习能帮助读者建立电商分布式架构设计的全局认知。目前已有133人学习浏览对从事电商系统规划或架构改造的技术人员具有直接的参考价值。1. 电商平台分布式架构设计文档先回答它到底要解决谁的什么问题一份命名规整的《电商平台分布式架构设计.docx》在绝大多数团队里最后都变成了三十页带彩色拓扑图的“设计摆设”——评审会翻一遍开发说看不懂运行半年后新来的同事根本不敢改。这不是画图能力的问题而是文档没有回答它该回答的问题系统在什么流量下会走到分布式这一步、每个设计决策的取舍依据是什么、故障来了系统会怎么表现、团队按这个架构能不能安全地迭代。这篇内容不讲抽象架构理论而是把一份能落地的分布式架构设计文档拆开告诉你目录怎么排、决策怎么记、容量怎么算、踩过哪些坑。适合正要自己产出设计文档的后端开发、被拉去评审架构的负责人以及想把设计资产真正沉淀下来的技术组长。2. 搭出一份能落地的文档骨架从目录设计到ADR决策记录2.1 别急着画架构图先确定文档的读者与职责我见过太多架构设计文档的第一章就是“架构愿景”“设计目标”这类正确但没用的场面话。真正动笔之前需要先想清楚这份docx的第一读者是谁。电商平台的分布式架构设计文档至少要服务三类人。后端开发看它是想知道“我这个服务该不该拆出来、数据放哪、调用谁”架构评审委员会看它是想判断“你有没有考虑过度设计、单点、容量、降级”运维和SRE看它是想得到“服务实例数、依赖关系、故障恢复手段”。同一份文档要同时满足这三种视角目录就不能是零散的技术点堆砌而要有清晰的职责分层。提示先写一段不到一百字的“文档读者与使用方式”放在目录之前。它逼你在动笔时就想清楚——这文档是给人做决策用的不是给自己做工作汇报用的。我自己常用的分层思路是第一层写背景和指标为什么做、做到什么程度第二层写架构现状与决策是什么、为什么这么选第三层写落地细节与风险怎么做、出事了怎么办。这三层对应的正好是评审者的三种现场提问顺序你为什么需要分布式、你打算怎么分、你扛不扛得住。2.2 一份可复用的目录结构从封面到降级预案下面这个结构是我在多次电商项目里收敛出来的版本它去掉了八股文式的“绪论”“国内外现状”每章都有明确的产出物。你可以直接复制到你的docx里再按项目情况增删。01 文档元信息修订历史、评审记录、状态 02 背景与目标业务规模、上线时间、增长预期 03 非功能指标QPS、RT、SLA、一致性等级 04 顶层架构与链路图用户访问主链路、数据主链路 05 架构设计决策记录ADR每条决策的状态与理由 06 服务拆分与部署视图服务清单、实例数、依赖关系 07 关键业务场景设计下单、库存扣减、支付回调、超时关单 08 缓存、MQ与分布式事务选型 09 容量测算与扩容预案 10 可观测性设计日志、指标、链路追踪、告警 11 风险清单与降级预案故障演习、应急预案 12 附录术语表、评审Checklist、待办清单这份骨架的核心心法把“设计决策记录ADR”单独拎出来作为第05章而不是让决策散落在各个技术小节里。因为评审和后来的开发最需要的其实不是“最终方案图”而是“为什么不是另一个方案”的推理过程。没有这个过程任何架构图都只是一个黑匣子。每个一级章节下我还会加一段“本章要回答的问题”比如第07章写下“下单在库存不足时是阻断还是异步排队”“支付回调丢失了怎么对账”。这能让你的docx在被评审时引导话题而不是被评审官随机翻页发问。2.3 把“为什么”写下来ADR决策记录模板光有目录还不够核心是每一条架构决策都要有标准的记录结构。我一般让每个关键决策按下面的模板写入docx### ADR-004订单超时关单采用状态机 延迟队列 状态已接受2024-11-10 影响版本v2.3.0 背景 订单创建后30分钟未支付需要自动关闭。 传统定时任务全表扫描在订单量超过1000万后 单次扫描耗时超过5分钟且对数据库造成周期性峰值压力。 决策 订单状态迁移收敛到独立状态机服务 超时事件通过分布式延迟队列触发调度层与执行层解耦 任务调度统一走 xxl-job 集群执行器按订单号取模路由。 替代方案 方案A定时任务全表扫描实现简单但扫描量随数据增长线性膨胀 方案B利用MQ消息延迟投递依赖消息队列的延迟精度存在分钟级误差 方案CRedis过期事件监听不可靠redis 不保证过期即通知 后果 正向关闭订单的时效误差从分钟级降到秒级数据库扫描压力消失。 反向需要额外维护状态机和调度集群引入新的运维组件。这个模板的好处是让决策变成可讨论、可推翻的记录——哪天业务把支付时长改成15分钟或者引入新的调度中间件你可以直接修改ADR状态为“已废弃”并追加新ADR而不是重写整份文档。架构文档这个“后悔药”机制在项目演进中价值极大。2.4 架构图的三层规范别把图画成黑匣子架构图是docx里最容易被误解的部分。很多人的架构图是把所有服务画在一张大图里密密麻麻评审时用手比划半天也说不清数据流。我一般把架构图按C4模型的思路拆成三层分别放进对应章节系统上下文图一个方框代表整个电商平台外面是用户、物流、支付网关、短信供应商。这张图放第04章目标是一分钟讲清楚系统边界。容器图按技术容器画比如Web网关、业务服务集群、MySQL集群、Redis集群、MQ集群。这层图配合第06章的部署视图让人看清物理拓扑。组件图只针对最核心的链路画比如“下单链路组件图”。组件图不要超过七到八个节点否则就继续拆分。每张图下面用三到五句话写明“这张图要回答什么问题、数据从哪来流到哪去、哪条路径是热点”。这样做最大的收益是评审官不会再拿着激光笔问“这个框是什么”而是直接进入真正的技术取舍讨论。3. 电商核心设计决策怎么写拆分、缓存与分布式事务的取舍依据3.1 服务拆分边界按领域划分而不是按技术分层电商平台的服务拆分是架构设计文档里最容易暴露水平的一章。最常见的错误是把“Controller、Service、DAO”这种技术分层当成服务边界最后拆出十几个只差名字的重复服务。正确的拆分依据应该是领域边界和变更频率而不是代码分层。我在文档里会用一个表格把服务边界讲清楚每一行回答三个问题——这个服务管什么数据、和谁通信、它为什么必须独立。服务数据职责主要调用方拆分理由商品服务商品SPU/SKU、类目、属性门户、搜索、购物车读多写少缓存命中率高独立扩容收益大库存服务可售库存、预占库存、库存流水下单、履约、售后写入压力集中需独立控制并发与锁粒度订单服务订单主数据、订单状态机用户端、支付回调、售后状态复杂需独立演进且不能因其他服务故障拖垮支付服务支付单、支付渠道配置、对账订单、财务、风控资金相关安全合规要求高审计隔离用户与营销服务用户信息、优惠券、活动下单、结算营销活动变更频繁独立部署避免频繁发版影响核心链路表格之后还需要一段决策叙述说明某两个服务为什么没有合并。比如“购物车为什么放进订单服务而不是单独拆”——因为购物车的查询和下单强依赖同一份用户会话数据拆开只会增加一次 RPC 和数据复制成本。这一段才是评审官真正想看的内容你不但知道怎么拆还知道怎么不拆。3.2 缓存一致性设计Cache-Aside是默认文档里要写三种异常电商平台的缓存设计章节默认方案是Cache-Aside旁路缓存。原因很实际它实现最简单读不到就去数据库加载再回填写的时候先更新数据库再删缓存。文档里用一段伪代码描述这个标准流程即可。// 读流程Cache-Aside Object val redis.get(key); if (val null) { val db.query(key); redis.setex(key, ttlSeconds, val); // 回填必须带过期时间 } return val; // 写流程先更新数据库再删除缓存 db.update(row); redis.del(key);这段伪代码之后必须附上对三种异常场景的说明否则文档就停留在“背八股”层面。缓存穿透查询一个不存在的商品ID每次都打到数据库。解决手段是布隆过滤器前置拦截或者把空结果也缓存短时间。文档里建议写清楚“我们选用空值缓存短TTL因为布隆过滤器需要全量ID同步维护成本高”。缓存击穿热点Key过期的一瞬间大量请求同时打到数据库。解决手段是互斥锁重建缓存或者热点Key逻辑永不过期。我会在文档里注明“采用单飞Singleflight机制合并回源请求而不是傻等锁”。缓存雪崩大量Key同时过期数据库瞬间被打爆。解决手段是TTL加随机抖动比如固定值加上0到300秒的随机数。这个要点必须写进文档因为它直接决定了Redis和MySQL之间的稳定性边界。3.3 分布式事务选型一张表说清TCC、Saga、本地消息表与幂等电商平台的分布式事务章节是整份文档里最容易“玄学化”的部分。我的经验是不要先把事务概念写一遍而是直接给一张选型表按业务场景推荐具体方案再补一段说明。场景推荐方案原因下单减库存本地消息表 MQ 最终一致库存预占允许短暂超卖后回滚不需要强一致支付回调与订单状态推进幂等校验 状态机 对账支付回调可能重复、乱序、丢失跨服务优惠券核销Saga 补偿失败可以反向执行补偿操作实现复杂度可控资金账户变动TCCTry-Confirm-Cancel资金操作必须强一致扣款与加款不能出现中间态表后面我会补一段话强调一个反直觉的经验大部分电商场景不应该走到TCC这一步。TCC虽然一致性强但开发量大、调试困难Try阶段就要准备回滚资源。如果你不是金融级转账就不要被“分布式事务”四个字吓住优先考虑“本地消息表幂等消费”的组合。幂等设计这一小节非常关键。我一般给出一个通用原则每个核心写操作带上全局唯一业务单号比如 orderId 操作码数据库加唯一索引消费端在写入前先查询状态。这个机制能让消息重复投递、支付回调重试都变成无害操作是文档里性价比最高的一部分。3.4 分布式定时任务超时关单与日终对账的调度方案电商平台里总有那么几个活儿跑起来是灾难不跑也是灾难——超时关单、日终对账、库存预占释放、营销活动过期下线。单机定时器在业务量上来之后必然翻车所以架构文档里要独立写清楚分布式调度方案。我会在文档中注明分布式定时任务调度组件业界常用 xxl-job 或 elastic-job。如果你的电商项目基于 Spring Cloud 技术栈xxl-job 是入门成本最低的选择——它自带调度中心与执行器模式支持动态调整执行时间、失败重试、任务分片。关键设计点不是“用什么组件”而是“任务怎么分片、怎么保证不重复执行”。以订单超时关单为例我建议用订单ID取模分片// xxl-job 执行器内部按订单号分片处理 shardIndex xxlJobContext.getShardIndex(); // 当前分片号 shardTotal xxlJobContext.getShardTotal(); // 总分片数 pageNo 0; while (true) { list orderMapper.selectTimeoutOrders( shardIndex, shardTotal, pageNo, pageSize); if (list.isEmpty()) break; list.forEach(o - closeOrderByStateMachine(o)); pageNo; } // 说明每台执行器只处理与自己分片匹配的订单号 // 避免多个节点同时扫到同一批订单造成状态竞争。文档里要强调的是分片算法带来的幂等性即使执行器宕机重跑同一订单也只会由同一分片处理配合数据库乐观锁版本号控制不会发生重复关单。另外一个必写细节是任务超时时间、执行线程池大小、失败重试次数这三个参数在 xxl-job 控制台里配置文档里给出推荐值单任务超时 30 分钟、调度线程池 10 个线程、重试次数 2 次。4. 把容量测算和SLA写进文档让设计从“看起来对”变成“算得出来”4.1 从峰值QPS推导副本数的计算路径架构评审最尴尬的时刻是有人问了一句“你这个集群规模怎么定出来的”。如果文档里只有“采用高峰保障”“支持弹性伸缩”这类模糊表述整个设计的可信度会瞬间崩塌。容量测算必须给出可复核的计算路径每一步都可以回溯。我通常在docx里用一段脚本体现计算过程用Python写比用Excel截图更清晰# 容量测算由业务预期推导核心服务实例数 daily_orders 1_000_000 # 日均订单 peak_factor 4.0 # 峰值系数 peak_qps daily_orders / 86400 * peak_factor print(f下单接口峰值 QPS ≈ {peak_qps:.0f}) # 每笔订单引入的内部调用放大库存支付风控营销 fanout 6 core_qps peak_qps * fanout print(f核心链路总流量 ≈ {core_qps:.0f} QPS) # 单机容量压测得到的参考值 # 4核8G实例RT 50ms单机可承载 600 QPS capacity_per_instance 600 instances core_qps / capacity_per_instance / 0.7 # 预留30%冗余 print(f建议实例数 ≈ {instances:.1f}取整为 {int(instances) 1} 台)脚本后面必须解释每个数字的来源否则仍然等于拍脑袋。日均订单量来自业务部门预期峰值系数按电商大促规律取3到5倍平时内部调用放大系数来自时序图里的调用次数统计单机容量来自压测报告不是估的。文档里我会加一条规范所有容量测算必须标注“输入来源”比如“下单QPS来自2024年双11压测报告”这样评审时可以直接调出报告核对。4.2 数据库层的瓶颈与分库分表触发线很多架构文档把容量全算在应用层到了数据库只写一句“采用读写分离、分库分表”完全不提触发线和预估水位。我一般把数据库瓶颈单独写一节给出一组明确的量化参考。单机MySQL在标准配置、主从同步开启的情况下写入吞吐量稳定在 3000 到 5000 TPS读吞吐量在有索引命中时能到 1 万以上 QPS。订单表、库存流水表这类写多读少的核心表当单表行数超过两千万或者写入QPS持续超过单库能力时就需要分库分表。订单表按 user_id 或 order_id 取模分片库存流水表按时间分区更合理。docx里的容量表建议给出每个核心库的未来12个月预估水位数据库当前行数月增长12个月后预估触发分片的时间点订单库800万100万/月2000万第10个月达到单表阈值库存流水库1500万200万/月3900万第4个月就要准备分表用户库500万20万/月740万暂不分片加缓存即可这张表比任何说教都管用。评审官一眼能看到哪张表是定时炸弹哪张表可以缓一缓。文档还应该注明分库分表中间件的选型方向以及分片键选择的理由——订单表用 order_id 作为分片键是因为核心查询都带着订单号如果按 user_id 分片订单详情页按订单号查时就成了全库扫。4.3 SLA参数表可用率、P99延迟、RTO/RPO怎么写分布式架构设计的最后一块硬骨头是把“目标”写清楚。很多文档只写“保证系统高可用”“追求低延迟”这种话等于没写。SLA一定要数字化并且要区分不同业务等级。我会在docx里放一张SLA参数表按业务重要性分级业务链路可用率目标P99延迟目标RTO恢复时间RPO数据丢失容忍商品浏览99.9%200ms30分钟分钟级可接受下单结算99.99%500ms5分钟秒级订单库不能丢支付回调99.99%1s5分钟零丢失售后/退款99.9%2s30分钟分钟级RTO和RPO这两个概念有时候会成为文档的扣分点。RTO是故障后恢复服务需要多长时间RPO是故障期间能容忍丢多少数据。下单链路RPO定秒级意味着必须开启半同步复制或组复制不能把宝全押在异步主从上。文档里写清楚这个理由比罗列一堆中间件名字有说服力得多。5. 架构设计文档常见翻车现场五条血泪避坑记录5.1 现象架构图画满一屏评审官却提不出问题有些文档放了一张包含几十个服务的大型拓扑图把所有细节都堆在一起。评审会上没人说话不是因为方案完美而是大家根本看不清、不知道从哪问起最后草草通过埋下一堆雷。原因图没有与决策目标绑定。架构图的功能不是展示信息而是聚焦一个具体的推演问题比如“下单高峰期的流量怎么走”。解决每张图限定七到八个节点图下方明确写“此图回答的问题”。大图拆成链路图、部署图、状态图多张分布在对应章节别贪多。评审时按章节引导先看链路再看状态最后看部署。5.2 现象技术选型章节变成“中间件功能对比”的产品说明书文档里出现大段“RocketMQ 支持事务消息、Kafka 支持高吞吐、RabbitMQ 支持多种路由策略”然后没有任何结论或者结论是“综合考虑我们选择RocketMQ”但没说为什么排除另外两个。原因把资料调研直接复制成了设计产出没有把选型与业务约束挂钩。解决选型章节写成“约束驱动的决策表”。先列业务约束比如“需要事务消息”“平均消息大小 2KB”“消费端允许重复投递但必须有序”再写每个候选方案是否满足约束最后给出结论和验证方法。验证方法可以是压测报告或POC结论不能空着。5.3 现象把API接口列表当成设计文档主体整份docx最有技术含量的是“订单服务接口定义”章节列了二十个接口的请求响应示例但跳过了状态流转、超时重试、数据一致性这些更关键的内容。原因写文档的人把设计理解成了接口定义或者为了凑篇幅直接贴代码。解决API定义放附录正文只保留时序描述。用文字加序号把下单流程写清楚“调用方提交订单 → 订单服务创建待支付状态 → 发本地消息 → 库存服务预占 → 回调订单中心 → 超时未支付由延迟任务关闭”。状态机和异常分支比接口签名重要得多。5.4 现象文档改完三版后和线上代码已经对不上评审意见改了三轮但架构文档里的服务依赖、MQ主题名、表结构早就过时了。开发照着文档里的旧调用关系做开发上线前才发现货不对板只能返工。原因没有把文档纳入变更管理流程谁都可以改改了没有记录。解决docx里强制写修订记录表每次变更记录日期、作者、变更章节、变更原因。更彻底的做法是把架构设计文档和代码仓库绑定修改文档要提Merge Request评审通过才能合入。ADR状态迁移也要同步更新——已接受的ADR如果被推翻必须有对应的新ADR来承接。5.5 现象容量测算是“拍脑袋三连”三个数字对不上文档里写了日均订单100万但数据库预估只给了2万行增长缓存容量又按日活1000万估。三个数字互相矛盾评审官一眼就能抓出漏洞。原因每个数字都来自不同的人或不同的时点没有人做全局校验。解决容量测算必须带输入来源和处理公式数据口径统一由一个人负责。我用一个简单的检查习惯把所有测算数字汇总成一张总量表对比业务DAU、日均订单、峰值QPS、存储增长四行数字看增长倍数是否一致。如果不一致要么是取错了口径要么是某个估算漏掉了系数。6. 让文档活着从评审通过到持续有效的架构治理架构设计文档最容易犯的最后一个错误是把“评审通过”当成终点。评审通过只是这份docx的起点真正有价值的是它能在系统演进的几年里持续被使用、被挑战、被修订。我自己的工作习惯是给每一份架构文档配一张“ADR索引表”挂在文档第05章的首页表格里列出所有ADR的编号、主题、当前状态已接受/已废弃/被替代。每次技术方案讨论先看索引表如果问题已经有ADR覆盖直接引用不再重复讨论。新决策产生时先补索引表再约评审这样文档的演进历史就是清晰的脉络。另外一个更进阶的做法是把架构设计文档和监控系统绑定。文档里每一个SLA指标、每一个容量预警线都应该对应一个可查询的监控面板。我在实际项目中会建一张“架构文档到监控面板”的映射表比如“订单库水位”对应Grafana面板上的分片容量图“P99延迟”对应核心链路APM报告。版本迭代时哪项指标恶化直接追溯到对应的架构决策记录判断是当初设计不合理还是执行走样这比靠感觉排查问题靠谱得多。最后说一个我踩过很多次的教训架构文档的更新频率应该和代码发版节奏一致至少保证一个迭代周期内文档和线上架构没有结构性偏差。别等到大促复盘时才想起来翻文档——那时候架构已经演进得连作者自己都不认识了。把文档当成团队共同维护的资产而不是某个人一次性交付的作业它才能真正发挥“设计决策的记录器”的作用。希望这些拆解和避坑经验能帮到你把下一份架构设计文档从摆设变成团队里真正值得反复翻阅的东西。本文还有配套的精品资源点击获取 电商平台分布式架构设计文档：从决策记录到容量测算落地
简介方案文档围绕电商平台分布式架构设计全面梳理从需求分析到技术落地的完整链路面向系统架构师、后端开发及技术负责人等需要处理高并发、海量数据的从业者。文档先说明架构设计的必要条件和优势再梳理购物、支付、物流、客服、评论等业务需求并明确核心与非核心子系统的拆分原则随后重点介绍技术架构的演进路径涵盖应用与服务器分离、缓存中间件引入、应用集群与分布式通信、数据库读写分离与分库分表、消息队列异步解耦等关键策略同时配有清晰的架构示意图。压缩包中共1个docx文档大小1.46MB内容结构完整适合按章节对照学习能帮助读者建立电商分布式架构设计的全局认知。目前已有133人学习浏览对从事电商系统规划或架构改造的技术人员具有直接的参考价值。1. 电商平台分布式架构设计文档先回答它到底要解决谁的什么问题一份命名规整的《电商平台分布式架构设计.docx》在绝大多数团队里最后都变成了三十页带彩色拓扑图的“设计摆设”——评审会翻一遍开发说看不懂运行半年后新来的同事根本不敢改。这不是画图能力的问题而是文档没有回答它该回答的问题系统在什么流量下会走到分布式这一步、每个设计决策的取舍依据是什么、故障来了系统会怎么表现、团队按这个架构能不能安全地迭代。这篇内容不讲抽象架构理论而是把一份能落地的分布式架构设计文档拆开告诉你目录怎么排、决策怎么记、容量怎么算、踩过哪些坑。适合正要自己产出设计文档的后端开发、被拉去评审架构的负责人以及想把设计资产真正沉淀下来的技术组长。2. 搭出一份能落地的文档骨架从目录设计到ADR决策记录2.1 别急着画架构图先确定文档的读者与职责我见过太多架构设计文档的第一章就是“架构愿景”“设计目标”这类正确但没用的场面话。真正动笔之前需要先想清楚这份docx的第一读者是谁。电商平台的分布式架构设计文档至少要服务三类人。后端开发看它是想知道“我这个服务该不该拆出来、数据放哪、调用谁”架构评审委员会看它是想判断“你有没有考虑过度设计、单点、容量、降级”运维和SRE看它是想得到“服务实例数、依赖关系、故障恢复手段”。同一份文档要同时满足这三种视角目录就不能是零散的技术点堆砌而要有清晰的职责分层。提示先写一段不到一百字的“文档读者与使用方式”放在目录之前。它逼你在动笔时就想清楚——这文档是给人做决策用的不是给自己做工作汇报用的。我自己常用的分层思路是第一层写背景和指标为什么做、做到什么程度第二层写架构现状与决策是什么、为什么这么选第三层写落地细节与风险怎么做、出事了怎么办。这三层对应的正好是评审者的三种现场提问顺序你为什么需要分布式、你打算怎么分、你扛不扛得住。2.2 一份可复用的目录结构从封面到降级预案下面这个结构是我在多次电商项目里收敛出来的版本它去掉了八股文式的“绪论”“国内外现状”每章都有明确的产出物。你可以直接复制到你的docx里再按项目情况增删。01 文档元信息修订历史、评审记录、状态 02 背景与目标业务规模、上线时间、增长预期 03 非功能指标QPS、RT、SLA、一致性等级 04 顶层架构与链路图用户访问主链路、数据主链路 05 架构设计决策记录ADR每条决策的状态与理由 06 服务拆分与部署视图服务清单、实例数、依赖关系 07 关键业务场景设计下单、库存扣减、支付回调、超时关单 08 缓存、MQ与分布式事务选型 09 容量测算与扩容预案 10 可观测性设计日志、指标、链路追踪、告警 11 风险清单与降级预案故障演习、应急预案 12 附录术语表、评审Checklist、待办清单这份骨架的核心心法把“设计决策记录ADR”单独拎出来作为第05章而不是让决策散落在各个技术小节里。因为评审和后来的开发最需要的其实不是“最终方案图”而是“为什么不是另一个方案”的推理过程。没有这个过程任何架构图都只是一个黑匣子。每个一级章节下我还会加一段“本章要回答的问题”比如第07章写下“下单在库存不足时是阻断还是异步排队”“支付回调丢失了怎么对账”。这能让你的docx在被评审时引导话题而不是被评审官随机翻页发问。2.3 把“为什么”写下来ADR决策记录模板光有目录还不够核心是每一条架构决策都要有标准的记录结构。我一般让每个关键决策按下面的模板写入docx### ADR-004订单超时关单采用状态机 延迟队列 状态已接受2024-11-10 影响版本v2.3.0 背景 订单创建后30分钟未支付需要自动关闭。 传统定时任务全表扫描在订单量超过1000万后 单次扫描耗时超过5分钟且对数据库造成周期性峰值压力。 决策 订单状态迁移收敛到独立状态机服务 超时事件通过分布式延迟队列触发调度层与执行层解耦 任务调度统一走 xxl-job 集群执行器按订单号取模路由。 替代方案 方案A定时任务全表扫描实现简单但扫描量随数据增长线性膨胀 方案B利用MQ消息延迟投递依赖消息队列的延迟精度存在分钟级误差 方案CRedis过期事件监听不可靠redis 不保证过期即通知 后果 正向关闭订单的时效误差从分钟级降到秒级数据库扫描压力消失。 反向需要额外维护状态机和调度集群引入新的运维组件。这个模板的好处是让决策变成可讨论、可推翻的记录——哪天业务把支付时长改成15分钟或者引入新的调度中间件你可以直接修改ADR状态为“已废弃”并追加新ADR而不是重写整份文档。架构文档这个“后悔药”机制在项目演进中价值极大。2.4 架构图的三层规范别把图画成黑匣子架构图是docx里最容易被误解的部分。很多人的架构图是把所有服务画在一张大图里密密麻麻评审时用手比划半天也说不清数据流。我一般把架构图按C4模型的思路拆成三层分别放进对应章节系统上下文图一个方框代表整个电商平台外面是用户、物流、支付网关、短信供应商。这张图放第04章目标是一分钟讲清楚系统边界。容器图按技术容器画比如Web网关、业务服务集群、MySQL集群、Redis集群、MQ集群。这层图配合第06章的部署视图让人看清物理拓扑。组件图只针对最核心的链路画比如“下单链路组件图”。组件图不要超过七到八个节点否则就继续拆分。每张图下面用三到五句话写明“这张图要回答什么问题、数据从哪来流到哪去、哪条路径是热点”。这样做最大的收益是评审官不会再拿着激光笔问“这个框是什么”而是直接进入真正的技术取舍讨论。3. 电商核心设计决策怎么写拆分、缓存与分布式事务的取舍依据3.1 服务拆分边界按领域划分而不是按技术分层电商平台的服务拆分是架构设计文档里最容易暴露水平的一章。最常见的错误是把“Controller、Service、DAO”这种技术分层当成服务边界最后拆出十几个只差名字的重复服务。正确的拆分依据应该是领域边界和变更频率而不是代码分层。我在文档里会用一个表格把服务边界讲清楚每一行回答三个问题——这个服务管什么数据、和谁通信、它为什么必须独立。服务数据职责主要调用方拆分理由商品服务商品SPU/SKU、类目、属性门户、搜索、购物车读多写少缓存命中率高独立扩容收益大库存服务可售库存、预占库存、库存流水下单、履约、售后写入压力集中需独立控制并发与锁粒度订单服务订单主数据、订单状态机用户端、支付回调、售后状态复杂需独立演进且不能因其他服务故障拖垮支付服务支付单、支付渠道配置、对账订单、财务、风控资金相关安全合规要求高审计隔离用户与营销服务用户信息、优惠券、活动下单、结算营销活动变更频繁独立部署避免频繁发版影响核心链路表格之后还需要一段决策叙述说明某两个服务为什么没有合并。比如“购物车为什么放进订单服务而不是单独拆”——因为购物车的查询和下单强依赖同一份用户会话数据拆开只会增加一次 RPC 和数据复制成本。这一段才是评审官真正想看的内容你不但知道怎么拆还知道怎么不拆。3.2 缓存一致性设计Cache-Aside是默认文档里要写三种异常电商平台的缓存设计章节默认方案是Cache-Aside旁路缓存。原因很实际它实现最简单读不到就去数据库加载再回填写的时候先更新数据库再删缓存。文档里用一段伪代码描述这个标准流程即可。// 读流程Cache-Aside Object val redis.get(key); if (val null) { val db.query(key); redis.setex(key, ttlSeconds, val); // 回填必须带过期时间 } return val; // 写流程先更新数据库再删除缓存 db.update(row); redis.del(key);这段伪代码之后必须附上对三种异常场景的说明否则文档就停留在“背八股”层面。缓存穿透查询一个不存在的商品ID每次都打到数据库。解决手段是布隆过滤器前置拦截或者把空结果也缓存短时间。文档里建议写清楚“我们选用空值缓存短TTL因为布隆过滤器需要全量ID同步维护成本高”。缓存击穿热点Key过期的一瞬间大量请求同时打到数据库。解决手段是互斥锁重建缓存或者热点Key逻辑永不过期。我会在文档里注明“采用单飞Singleflight机制合并回源请求而不是傻等锁”。缓存雪崩大量Key同时过期数据库瞬间被打爆。解决手段是TTL加随机抖动比如固定值加上0到300秒的随机数。这个要点必须写进文档因为它直接决定了Redis和MySQL之间的稳定性边界。3.3 分布式事务选型一张表说清TCC、Saga、本地消息表与幂等电商平台的分布式事务章节是整份文档里最容易“玄学化”的部分。我的经验是不要先把事务概念写一遍而是直接给一张选型表按业务场景推荐具体方案再补一段说明。场景推荐方案原因下单减库存本地消息表 MQ 最终一致库存预占允许短暂超卖后回滚不需要强一致支付回调与订单状态推进幂等校验 状态机 对账支付回调可能重复、乱序、丢失跨服务优惠券核销Saga 补偿失败可以反向执行补偿操作实现复杂度可控资金账户变动TCCTry-Confirm-Cancel资金操作必须强一致扣款与加款不能出现中间态表后面我会补一段话强调一个反直觉的经验大部分电商场景不应该走到TCC这一步。TCC虽然一致性强但开发量大、调试困难Try阶段就要准备回滚资源。如果你不是金融级转账就不要被“分布式事务”四个字吓住优先考虑“本地消息表幂等消费”的组合。幂等设计这一小节非常关键。我一般给出一个通用原则每个核心写操作带上全局唯一业务单号比如 orderId 操作码数据库加唯一索引消费端在写入前先查询状态。这个机制能让消息重复投递、支付回调重试都变成无害操作是文档里性价比最高的一部分。3.4 分布式定时任务超时关单与日终对账的调度方案电商平台里总有那么几个活儿跑起来是灾难不跑也是灾难——超时关单、日终对账、库存预占释放、营销活动过期下线。单机定时器在业务量上来之后必然翻车所以架构文档里要独立写清楚分布式调度方案。我会在文档中注明分布式定时任务调度组件业界常用 xxl-job 或 elastic-job。如果你的电商项目基于 Spring Cloud 技术栈xxl-job 是入门成本最低的选择——它自带调度中心与执行器模式支持动态调整执行时间、失败重试、任务分片。关键设计点不是“用什么组件”而是“任务怎么分片、怎么保证不重复执行”。以订单超时关单为例我建议用订单ID取模分片// xxl-job 执行器内部按订单号分片处理 shardIndex xxlJobContext.getShardIndex(); // 当前分片号 shardTotal xxlJobContext.getShardTotal(); // 总分片数 pageNo 0; while (true) { list orderMapper.selectTimeoutOrders( shardIndex, shardTotal, pageNo, pageSize); if (list.isEmpty()) break; list.forEach(o - closeOrderByStateMachine(o)); pageNo; } // 说明每台执行器只处理与自己分片匹配的订单号 // 避免多个节点同时扫到同一批订单造成状态竞争。文档里要强调的是分片算法带来的幂等性即使执行器宕机重跑同一订单也只会由同一分片处理配合数据库乐观锁版本号控制不会发生重复关单。另外一个必写细节是任务超时时间、执行线程池大小、失败重试次数这三个参数在 xxl-job 控制台里配置文档里给出推荐值单任务超时 30 分钟、调度线程池 10 个线程、重试次数 2 次。4. 把容量测算和SLA写进文档让设计从“看起来对”变成“算得出来”4.1 从峰值QPS推导副本数的计算路径架构评审最尴尬的时刻是有人问了一句“你这个集群规模怎么定出来的”。如果文档里只有“采用高峰保障”“支持弹性伸缩”这类模糊表述整个设计的可信度会瞬间崩塌。容量测算必须给出可复核的计算路径每一步都可以回溯。我通常在docx里用一段脚本体现计算过程用Python写比用Excel截图更清晰# 容量测算由业务预期推导核心服务实例数 daily_orders 1_000_000 # 日均订单 peak_factor 4.0 # 峰值系数 peak_qps daily_orders / 86400 * peak_factor print(f下单接口峰值 QPS ≈ {peak_qps:.0f}) # 每笔订单引入的内部调用放大库存支付风控营销 fanout 6 core_qps peak_qps * fanout print(f核心链路总流量 ≈ {core_qps:.0f} QPS) # 单机容量压测得到的参考值 # 4核8G实例RT 50ms单机可承载 600 QPS capacity_per_instance 600 instances core_qps / capacity_per_instance / 0.7 # 预留30%冗余 print(f建议实例数 ≈ {instances:.1f}取整为 {int(instances) 1} 台)脚本后面必须解释每个数字的来源否则仍然等于拍脑袋。日均订单量来自业务部门预期峰值系数按电商大促规律取3到5倍平时内部调用放大系数来自时序图里的调用次数统计单机容量来自压测报告不是估的。文档里我会加一条规范所有容量测算必须标注“输入来源”比如“下单QPS来自2024年双11压测报告”这样评审时可以直接调出报告核对。4.2 数据库层的瓶颈与分库分表触发线很多架构文档把容量全算在应用层到了数据库只写一句“采用读写分离、分库分表”完全不提触发线和预估水位。我一般把数据库瓶颈单独写一节给出一组明确的量化参考。单机MySQL在标准配置、主从同步开启的情况下写入吞吐量稳定在 3000 到 5000 TPS读吞吐量在有索引命中时能到 1 万以上 QPS。订单表、库存流水表这类写多读少的核心表当单表行数超过两千万或者写入QPS持续超过单库能力时就需要分库分表。订单表按 user_id 或 order_id 取模分片库存流水表按时间分区更合理。docx里的容量表建议给出每个核心库的未来12个月预估水位数据库当前行数月增长12个月后预估触发分片的时间点订单库800万100万/月2000万第10个月达到单表阈值库存流水库1500万200万/月3900万第4个月就要准备分表用户库500万20万/月740万暂不分片加缓存即可这张表比任何说教都管用。评审官一眼能看到哪张表是定时炸弹哪张表可以缓一缓。文档还应该注明分库分表中间件的选型方向以及分片键选择的理由——订单表用 order_id 作为分片键是因为核心查询都带着订单号如果按 user_id 分片订单详情页按订单号查时就成了全库扫。4.3 SLA参数表可用率、P99延迟、RTO/RPO怎么写分布式架构设计的最后一块硬骨头是把“目标”写清楚。很多文档只写“保证系统高可用”“追求低延迟”这种话等于没写。SLA一定要数字化并且要区分不同业务等级。我会在docx里放一张SLA参数表按业务重要性分级业务链路可用率目标P99延迟目标RTO恢复时间RPO数据丢失容忍商品浏览99.9%200ms30分钟分钟级可接受下单结算99.99%500ms5分钟秒级订单库不能丢支付回调99.99%1s5分钟零丢失售后/退款99.9%2s30分钟分钟级RTO和RPO这两个概念有时候会成为文档的扣分点。RTO是故障后恢复服务需要多长时间RPO是故障期间能容忍丢多少数据。下单链路RPO定秒级意味着必须开启半同步复制或组复制不能把宝全押在异步主从上。文档里写清楚这个理由比罗列一堆中间件名字有说服力得多。5. 架构设计文档常见翻车现场五条血泪避坑记录5.1 现象架构图画满一屏评审官却提不出问题有些文档放了一张包含几十个服务的大型拓扑图把所有细节都堆在一起。评审会上没人说话不是因为方案完美而是大家根本看不清、不知道从哪问起最后草草通过埋下一堆雷。原因图没有与决策目标绑定。架构图的功能不是展示信息而是聚焦一个具体的推演问题比如“下单高峰期的流量怎么走”。解决每张图限定七到八个节点图下方明确写“此图回答的问题”。大图拆成链路图、部署图、状态图多张分布在对应章节别贪多。评审时按章节引导先看链路再看状态最后看部署。5.2 现象技术选型章节变成“中间件功能对比”的产品说明书文档里出现大段“RocketMQ 支持事务消息、Kafka 支持高吞吐、RabbitMQ 支持多种路由策略”然后没有任何结论或者结论是“综合考虑我们选择RocketMQ”但没说为什么排除另外两个。原因把资料调研直接复制成了设计产出没有把选型与业务约束挂钩。解决选型章节写成“约束驱动的决策表”。先列业务约束比如“需要事务消息”“平均消息大小 2KB”“消费端允许重复投递但必须有序”再写每个候选方案是否满足约束最后给出结论和验证方法。验证方法可以是压测报告或POC结论不能空着。5.3 现象把API接口列表当成设计文档主体整份docx最有技术含量的是“订单服务接口定义”章节列了二十个接口的请求响应示例但跳过了状态流转、超时重试、数据一致性这些更关键的内容。原因写文档的人把设计理解成了接口定义或者为了凑篇幅直接贴代码。解决API定义放附录正文只保留时序描述。用文字加序号把下单流程写清楚“调用方提交订单 → 订单服务创建待支付状态 → 发本地消息 → 库存服务预占 → 回调订单中心 → 超时未支付由延迟任务关闭”。状态机和异常分支比接口签名重要得多。5.4 现象文档改完三版后和线上代码已经对不上评审意见改了三轮但架构文档里的服务依赖、MQ主题名、表结构早就过时了。开发照着文档里的旧调用关系做开发上线前才发现货不对板只能返工。原因没有把文档纳入变更管理流程谁都可以改改了没有记录。解决docx里强制写修订记录表每次变更记录日期、作者、变更章节、变更原因。更彻底的做法是把架构设计文档和代码仓库绑定修改文档要提Merge Request评审通过才能合入。ADR状态迁移也要同步更新——已接受的ADR如果被推翻必须有对应的新ADR来承接。5.5 现象容量测算是“拍脑袋三连”三个数字对不上文档里写了日均订单100万但数据库预估只给了2万行增长缓存容量又按日活1000万估。三个数字互相矛盾评审官一眼就能抓出漏洞。原因每个数字都来自不同的人或不同的时点没有人做全局校验。解决容量测算必须带输入来源和处理公式数据口径统一由一个人负责。我用一个简单的检查习惯把所有测算数字汇总成一张总量表对比业务DAU、日均订单、峰值QPS、存储增长四行数字看增长倍数是否一致。如果不一致要么是取错了口径要么是某个估算漏掉了系数。6. 让文档活着从评审通过到持续有效的架构治理架构设计文档最容易犯的最后一个错误是把“评审通过”当成终点。评审通过只是这份docx的起点真正有价值的是它能在系统演进的几年里持续被使用、被挑战、被修订。我自己的工作习惯是给每一份架构文档配一张“ADR索引表”挂在文档第05章的首页表格里列出所有ADR的编号、主题、当前状态已接受/已废弃/被替代。每次技术方案讨论先看索引表如果问题已经有ADR覆盖直接引用不再重复讨论。新决策产生时先补索引表再约评审这样文档的演进历史就是清晰的脉络。另外一个更进阶的做法是把架构设计文档和监控系统绑定。文档里每一个SLA指标、每一个容量预警线都应该对应一个可查询的监控面板。我在实际项目中会建一张“架构文档到监控面板”的映射表比如“订单库水位”对应Grafana面板上的分片容量图“P99延迟”对应核心链路APM报告。版本迭代时哪项指标恶化直接追溯到对应的架构决策记录判断是当初设计不合理还是执行走样这比靠感觉排查问题靠谱得多。最后说一个我踩过很多次的教训架构文档的更新频率应该和代码发版节奏一致至少保证一个迭代周期内文档和线上架构没有结构性偏差。别等到大促复盘时才想起来翻文档——那时候架构已经演进得连作者自己都不认识了。把文档当成团队共同维护的资产而不是某个人一次性交付的作业它才能真正发挥“设计决策的记录器”的作用。希望这些拆解和避坑经验能帮到你把下一份架构设计文档从摆设变成团队里真正值得反复翻阅的东西。本文还有配套的精品资源点击获取