模块化设计六原则

经典软件工程设计原则在 AI 协作场景下的现代化清单。 用作新模块设计、重构、代码审查时的对照表，不替代具体执行 skill。

触发场景

• 编写新模块、新服务、新接口
• 用户说"设计"、"拆分模块"、"评审"、"重构"
• /review、/new-feature、/optimize、/design 命令在设计阶段
• 评估技术债时对照原则定位坏味道

---

六原则速查表

#	原则	一句话	衡量指标	详细案例
1	模块大小适中	单文件控制在职责边界内	行数/职责数	引用 size-check
2	减少调用深度	调用链尽量 ≤ 3 层	栈深度	modularity.md#调用深度
3	多扇入，少扇出	被复用 > 主动依赖	依赖数/被依赖数	modularity.md#扇入扇出
4	接口边界清晰	入参/出参/异常统一	统一响应包装	modularity.md#边界清晰
5	作用域内聚	改 A 不波及 B	跨模块副作用	引用 refactor-safety
6	功能可预测	同输入→同输出	幂等/无副作用/可测	predictability.md

---

1. 模块大小适中

主要执行交给 size-check skill；本 skill 仅作总纲提示。

核心：单文件超限是设计信号，不是格式问题。提示职责过载，应拆分。

默认阈值：Java ≤ 300 / Go ≤ 400 / Vue ≤ 200 / TS ≤ 300 / Python ≤ 300（项目可覆盖）。

---

2. 减少调用深度

❌ 反例：Controller → ServiceA → ServiceB → ServiceC → DAO → Mapper（6 层）。定位 bug 需要逐层进栈，新人难以理解。

✅ 正例：Controller → Service → Repository（3 层），其余通过事件/队列/纯函数解耦。

衡量：调用栈深度 > 5 即视为坏味道。详见 modularity.md#调用深度。

---

3. 多扇入，少扇出

❌ 反例：OrderService.createOrder() 依赖 UserService、CouponService、PaymentService、StockService、NotifyService、AuditService、CacheService、MetricsService（扇出 8）。改一处可能炸 8 处。

✅ 正例：StringUtils.toCamelCase() 被项目 30 处复用（扇入 30）。复用价值高，无下游污染。

衡量：单方法直接依赖数 ≤ 5；被依赖数越多越好。详见 modularity.md#扇入扇出。

---

4. 接口边界清晰 + 统一错误返回

现代化改写"单入口单出口"原则。早期 return / guard clause 优于深嵌套。

❌ 反例：成功返回 {data}、失败抛异常、还有一种返 null，调用方需要 3 种处理路径。

✅ 正例：统一 {code, data, message} 包装，异常在边界层（middleware / interceptor）集中处理。一个出入口契约对所有调用方一致。

详见 modularity.md#边界清晰。

---

5. 作用域内聚

主要执行交给 refactor-safety 与 multi-tenant-safety skill。