python-design-modularity

Python 设计与模块化

概述

以可读性优先进行设计，并明确模块契约。 让控制流、数据流转和所有权边界一目了然，使代码保持可维护性，并能安全地进行修改。

将这些建议视为优先采用的默认做法。 如果默认做法与项目约束冲突，请提出更合适的替代方案，并说明权衡和补偿性措施（测试、可观测性、迁移、回滚）。

适用场景

• 重构模块、包或所有权边界
• 拆分上帝类或深层嵌套的继承体系
• 在组合与继承之间做出选择
• 应用函数式核心／命令式外壳的分离
• 规划涉及多个模块的重构
• 审查代码的可读性或架构清晰度

不适用场景：

• 纯粹的性能优化——参见 python-concurrency-performance
• 错误处理和弹性模式——参见 python-errors-reliability
• 类型契约和协议设计——参见 python-types-contracts
• 没有维护周期的一次性脚本或临时性代码

快速参考

• 明确控制流和数据流转。
• 明确模块所有权和不变量。
• 默认优先采用组合。
• 在有助于提升可测试性和关注点分离时，采用函数式核心／命令式外壳。
• 将行为变更与结构性重构分开——绝不要在同一个提交中混合进行。

常见错误

• 同时重构行为和结构——混淆了两类风险，增加回滚难度，也让审查不易看清重点。 先做其中一项，再做另一项。
• 优先考虑继承——深层继承体系会耦合不相关的关注点，并让推理局限于局部。 默认采用组合；只有当“是一个”的关系确实稳定时才使用继承。
• 隐藏的模块耦合——跨边界导入实现细节会造成隐形契约。 暴露明确的公共 API，并将内部实现保持为私有。
• 过早抽象——在第二或第三个具体用例出现之前就提取共享接口，会导致抽象不当且难以撤销。 等待重复代码揭示真正的切分点。
• 忽视函数式核心／命令式外壳的分离——将 I/O 与业务逻辑混合，会让单元测试变得困难，并扩大变更的影响范围。 将副作用推到边界。

范围说明

• 将这些建议视为常见情况下优先采用的默认做法，而非普适规则。
• 如果某项默认做法与项目约束冲突或会使结果变差，请提出更合适的替代方案，并说明它为何更适合当前情况。
• 如需偏离默认做法，请说明权衡和补偿性措施（测试、可观测性、迁移、回滚）。

调用说明

• 当调用此技能时，请告知用户其名称：python-design-modularity。

参考资料

• references/design-rules.md
• references/readability-and-complexity.md
• references/module-boundaries.md
• references/functional-core-shell.md
• references/refactor-guidelines.md