git-learn/skill-workbench/generated-skills/skills/value-dig/assets/深度模板/设计思路与取舍模板.md

⟨主题⟩ · 设计思路与取舍（复盘）（S4 产物 ②）

视角：第一人称复盘——我拿到「⟨需求名⟩」这个需求时，是怎么想、怎么设计、怎么取舍、预判会遇到什么问题的。贴合现有实现，末尾给改进建议与可直接口述的版本。 配套文档：功能点见同目录《⟨主题⟩-功能点清单.md》；⟨可选的关联文档⟩ 说明：文中「我会这样想」是设计时的推理；「实际做法」是代码里的真实实现，两者不一致处必须标出。 路径简写：⟨简写⟩/ = ⟨真实路径⟩

---

0. 我拿到需求，先不写代码：把问题定义清楚

需求的一句话：⟨…⟩

我第一件事是承认 N 个事实，它们决定了后面所有设计：

1. ⟨例：对方的回答不是二元的⟩。 ⟨…⟩
2. ⟨例：几种失败的"可逆性"不同⟩。 ⟨…⟩
3. ⟨例：我没法从"失败"这个现象本身推出可逆性⟩。 ⟨…⟩

由此我定下 N 条不变量（当成验收标准）：

• 不变量一：⟨例：只有确定对方没接单才退款⟩——⟨为什么⟩；
• 不变量二：⟨例：不确定的失败不能当成失败处理⟩——⟨为什么⟩；
• 不变量三：⟨例：每一种失败都必须有归属⟩——⟨为什么⟩。

再看 N 个我不能改变的前提：⟨省侧是权威 · 对外调用有副作用 · 没有跨系统事务 · …⟩

结论：⟨这不是"加个 try-catch 再套个重试框架"的需求，而是「把异常翻译成后果」的需求。⟩——这句是我做取舍时反复回到的锚点。

---

1. 我怎么拆这个需求

第一刀，我按「⟨拆解维度⟩」拆，不按「⟨被否决的维度⟩」拆。

为什么否决另一个维度	⟨例：按商品类型拆会得到三块，但三种商品的前置动作不同、汇合点却是同一个；各写一套会得到三份可能走偏的代码⟩

拆完是 ⟨N⟩ 条路 + ⟨N⟩ 个汇合点：

路径	⟨前置动作⟩	⟨性质⟩	风险
⟨…⟩		异步 / 同步

第二刀，我找「⟨关键定位决策⟩」，这是本需求最关键的一个决策。

我的判断是：⟨…⟩。理由：⟨只有那一层同时拿得到 X 和 Y；再往上一层只能看到一个已被包装过的异常，原始信息已经丢了⟩。

实际做法与我的判断是否一致：⟨是 / 否⟩，证据 ⟨路径:行号⟩。

这个决策的代价：⟨例：调用层要维护两套调用方式；推广不全会造成覆盖面缺口（实际就漏了）⟩。

---

2. 我的设计主线：⟨一句话概括主线⟩

⟨这是我做的最核心的一个决定：不给 A/B/C 各写一套处理，而是让它们沿一条固定的链往下走，每层只做一件事。⟩

① ⟨层名（职责）⟩ → ② ⟨层名（职责）⟩ → ③ ⟨层名（职责）⟩ → ④ ⟨层名（职责）⟩

⟨N⟩ 层不是我拍脑袋凑的，是从"上一版为什么会漏"反推出来的——每层都对着一个旧实现的具体病灶：

层	旧实现的病灶	我的做法	为什么必须在这一层做
①		⟨路径:行号⟩	⟨信息只在最底层存在，越往上越不可恢复⟩
②
③
④

flowchart TD
    A["⟨入口⟩"] --> B["① ⟨层⟩"]
    B --> C{"② ⟨层⟩"}
    C -->|"⟨…⟩"| D["③ ⟨层⟩"]
    C -->|"⟨…⟩"| E["③ ⟨层⟩"]
    D --> F["④ ⟨归集⟩"]
    E --> F
    F -->|"⟨可逆⟩"| G["⟨处置⟩"]
    F -->|"⟨不确定⟩"| H["⟨处置⟩"]

2.1 ⟨N⟩ 重判断，才是这个设计的真正内容（标题按实际重数写，如「三重判断…」）

比"N 层"更重要的是层里做的判断——它们才是经验，层只是载体。

判断一：⟨…⟩

⟨用收益 × 概率算的：…⟩ 关键点是"不做什么"比"做什么"更难做对——⟨因为框架默认什么都做⟩。

判断二：⟨…⟩

⟨…⟩ 代价必须自己扛：⟨你关掉了 X，就必须自己承担 Y 的责任。⟩

