Python 模块化设计的边界判断

合理模块粒度应以责任边界清晰、import稳定、避免循环依赖和隐式耦合为标准，如auth.py专注凭证与会话，不掺杂邮件发送；禁用utils.py式黑洞；子包用于共享约定或封装实现细节，__init__.py仅声明包并控制导出，不执行业务逻辑；松耦合体现为依赖单向、可独立mock、变更影响可控。

模块拆分到什么粒度才算合理

模块不是越小越好，也不是按功能名硬切。关键看 import 是否稳定、from ... import 是否频繁引发循环依赖、测试时是否必须连带加载一堆无关逻辑。

实操建议：

• 一个模块对应一个明确的「责任边界」，比如 auth.py 处理凭证校验和会话管理，但不包含密码重置邮件发送（那是 notifications.py 的事）
• 如果两个函数总是一起被调用、参数高度耦合、修改一个必改另一个，它们大概率不该拆到不同模块
• 避免出现 utils.py 这种“啥都往里塞”的模块——它迟早变成隐式依赖黑洞，改一行可能影响三个服务

什么时候该用子包而不是平级模块

当一组模块开始共享内部约定（如共用 _base.py、共用 __all__ 导出规则）、或需要隐藏实现细节（比如把 _parser.py 和 _serializer.py 放进 serializers/ 包，只暴露 serialize() 和 deserialize() 接口）。

常见错误现象：

立即学习“Python免费学习笔记（深入）”；

• 把 models/ 做成包，但里面全是独立的 user.py、order.py，没定义 __init__.py 导出逻辑，结果外部还得写 from models.user import User —— 这和扁平模块没区别
• 子包里放了太多顶层接口函数，导致使用者搞不清该导入 pkg.foo() 还是 pkg.submod.bar()
• 子包之间存在跨包的 from .. import 相对导入，一旦目录结构调整，ImportError: attempted relative import with no known parent package 立刻报错

__init__.py 里该写什么、不该写什么

它的核心作用是声明“这里是个包”，顺便控制对外暴露的接口。不是初始化脚本，也不该承担业务逻辑。

实操建议：

• 必须有（哪怕空文件），否则 python 3.3+ 可能忽略该目录为包（尤其在 zipimport 或某些打包场景下）
• 推荐显式定义 __all__ = ["Client", "connect"]，防止 from pkg import * 污染命名空间
• 禁止在其中调用耗时操作（如读配置、连数据库），因为只要有人 import pkg 就会触发——而这个 import 可能发生在 CLI 启动阶段，拖慢整个命令响应
• 避免在 __init__.py 里做条件导入（如 if sys.version_info > (3, 8): from typing import Literal），应统一移到具体模块中按需处理

模块间依赖怎么才算“松”

松耦合不是指“没有 import”，而是指依赖方向清晰、变更影响可控。比如 api.py 依赖 service.py 是合理的，但反过来就不行；service.py 依赖 db.py 可以，但如果它还直接 import 了 cache.py 和 metrics.py，就说明职责过重。

判断依据：

• 运行 python -m pydeps mypkg --max-bacon=1（需装 pydeps），看依赖图是否出现双向箭头或密集星型结构
• 尝试 mock 一个模块的依赖：如果为了测 payment.py，你得 patch Logging、requests、settings、user.py 四个东西，那它大概率太紧了
• 修改 models.py 中一个字段类型，结果 api.py、admin.py、migrations/ 全报错——说明模型被到处硬引用，该考虑加一层 repository 或 DTO 隔离

事情说清了就结束。模块边界的本质，是让每次 git blame 时，你能快速定位到“谁该对这个 bug 负责”，而不是翻十来个文件才搞懂数据从哪来、到哪去。