modular-design

# 模块化设计决策技能 ## 决策 1：该不该拆成独立模块？ ``` 问：这段代码应该留在当前模块，还是拆出去？ 判断流程： 1. 能用一句话说清楚当前模块的职责吗？ → 能 → 不拆 → 需要用"和"连接两件事 → 考虑拆 2. 这两块代码的变更理由相同吗？ → 相同（都是因为"聊天功能变了"才改）→ 不拆，内部分目录就够 → 不同（一个因为"认证流程变了"，一个因为"用户资料变了"）→ 拆 3. 拆完之后两个模块之间会大量来回调用吗？ → 会 → 不该拆，它们本来就是一个东西 → 不会 → 拆 ``` **核心原则**：按业务域拆，不按技术层。一个业务模块内部包含 data/logic/view 是正常的，不要拆成 chat_network + chat_cache + chat_ui 三个独立包。 ## 决策 2：逻辑隔离还是物理隔离？ ``` 问：用目录分区够了，还是需要独立 package/crate？ 判断流程： 1. 模块边界稳定了吗？ → 还在探索阶段，边界可能变 → 逻辑隔离（目录分区） → 边界已经清晰稳定 → 考虑物理隔离 2. 有没有出现"不小心 import 了不该 import 的东西"？ → 没有 → 逻辑隔离够用 → 有，而且靠 code review 拦不住 → 物理隔离 3. 这个模块需要被多个项目复用吗？ → 是 → 物理隔离 → 否 → 看前两条 ``` **物理隔离后**：barrel file（入口文件）就是模块的公开 API。没导出的，对外界就是不存在的。内部随便重构，只要 barrel file 不变，外界无感。 ## 决策 3：模块间怎么通信？ ``` 问：A 模块需要和 B 模块交换信息，用什么方式？ 优先级（从简单到复杂）： 1. 直接调用 → A import B 的公开 API，直接调方法 适用：A 依赖 B，方向清晰，B 的接口稳定 2. 回调/闭包 → A 把函数注入 B，B 在合适时机调用 适用：B 需要 A 的信息但不能依赖 A（如底层需要高层的 Token） 3. Stream/事件 → B 广播事件，A 订阅监听 适用：一对多通知，发布方不关心谁在听 4. 组装层中转 → A 和 B 互不依赖，由 main.dart 把 A 的输出接到 B 的输入 适用：两个平级业务域完全独立 选择原则：能用 1 解决的别用 2，能用 2 解决的别用 3。 ``` ## 决策 4：依赖方向对不对？ ``` 问：这个依赖关系安全吗？ 规则： - 短命依赖长命 → 安全（聊天页依赖 WsClient ✓） - 长命依赖短命 → 危险（WsClient 持有聊天页引用 ✗） - 上层依赖下层 → 正常（View → Cubit → Repository ✓） - 下层依赖上层 → 违规（Repository import View ✗） - 平级互相依赖 → 循环依赖，需要重构 长命通知短命的正确方式：Stream/事件。短命的订阅，用完取消，互不牵连。 ``` ## 决策 5：该放 shared 还是留在业务模块？ ``` 问：这个类/组件应该放到 shared 模块吗？ 判断流程： 1. 它被几个模块使用？ → 只有一个 → 留在那个模块里 → 两个及以上 → 考虑放 shared 2. 它和业务逻辑有关吗？ → 有（如 Conversation 模型）→ 放到对应的业务模块，让其他模块依赖它 → 没有（如 AvatarWidget、SearchBar）→ 放 shared 3. shared 模块是不是越来越大了？ → 是 → 审视一下，有没有只被一个模块用的东西混进来了 ``` 改了底层模块的类，上层所有引用该类的模块都可能需要同步更新。 ## 决策 6：稳定性与变更频率 ``` 问：一个新功能应该加到现有模块里，还是独立出去？ 判断流程： 1. 现有模块是否已经稳定（很少变更）？ → 是 → 继续判断 → 否（本身也在频繁变更）→ 加进去，一起迭代 2. 新功能是否可能频繁变更、反复调整？ → 是 → 独立出去，不要让不稳定的部分拖累稳定的模块 → 否（一次性做完就不动了）→ 加进去 3. 新功能的变更是否会导致现有模块的消费方被迫跟着改？ → 会 → 必须独立，否则每次调整都是连锁反应 → 不会（内部变更，公开 API 不变）→ 可以加进去 ``` **核心原则**：稳定的模块是系统的地基，不要往地基里塞实验性的东西。把不确定的、可能反复调整的功能隔离到独立模块，让它自己折腾，不影响已经稳定运行的部分。 ## 决策 7：可复用性 ``` 问：这段代码将来可能被其他模块/项目复用吗？ 判断流程： 1. 它是否和具体业务逻辑无关（纯工具、纯 UI 组件、纯算法）？ → 是 → 适合独立成可复用模块 → 否 → 留在业务模块内部 2. 它的接口是否足够通用（不依赖特定的业务类型）？ → 是 → 可以抽出来 → 否（参数里有业务模型）→ 先留着，等第二个消费方出现再抽 3. 现在就有多个消费方吗？ → 是 → 抽出来 → 否（只是"将来可能"）→ 不要过早抽象，等真正需要时再动 ``` **核心原则**：不要为了"将来可能复用"就提前抽象。过早抽象的代价是：接口设计基于猜测而非真实需求，等真正的第二个消费方出现时，往往发现接口不对，还得重来。等到第二个消费方真的出现了，再抽也不迟。