判断三：⟨…⟩

⟨…⟩ 为什么"⟨反面做法⟩"是错的：⟨…⟩

还有一条我特意保留的例外：⟨…⟩——因为 ⟨…⟩。

2.2 ⟨独立工具/组件名⟩ 为什么要写成一个独立⟨工具/组件⟩（若无可删本节）

⟨它看着简单，但它是整个 ⟨机制⟩ 的地基——判错一次，方向就错，后面全走偏。⟩

1. 精确匹配 ⟨…⟩；
2. 兜底模糊匹配 ⟨…⟩；
3. 逐层剥 cause——⟨因为异常常被框架层层包装，真实原因往往在第三、四层⟩。

这里的取舍我很清楚：⟨选了"宁可多试一次"——因为重试的成本（多一次调用）远低于漏重试的成本（一单卡死）⟩。

---

3. 逐环节决策复盘

#	当时的问题	我的选择	为什么	代价 / 风险
1	⟨…⟩
2
3
…

代价/风险列不可空——只讲选择不讲代价，就等于没做取舍。

---

4. 我预判会遇到的问题（拿到需求时就能想到的）

1. ⟨…⟩。 ⟨…⟩
2. ⟨…⟩。 ⟨…⟩
3. ⟨…⟩。 ⟨这是我设计时预判到了却仍然漏掉的一条⟩

---

5. 我做对的 ⟨N⟩ 件事 / 承接不住的 ⟨N⟩ 件事

做对的

1. ⟨…⟩——⟨为什么它最有价值；它是从业务语义推出来的，不是从技术模式套出来的⟩。
2. ⟨…⟩——⟨…⟩
3. ⟨…⟩——⟨方向是对的，只是推广范围不够⟩

承接不住的

1. ⟨…（最严重）⟩——⟨后果；这是"设计对了但落地不完整"的典型案例⟩。
2. ⟨…⟩
3. ⟨…⟩

---

6. 如果让我重做，我会改什么（按性价比排序）

复盘视角只给优先级判断；分阶段展开、验收标准与灰度见《⟨主题⟩-改造方案.md》，此处不重复。

优先级	改什么	为什么	成本	收益
P0		⟨真金白银 / 会花错钱⟩	低
P1			中
P2
P3		⟨卫生问题⟩

一句话排序逻辑：先修会花错钱和会重复调用外部系统的（P0/P1），再做让"不确定"可运营（P1/P2），最后才是卫生问题（P3）。因为前两类是"静默地把事情做错"，后者只是"做得不够漂亮"。

---

7. 这套设计里可以复用的方法论

1. ⟨先判"可逆性"，再决定"要不要补偿"。⟩ ⟨任何跨系统写操作都适用…⟩
2. ⟨异常分层翻译：真相层 → 重试层 → 履历层 → 归集层。⟩ ⟨每层只做一件事，且必须在能拿到信息的最高层把信息捞住⟩
3. ⟨重试责任单点。⟩ ⟨否则是乘法关系，不是加法⟩
4. ⟨"不确定"必须是一等状态。⟩ ⟨否则会退化成一行日志，等于不存在⟩
5. ⟨分级的上限取决于覆盖面，不是取决于精细度。⟩ ⟨一条路上做四层分级，不如四条路上各做一层⟩

---

8. 附：面试口述版

8.1 一分钟版（先讲骨架）

「⟨需求一句话⟩。我的判断是：⟨核心判断⟩。所以我不能只写 try-catch，得把 ⟨X⟩ 翻译成 ⟨Y⟩。

设计上是 N 层：⟨逐层一句话⟩。调用方只做一件事：⟨…⟩。」

8.2 三分钟版（加取舍与代价）

在上一段基础上补三段：⟨取舍一（最看重的一点）+ 它的代价⟩ · ⟨取舍二 + 难在哪⟩ · ⟨要坦白的一点（覆盖面 / 落地不完整）⟩。

8.3 追问预判（问题 → 一句话答）

追问	答
⟨为什么…？⟩	⟨一句话⟩
⟨既然…，那…？⟩	⟨一句话，含"坦白说没有"这类诚实回答⟩
⟨这套设计最大的风险？⟩	⟨一句话⟩

---

附：与代码的对照说明

本文的判断	代码事实	是否一致
⟨分级放最底层⟩	⟨路径:行号⟩	✅ 一致，但未推广
⟨只重超时⟩	⟨路径:行号⟩	✅ 一致
⟨…⟩		⚠️ 部分一致

诚实性要求：本文的判断与代码事实不一致处必须逐条列出——这是这份文档可信度的来源。