各位开发者朋友，上次分享了结构化写作的黄金公式后，很多同学反馈需要更具象的落地方法。今天通过真实电商支付系统案例，手把手教你用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 任务
- 文档存放在 GitLab，每次修改添加标签（如
避坑指南
- 避免过度设计：初期保留防腐层，先实现核心流程
- 数据一致性：使用 RocketMQ 事务消息，补偿机制覆盖99%异常场景
- 可观测性 ：
- 埋点监控：支付成功率、接口响应时间
- 日志规范：统一格式（时间戳+服务名+请求ID+日志级别）
互动话题 ：
你在设计支付系统时遇到过哪些诡异的一致性问题？欢迎留言区分享解决方案！
工具包升级 ：
回复【支付文档模板】获取：
- 完整支付系统设计文档模板（含BPMN流程图源文件）
- 微服务拆分评估Checklist
- 异常处理策略库（覆盖20+常见场景）