3. 环境搭建：Python版本选择、虚拟环境、依赖管理
做数据访问审计SDK开发，第一件事不是写代码。
先把环境搭好。我见过不少新手，上来就pip install一把梭，结果项目做到一半发现依赖冲突、版本不对、跑都跑不起来。嗯，这种坑我自己也踩过好几次。今天就把我这些年积累的环境搭建经验说清楚。
3.1 Python版本怎么选？
先说结论：推荐Python 3.9或3.10。为什么不是最新的3.12？不是越新越好，看生态兼容性。
- Python 3.8：还在维护，但已接近EOL。如果你的生产环境只能用3.8，那也行。但新项目不建议了。
- Python 3.9：我个人最常用。审计SDK依赖的库（比如sqlparse, cryptography）在3.9上测试最充分。
- Python 3.10：支持match语句，写审计规则时很爽。大部分库已兼容。
- Python 3.11/3.12：性能有提升，但某些审计专用的ORM库可能还没适配。你想想，项目写到一半发现某个库不支持，多郁闷。
避坑指南：我曾经接手过一个项目，用了Python 3.12的f-string调试特性，结果CI环境里的3.11直接炸了。所以，稳一点，选3.9或3.10。
3.2 虚拟环境选哪个？
说白了，虚拟环境就是把项目的依赖隔离起来，防止“A项目需要Django 3.2，B项目需要Django 4.2”这种冲突。
Python自带的venv够用，但缺点是没有依赖锁定和完全的环境复现能力。我一般把虚拟环境分为两派：
- 轻量派：直接
python -m venv .venv+pip freeze > requirements.txt。适合小型脚本。 - 工程派：用pipenv或poetry，自带依赖解析和锁定，还能分离开发/生产依赖。
我个人更推荐工程派。尤其是像审计SDK这种要对接多种数据库、多种Python版本的项目，依赖管理稍有不慎就出问题。我遇到过几次“我机器能跑，你机器跑不了”的尴尬，都是因为没用锁定文件。
3.3 依赖管理：pipenv vs poetry
这两个是当前最主流的工具。我列个表对比，你一看就明白。
| 特性 | pipenv | poetry |
|---|---|---|
| 锁定文件 | Pipfile.lock | poetry.lock |
| 依赖解析速度 | 较慢，尤其依赖多的时候 | 快，用了更先进的解析器 |
| 虚拟环境管理 | 自动创建和管理 | 自动创建和管理，且支持跨项目 |
| 发布到PyPI | 需要额外工具（twine） | 内置poetry build和发布功能 |
| 配置文件格式 | Toml（Pipfile） | Toml（pyproject.toml）——更标准 |
| 社区趋势 | 维护中，但活跃度下降 | 非常活跃，已成为主流 |
我个人的建议：新项目直接用poetry。理由很简单——它更贴近Python官方推荐的pyproject.toml规范，而且速度真的快。之前我把一个老项目从pipenv迁移到poetry，依赖解析时间从2分钟降到了20秒。
当然，如果你所在团队已经统一用pipenv，也不必强行换。工具只是工具，关键是锁定文件必须进版本控制。
3.3.1 快速上手poetry
# 安装poetry（推荐使用官方安装器）
curl -sSL https://install.python-poetry.org | python3 -
# 创建新项目
poetry new audit-sdk
# 进入项目目录
cd audit-sdk
# 添加依赖（生产）
poetry add sqlparse cryptography
# 添加依赖（开发）
poetry add --dev pytest black
# 安装所有依赖（包括lock中的）
poetry install
# 激活虚拟环境
poetry shell
# 锁定依赖（install时自动生成或更新poetry.lock）
poetry config virtualenvs.in-project true。
3.4 环境搭建完整流程（SVG图）
下面这张图是我整理的完整环境搭建流程。跟着走，不会乱。
3.5 实战中的一些坑
讲几个我踩过的坑，你以后可能也会遇到。
- Python版本混用：同一个项目，有人用3.8，有人用3.11。结果3.8上依赖解析出失败。解决办法：在项目根目录放一个
.python-version文件（pyenv读取的），或者直接在pyproject.toml里指定[tool.poetry.dependencies] python = "^3.9"。 - 忘记激活虚拟环境：直接
pip install把依赖装到了系统Python里，然后poetry install报错。我遇到过同事把pandas装到系统环境，项目里还用poetry，最后跑测试时发现两个版本冲突。 - lock文件没进版本控制：这是最致命的。没有poetry.lock，你的依赖版本就是浮动的。昨天能跑，今天可能就不能跑了。我曾经因为这个问题在产品环境上排查了一整天，最后发现是一个依赖的小版本升级引入了bug。
3.6 用IDE辅助环境管理
说实话，命令行再熟练也不如IDE帮你自动识别环境来得省心。我用PyCharm和VS Code都很多，简单说下配置：
- PyCharm：打开项目，点击右下角Python Interpreter，选择“Add Interpreter” -> “Poetry Environment”，它会自动找到项目的poetry虚拟环境。
- VS Code：按
Ctrl + Shift + P，输入“Python: Select Interpreter”，选择“Enter interpreter path” -> 输入~/.cache/pypoetry/virtualenvs/你的项目名*/bin/python。或者装Poetry插件，直接识别。
我个人的习惯：先用poetry把环境建好，然后用IDE打开项目时直接选那个虚拟环境。一旦选好，终端、调试器、代码补全都用同一个环境，再也不会出现“终端能跑，IDE里却报模块找不到”的问题。
好，环境搭好了。接下来就可以开始写真正的审计SDK代码了。