002、现代Python后端开发环境与工具链搭建

002、现代Python后端开发环境与工具链搭建上周排查一个线上问题日志里报了个ImportError: cannot import name ... from partially initialized module。花了半小时才发现是同事本地虚拟环境混用了Python 3.8和3.10的依赖打包时没锁版本。这种环境问题最耗时间——代码逻辑没错工具链没搭对上线就出鬼故事。虚拟环境别再用全局Python了见过太多人直接pip install装到系统Python里过两个月项目就跑不起来了。虚拟环境是底线不是可选项。# 用venv就行别折腾virtualenv了python-mvenv .venv# Windows用户注意激活命令不一样# source .venv/bin/activate # Linux/Mac# .venv\Scripts\activate # Windows# 激活后提示符会变这是最直观的确认方式(.venv)userhost ~/project $有个细节把.venv加到.gitignore里但要把requirements.txt或Pipfile提交。团队协作时我习惯在项目README开头就写环境搭建步骤省得新人挨个问。依赖管理requirements.txt只是起点直接pip freeze requirements.txt会混入系统所有包包括你根本不需要的。得手动维护主依赖但这样版本容易飘。# requirements.in - 只写你主动安装的 fastapi0.104.1 sqlalchemy2.0.0,3.0.0 # 这里用范围给安全更新留空间 redis # 然后编译成精确版本 pip-compile requirements.in # 需要pip-tools # 生成的requirements.txt会包含所有子依赖及其哈希值 # 部署时用这个锁死的版本 pip-sync requirements.txt # 这个狠会删掉不在列表里的包现在更流行用poetry或pdm。我团队用pdm多因为快而且兼容pip的生态。它的pyproject.toml一份文件搞定依赖、构建配置比setup.py清爽。# pyproject.toml示例 [project] dependencies [ flask2.3.0, celery5.3.0, ] [tool.pdm.dev-dependencies] dev [ pytest7.4.0, black23.0.0, # 格式化工具放开发依赖里 ]编辑器配置VSCode够用了别在编辑器上站队用顺手的就行。但有些配置能少踩坑// .vscode/settings.json{python.defaultInterpreterPath:${workspaceFolder}/.venv/bin/python,python.formatting.provider:black,// 统一格式化editor.formatOnSave:true,// 存盘自动格式化避免代码风格争论python.linting.enabled:true,python.testing.pytestEnabled:true// 测试框架设成pytest}重点是把.vscode/也提交到Git团队风格就统一了。特别是extensions.json里推荐安装的插件列表新人装完就能开工。代码质量工具链不是可有可无很多团队等到出问题了才加这些其实应该第一天就配置好。# pyproject.toml里加这些 [tool.black] line-length 88 target-version [py310] [tool.isort] profile black # 让isort兼容black的格式 [tool.mypy] python_version 3.10 strict true # 严格模式开始痛苦但长期受益 [tool.ruff] # 这个比flake8快一个数量级 select [E, F, B, I] # 错误、flake8-bugbear、import排序 ignore [E501] # 行长度交给black管然后在pre-commit配置里挂上钩子# .pre-commit-config.yamlrepos:-repo:https://github.com/psf/blackrev:23.11.0hooks:-id:black-repo:https://github.com/charliermarsh/ruff-pre-commitrev:v0.1.6hooks:-id:ruffargs:[--fix,--exit-non-zero-on-fix]这样每次git commit前自动检查不合格的代码根本进不了仓库。CI流水线里也要跑这些检查再加个pytest跑测试。调试配置别只会print了VSCode的调试配置存到项目里// .vscode/launch.json{version:0.2.0,configurations:[{name:Python: 当前文件,type:python,request:launch,program:${file},console:integratedTerminal,justMyCode:false// 这个很重要能进第三方库源码},{name:Python: FastAPI应用,type:python,request:launch,module:uvicorn,args:[main:app,--reload,--host,0.0.0.0],env:{PYTHONPATH:${workspaceFolder}}}]}遇到复杂问题用debugpy远程调试。生产环境慎用但预发环境救过我好几次。# 在代码里临时插一段importdebugpy debugpy.listen((0.0.0.0,5678))print(等待调试器连接...)debugpy.wait_for_client()# 这里会阻塞直到VSCode连上来容器化配置早点接触有好处哪怕不上K8s用Docker统一环境也是值的。# Dockerfile FROM python:3.10-slim # 先装系统依赖apt-get记得清理缓存 RUN apt-get update apt-get install -y \ gcc \ rm -rf /var/lib/apt/lists/* # 复制依赖文件 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 复制代码 COPY . . # 别用root跑应用 RUN useradd -m -u 1000 appuser USER appuser CMD [uvicorn, main:app, --host, 0.0.0.0].dockerignore别忘了写不然把.venv、__pycache__都拷进去镜像能大好几倍。个人经验谈工具链不是一次搭完的。我习惯新项目先上虚拟环境pdmblack两周内加上pre-commit一个月内配好CI。关键是要团队达成共识代码风格检查不是找茬是为了减少低级错误依赖锁版本不是死板是为了线上稳定。还有个习惯在项目docs/env.md里记录环境特殊问题。比如某个包需要系统库或者Windows下某个路径处理不一样。这些细节文档化新人接手时能少走弯路。最后说个反直觉的工具链太复杂也会拖慢开发。见过一个团队配了十几项检查git commit要等一分钟后来大家干脆都--no-verify绕过去。平衡点在于检查要快比如用ruff替代flake8失败要有明确提示并且团队定期回顾这些规则是否还合理。环境问题就像地基平时看不见出问题就是大事。花一天把工具链理顺往后几个月都踏实。