模块拆分后 import 失败但没报错的主因是缺失非空 init__.py；循环导入需抽离公共类型或用字符串注解；集成测试和显式 __all 可提升可维护性。
模块拆分后 import 失败但没报错
Python 不会因为模块路径存在就自动把它当包处理，__init__.py 缺失或为空是静默失败的常见原因。尤其在子目录里新建了 utils/ 或 core/ 后，直接 from utils.helper import foo 报 ModuleNotFoundError，但 IDE 可能不标红——因为静态分析误判了包结构。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 每个含 Python 文件的子目录都放一个非空
__init__.py（哪怕只写__all__ = []） - 用
python -m pip install -e .安装本地包时，确保setup.py或pyproject.toml的packages正确包含新模块路径 - 运行脚本前检查
sys.path，确认当前工作目录或父目录在其中；避免靠sys.path.append('..')临时修复
循环导入在拆分后突然暴露
原来单文件里看似合理的引用，在拆成 models.py 和 serializers.py 后立刻变成死锁：A 导入 B，B 又导入 A 的某个类，而那个类的定义依赖 A 的全局状态。这种问题不是“写错了”，而是拆分放大了隐式耦合。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 把被双方依赖的类型定义（如
BaseModel、ErrorResponse）抽到独立的types.py或base.py中 - 用字符串注解替代实际导入，例如
def load(item: "User") -> None:，配合from __future__ import annotations - 在模块顶层避免执行依赖其他模块的逻辑（比如调用
register_handler()），改用函数内延迟导入：from .handlers import process_event
测试覆盖率虚高但实际漏测边界
拆分后每个小模块单独跑 pytest 都绿，但集成起来出错。典型场景是 config.py 读取环境变量，db.py 依赖它初始化连接池——单元测试各自 mock 了依赖，却没覆盖 “config 加载失败 → db 初始化抛异常” 这条链路。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 对跨模块协作的关键路径（如启动、配置加载、中间件注册）写集成测试，不 mock 任何内部模块
- 在 CI 中加一条检查：运行
python -c "import myapp; myapp.main()"，验证入口能无异常导入并初始化 - 避免在模块级定义可变默认值（如
CACHE = {}），拆分后多个模块可能各自初始化一份，掩盖共享状态预期
IDE 补全和类型检查变弱
PyCharm 或 VS Code 对 from myapp.v2.api import routes 能跳转，但对 from myapp.v2.api.routes import handle_user 就常标黄——不是代码错，是模块层级太深、__all__ 没声明、或类型存根（.pyi）没同步更新。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 在每个模块的
__init__.py中显式声明__all__，控制对外暴露的符号 - 避免用
from .submodule import *，它会让类型检查器丢失上下文 - 如果用了 Pydantic 或 TypedDict，确保字段名拼写和类型注解在拆分后仍保持一致，否则
mypy无法跨模块推导
模块拆得越细，对 import 路径、初始化顺序、类型可见性的要求就越苛刻。最容易被忽略的不是“能不能拆”，而是“谁来保证拆完之后，所有地方依然按你设想的方式被导入和使用”。
