17370845950

Python项目结构的关键在于模块划分逻辑、导入路径控制和包初始化行为，而非教程编号；__init__.py空则标识包，有内容可暴露接口、防循环导入或触发副作用；PYTHONPATH优先级高于sys.path但不推荐使用；tests/应与主包同级并排除在安装外。

这标题不是学习路线，是营销包装——Python 项目结构没有“第238讲”这种官方分级，也没有统一教程编号。真正决定项目是否可维护的，是模块划分逻辑、导入路径控制和包初始化行为，不是讲数。

为什么 __init__.py 有时为空，有时必须写内容？

空的 __init__.py 只起标识作用，让 Python 把目录当成包；但一旦需要控制包的公共接口、设置默认导入或执行初始化逻辑，就必须写内容。

• 暴露子模块：在 mylib/__init__.py 中写 from .core import process_data，调用方才能直接 from mylib import process_data
• 避免循环导入：把跨模块共享的常量或类型定义提前放到 __init__.py，比分散在各模块里更可控
• 触发副作用：某些库（如旧版 Flask 扩展）依赖 __init__.py 中的注册语句，删掉就失效

sys.path 和 PYTHONPATH 哪个优先级更高？

PYTHONPATH 环境变量的内容会被插入到 sys.path 开头，所以它优先级更高——但这不等于推荐使用。

• 本地开发时设 PYTHONPATH=.:./src 能绕过安装，但 CI 环境通常没配，导致“本地能跑线上报 ModuleNotFoundError”
• pip install -e . 是更可靠的方式：它把当前项目路径写进 site-packages 的 .pth 文件，既生效又可复现
• 检查实际导入路径：运行 python -c "import mymodule; print(mymodule.__file__)"，比猜 sys.path 顺序更直接

测试目录 tests/ 放哪才不会导入冲突？

放在项目根目录下（与 src/ 或主包同级），并确保测试代码不被当作包安装——这是最简且兼容性最好的方式。

• 不要把 tests/ 放进主包里（如 mylib/tests/），否则 pip install 会把它一起装进去，还可能意外被 pytest 发现为测试包
• pyproject.toml 中加 packages = [{include = "mylib"}]，明确排除 tests/
• 运行测试时用 pytest tests/，而不是 python -m pytest tests/ —— 后者可能改变工作目录导致相对导入失败

pyproject.toml
[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "mylib"
version = "0.1.0"
packages = [{include = "mylib"}]

项目结构的关键不在层级多深，而在每个 import 是否清晰表达意图、每次 pip install 是否产生预期结果。那些靠改 sys.path 硬凑出来的结构，上线前一定会在某个环境里崩一次。