Python文件管理规范_工程实践说明【指导】

规范python项目目录结构需分层明确、职责分明：src/放主代码，tests/平级存测试，scripts/放可执行脚本，configs/集中配置，requirements/拆分依赖；命名全小写下划线，测试文件以test_开头或_test.py结尾，__init__.py显式导出接口，敏感配置.gitignore过滤，根目录用pyproject.toml管理依赖与工具，CI强制代码检查，README和make封装提升协作效率。

Python项目文件管理不是随便建个文件夹就完事，关键在结构清晰、职责分明、方便协作和部署。一个规范的目录结构能让新成员快速上手，让CI/CD流程稳定运行，也避免import混乱或路径硬编码出错。

核心目录结构建议

推荐采用分层明确、按功能隔离的布局，典型结构如下（根目录下）：

• src/：主代码包（如 src/myproject/），含所有可导入模块，__init__.py 齐全；不把代码直接放根目录
• tests/：与 src/ 平级，用 pytest 结构（如 tests/test_core.py），支持 python -m pytest 直接运行
• scripts/：存放可执行脚本（如数据清洗、定时任务），不混入业务逻辑，用 #!/usr/bin/env python + if __name__ == "__main__":
• configs/：配置文件集中地（dev.yaml, prod.env 等），避免写死在代码里
• requirements/：拆分依赖（requirements/base.txt, dev.txt, prod.txt），用 pip install -r requirements/prod.txt 精准安装

命名与组织细节要点

小习惯影响大体验，这些细节常被忽略但极易引发问题：

• 包名、模块名全小写+下划线（data_loader.py），不用驼峰或中划线（DataLoader.py 或 data-loader.py 会导致 import 失败）
• 测试文件必须以 test_ 开头或 _test.py 结尾，pytest 才能自动发现
• __init__.py 不留空——显式导出公共接口，例如：from .core import run_pipeline，再在外部 from myproject import run_pipeline
• 敏感配置（密钥、数据库密码）绝不提交到 Git，用 .gitignore 过滤 *.env, secrets.yml 等，并在 README 中说明如何生成

环境与依赖管理实践

依赖混乱是线上事故高频原因，靠规范约束比靠人工记忆更可靠：

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

• 项目根目录放 pyproject.toml（替代 setup.py），定义构建系统、依赖、lint 工具等，现代 Python 工具链（pip, poetry, hatch）都优先读它
• 开发时用 poetry install 或 pip install -e ".[dev]" 安装可编辑模式，确保本地 import 路径与生产一致
• 每次更新依赖后运行 pip freeze > requirements/locked.txt（或用 poetry export -f requirements.txt），部署时严格按锁文件安装
• 禁止在代码中用 os.chdir() 切换工作目录——改用 pathlib.Path(__file__).parent 获取相对路径

自动化检查与文档同步

规范要落地，得靠工具兜底和轻量文档支撑：

• 在 pyproject.toml 中配置 flake8 / black / mypy，CI 流程中强制校验，失败即阻断合并
• 根目录放简洁 README.md，包含：快速启动命令（make init）、配置说明、测试运行方式、常见问题（如“ImportError: No module named ‘xxx’” → 检查是否在 src 外运行）
• 用 make 或 just 封装常用操作（make test, make format, make deploy），降低新人使用门槛
• 定期运行 pylint --fail-under=8 . 或 bandit -r src/ 扫描安全与质量风险，结果集成进 CI 报告

不复杂但容易忽略——结构定下来，团队写代码、测代码、发代码就都有了共同语言。坚持几周，会明显减少“为什么我本地跑得通，服务器报错”的沟通成本。