【实战案例】用STAR+3W模型拆解电商支付系统设计文档

各位开发者朋友，上次分享了结构化写作的黄金公式后，很多同学反馈需要更具象的落地方法。今天通过真实电商支付系统案例，手把手教你用STAR+3W模型写出可执行的设计文档！

结构化写作的「黄金公式」

STAR原则 + 3W模型

Situation（场景）- Task（任务）- Action（行动）- Result（结果）

What（做什么）- Why（为什么）- How（怎么做）

案例背景

Situation（场景）：某电商平台日均10万笔交易，原单体系统支付模块耦合严重，新增支付方式需全量部署，稳定性不足。

Task（任务）：将支付系统拆分为独立微服务，支持支付宝/微信/银联多渠道接入，响应时间控制在200ms内。

文档拆解

1. 用STAR原则梳理需求

Situation（场景）：

现有问题：支付逻辑与订单、库存模块强耦合，每次支付方式变更需全量发布，影响系统稳定性
业务痛点：双11期间支付成功率下降15%，用户投诉激增

Task（任务）：

核心目标：解耦支付系统，实现独立部署
关键指标：支付接口QPS≥5000，响应时间≤200ms，支持每秒1000笔退款

Action（行动）：

领域划分：按支付渠道/交易类型拆分微服务（支付网关服务、渠道适配服务、交易记录服务）
技术选型：
- 通信协议：gRPC（序列化效率比REST高30%）
- 消息队列：RocketMQ（支持事务消息保证最终一致性）
- 存储方案：MySQL（交易记录）+ Redis（高频查询缓存）

Result（结果）：

支付系统独立部署，变更发布时间从8小时缩短至30分钟
支付成功率提升至99.95%，退款处理速度提升4倍

2. 用3W模型细化设计

What（做什么）：

支付系统包含3大核心服务：

支付网关服务渠道适配服务交易记录服务账户余额服务

Why（为什么）：

选择gRPC的原因：

diff 复制代码

+ 高性能（HTTP/2+Protobuf）  
+ 强类型定义（自动生成客户端代码）  
- 兼容性差（需额外维护REST网关）

How（怎么做）：

关键流程时序图（Mermaid代码）：

用户支付网关微信渠道交易记录服务发起支付请求调用统一下单接口返回预支付ID 跳转微信支付完成支付发送异步通知记录支付结果用户支付网关微信渠道交易记录服务

异常处理矩阵：

异常类型	处理策略	重试机制	通知方式
支付超时	调用查询接口确认状态	3次/5分钟	短信+邮件
渠道返回错误码	解析错误码返回友好提示	不重试	前端弹窗
数据库写入失败	记录日志并异步重试	5次/指数退避	钉钉机器人

3. 关键图表示例

业务流程图（BPMN 2.0）

bpmnDiagram participant 开始事件 participant 支付申请 participant 风控校验 participant 并行网关 participant 微信渠道 participant 银联渠道 participant 结果通知 participant 结束事件开始事件 --> 支付申请支付申请 --> 风控校验风控校验 --> 并行网关并行网关 --> 微信渠道并行网关 --> 银联渠道微信渠道 --> 并行网关银联渠道 --> 并行网关并行网关 --> 结果通知结果通知 --> 结束事件

架构分层图

复制代码

┌───────────────┐
│ 表现层 (API网关) │
├───────────────┤
│ 应用层 (支付服务) │
├───────────────┤
│ 领域层 (领域模型) │
├───────────────┤
│ 基础设施层 (MySQL/Redis) │
└───────────────┘

4. 工具落地方案

流程图绘制：
- 使用 Draw.io 绘制BPMN流程图，导出为SVG嵌入文档
- 复杂流程用 Mermaid 代码块生成（支持Markdown渲染）
技术选型对比：

维度 gRPC REST

性能优良

开发效率中（需代码生成）高

生态支持良优
版本管理：
- 文档存放在 GitLab，每次修改添加标签（如v1.0-支付系统拆分）
- 关键决策记录在 Confluence 维基，关联 Jira 任务

维度	gRPC	REST
性能	优	良
开发效率	中（需代码生成）	高
生态支持	良	优

避坑指南

避免过度设计：初期保留防腐层，先实现核心流程
数据一致性：使用 RocketMQ 事务消息，补偿机制覆盖99%异常场景
可观测性 ：
- 埋点监控：支付成功率、接口响应时间
- 日志规范：统一格式（时间戳+服务名+请求ID+日志级别）

互动话题 ：

你在设计支付系统时遇到过哪些诡异的一致性问题？欢迎留言区分享解决方案！

工具包升级 ：

回复【支付文档模板】获取：

完整支付系统设计文档模板（含BPMN流程图源文件）
微服务拆分评估Checklist
异常处理策略库（覆盖20+常见场景）