Python脚本到工程化项目转型指南

当脚本被多人调用、需日志/配置/多环境时，if name == "__main__" 会成为瓶颈，应将核心逻辑抽成模块函数或类，主脚本仅负责参数解析与执行，避免顶层副作用代码。

脚本里直接写 if __name__ == "__main__" 还能撑多久

当一个 Python 脚本开始被多人调用、需要加日志、要读配置、还要跑在不同环境时，if __name__ == "__main__" 就从入口变成了瓶颈。它本身没问题，但意味着所有逻辑都挤在单文件里，没法被单元测试覆盖，改一行可能影响三个调用方。

实操建议：

• 把核心逻辑抽成函数或类，放在 src/ 或 lib/ 下的模块中，主脚本只负责解析参数、组装依赖、触发执行
• 避免在模块顶层写带副作用的代码（比如直接调用 requests.get() 或修改全局状态）
• 如果脚本已承担调度职责（如定时拉数据），考虑先用 argparse 拆出子命令，为后续转成 CLI 工具打基础

setup.py 还是 pyproject.toml？选错会卡住 CI 流程

Python 3.12+ 新项目必须用 pyproject.toml，不是“推荐”，是工具链默认只认它。用 setup.py 会导致 pip install -e . 失败、GitHub Actions 里 build 步骤报 UnsupportedPythonVersion，甚至本地 poetry 加依赖时静默忽略你的包。

关键差异点：

• pyproject.toml 必须声明 [build-system]，否则 pip 认不出构建后端；常见填法是 requires = ["setuptools>=45", "wheel"]
• 包路径由 [project] 下的 packages 或 find 控制，别再手动列 src/xxx/__init__.py，用 find = {where = ["src"]} 更稳
• 开发依赖（如 pytest、mypy）不要塞进 install_requires，该放 [project.optional-dependencies] 或独立的 dev-requirements.txt

日志一开就满屏 INFO:root:，怎么让不同模块输出可区分又不漏错误

直接用 print() 或 logging.info() 全局配置，会让 Flask 的请求日志和你自己的数据清洗日志混在一起，线上出问题时根本分不清谁打的 INFO。更麻烦的是，有些库（如 urllib3）默认开 DEBUG，一启用全量日志就刷屏。

正确做法：

• 每个模块用 logging.getLogger(__name__) 获取 logger，而不是 logging.getLogger()（后者拿到 root）
• 在入口处统一配置 handler 和 level：root 设为 WARNING，你自己的包设为 INFO，第三方库（如 botocore）显式设为 ERROR
• 别用 basicConfig，它只能调一次且不支持多 handler；改用 dictConfig 或显式 addHandler + setLevel

测试跑不通，是因为没 mock datetime.now() 还是路径没加到 PYTHONPATH

常见失败现象：ModuleNotFoundError: No module named 'myproject' 或测试里时间相关断言总失败。前者多半是项目结构没对齐 Python 导入规则，后者几乎 100% 是没冻结时间。

两个最常漏的点：

• 确保测试目录（如 tests/）和源码目录（如 src/）都在 Python 模块搜索路径里——CI 中用 export PYTHONPATH=$(pwd)/src:$(pwd)/tests，本地用 -m pytest 并配合 pyproject.toml 里的 [tool.pytest.ini_options] 配置 pythonpath
• 所有涉及系统时间、网络、文件读写的操作，必须 mock。用 freezegun.freeze_time("2023-01-01") 替代手写 patch(datetime, ...)；用 responses.add() 拦 HTTP 请求，别信 “这个 API 稳定所以不用 mock”

工程化不是加一堆配置和目录，而是让每次 git push 后你知道：测试会跑、日志能查、部署不炸、别人接手时不抓瞎。最难的其实是说服自己——那个能跑通的脚本，真不该再改了。