Python项目结构无统一标准，需依场景权衡：小工具可省src/，发布项目推荐src/并配置package_dir；__init__.py建议显式添加以支持IDE和类型检查；配置应分环境、敏感信息走环境变量，避免硬编码路径。
Python 项目结构没有标准答案，但有公认的合理边界。盲目套用“教科书式结构”反而会拖慢开发节奏，尤其在小工具、CLI 脚本或快速验证场景下。
什么时候该用 src/ 目录？
不是所有项目都需要 src/。它的核心作用是隔离源码与顶层命名空间，避免 import mypackage 时因当前路径（pwd）不同导致的导入冲突。
- 需要发布到 PyPI 或被其他项目以
pip install -e .方式引用时，src/是推荐做法 -
setup.py或pyproject.toml中必须显式配置packages=find_packages(where="src")和package_dir={"": "src"} - 测试代码（
tests/）不能放在src/内，否则会被打包进发布包 - 如果项目只运行不安装（比如 Flask Web 服务直接
python app.py），src/反而增加路径跳转成本
__init__.py 到底要不要写？
Python 3.3+ 支持隐式命名空间包（PEP 420），但实际工程中仍建议显式添加 __init__.py，除非你明确需要跨目录合并同名包。
- 空文件即可，不需要导出内容；但若需控制
from mypkg import *行为，可定义__all__ - 在
src/mypkg/__init__.py中做统一初始化（如日志配置、全局变量注册）是常见实践 - IDE（如 PyCharm）和类型检查器（mypy）依赖
__init__.py推断包结构，缺失可能导致补全失效或ImportError - 注意：Git 不跟踪空文件，若用
touch src/mypkg/__init__.py创建后未git add，CI 环境可能报错
如何组织配置文件才不会踩坑？
配置不是越集中越好。硬编码路径、混用环境变量与文件、把敏感信息写进 Git，是三个高频雷区。
立即学习“Python免费学习笔记（深入）”；
- 用
os.getenv("ENV", "dev")或os.environ.get("DB_URL")读取环境变量，优先级高于配置文件 - 配置文件按环境分层：
config/base.py（通用）、config/dev.py（开发）、config/prod.py（生产），再用importlib.import_module(f"config.{os.getenv('ENV') or 'dev'}")加载 - 敏感字段（如密钥、数据库密码）绝不写入任何 Python 文件或
.yaml，应通过环境变量注入 - 使用
python-dotenv加载.env仅限本地开发，CI/CD 中禁用该机制
import os from pathlib import Path安全获取配置根路径，不依赖当前工作目录
CONFIG_ROOT = Path(file).parent.parent / "config" BASE_CONFIG = CONFIG_ROOT / "base.py"
避免 os.getcwd() + "/config/base.py" 这类写法 —— 在 pytest 或 celery worker 中极易失效
项目结构的本质是权衡：可维护性 vs 启动速度，一致性 vs 场景适配。最危险的不是结构简陋，而是结构与实际部署方式脱节——比如用 src/ 却没配 package_dir，或把 __init__.py 当装饰品留空却指望 IDE 正确解析模块依赖。
