Python模块化设计边界怎么判断

Python模块化设计的核心在于划定清晰的责任边界，而非盲目追求模块数量或按功能机械切分：理想的模块应职责单一（如auth.py只管认证、不涉邮件）、import稳定、杜绝循环依赖和隐式耦合，坚决摒弃“万能”utils.py；子包应服务于共享约定或封装实现细节，而非简单归类文件，且需通过__init__.py审慎控制导出接口、严禁执行业务逻辑或耗时操作；松耦合则体现为单向依赖、可独立mock、变更影响可控——最终目标是让代码具备可追溯性：一次git blame就能精准定位问题责任人，而非在十几个文件间迷失数据流向。

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

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

实操建议：

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

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

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

常见错误现象：

• 把 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 隔离

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Python模块化设计边界怎么判断》文章吧，也可关注golang学习网公众号了解相关技术文章。