📚 课程目录第4章环境准备

环境准备：更新依赖与 SDK 安装

说实话，迁移项目最怕什么？不是代码逻辑复杂，而是环境没搭好，半天跑不起来。V1 到 V2 的依赖变化不小，我刚开始接手这个迁移时，以为直接把版本号改了就完事，结果一运行就报错——依赖冲突，SDK 找不到，折腾了大半天。所以这一章，我把踩过的坑都拎出来，咱们一步一步把环境搞干净。

为什么要更新依赖？先看看 V1 和 V2 的区别

你想想看，Secrets SDK V2 换了底层核心。V1 用的是 secrets-client-core 1.x，V2 换成了 2.x。不止版本号变了，包名也改了，依赖树完全不一样。

模块	V1 依赖	V2 依赖
核心 SDK	`secrets-sdk==1.8.0`	`secrets-sdk-v2==2.0.0`
传输层	`requests>=2.20`（内置）	`httpx>=0.24`（独立依赖）
认证库	`authlib==0.15`	`authlib==1.2`
数据序列化	`msgpack==1.0`	`msgpack==1.1`

看明白了吗？传输层从 requests 换成了 httpx，这俩虽然功能类似，但 API 不同。我之前在项目里直接升级，结果 requests.Session 的代码全部要改——这是个大坑，后面避坑指南会细说。

更新依赖的具体步骤

我习惯把环境隔离干净再做迁移。下面两个场景我都试过，选一个适合你的。

场景一：用 pip 直接管理（简单项目）

先导出当前 V1 的依赖快照：
```
pip freeze > requirements-v1.txt
```

然后卸载旧 SDK 及其相关包：

pip uninstall secrets-sdk secrets-client-core -y

安装 V2 家族：

pip install secrets-sdk-v2==2.0.0 secrets-client-core==2.0.0 httpx authlib==1.2

验证安装列表，确保没有残留的 V1 包：
```
pip list | grep secrets
```

一个小技巧：安装后运行 pip check 检查依赖冲突。我之前在升级 msgpack 时碰到过版本不兼容的问题，pip check 直接报了出来，省了半小时调试时间。

场景二：用 poetry 管理（推荐团队项目）

如果你在用 poetry，更新会更可控。我个人的做法是：

在 pyproject.toml 里修改依赖声明：

[tool.poetry.dependencies]
python = "^3.9"
# 删除 V1 行: secrets-sdk = "^1.8"
# 添加 V2 行:
secrets-sdk-v2 = "^2.0"
secrets-client-core = "^2.0"
httpx = "^0.24"
authlib = "^1.2"

执行更新：
```
poetry lock
poetry install
```
确认虚拟环境中没有旧包：
```
poetry show | grep secrets
```

注意 poetry lock 这一步会重新解析整个依赖树。我遇到过 poetry 把 httpx 解析成 0.23 版本的情况——因为 authlib 1.2 对 httpx 版本有约束，必须手动指定 httpx = "^0.24" 加 authlib = "1.2" 并锁定。

SDK 安装验证

环境装完不等于能用。我每次都会跑一个最小验证脚本，确保 SDK 能正常加载。

# verify_install.py
try:
    from secrets_sdk_v2 import Client, config
    print("✅ secrets-sdk-v2 核心模块导入成功")

    # 检查版本
    from secrets_sdk_v2._version import __version__
    assert __version__.startswith("2."), f"版本号不正确: {__version__}"
    print(f"✅ SDK 版本: {__version__}")

    # 检查 httpx 可用
    import httpx
    print(f"✅ httpx 版本: {httpx.__version__}")
except Exception as e:
    print(f"❌ 验证失败: {e}")
    exit(1)

核心检查项：

V2 模块名是 secrets_sdk_v2（注意下划线），不是 secrets_sdk
版本号必须以 2. 开头
httpx 必须 >=0.24.0

避坑指南：我踩过的三个问题

⚠️ 坑一：pip 残留旧包

我曾经直接 pip install secrets-sdk-v2，没有卸载旧版。结果运行时导入了 V1 的 secrets_sdk 模块，导致 Client 类方法签名不匹配。解决方案：先 pip uninstall secrets-sdk secrets-client-core，再装新的。

⚠️ 坑二：httpx 与 authlib 版本锁死

V2 里 httpx 的异步客户端 AsyncClient 需要 httpx==0.24.1 以上才能正常配合 authlib 1.2 的 OAuth2Client。有一次我装了 0.23，结果认证报 AttributeError: 'AsyncClient' object has no attribute 'auth_flow'。切记：httpx>=0.24。

⚠️ 坑三：poetry.lock 文件冲突

团队协作时，如果有人忘了更新 poetry.lock，其他人 poetry install 可能装成 V1 的依赖组合。我建议每次迁移前先 git rm --cached poetry.lock，然后重新 poetry lock，把新 lock 文件提交。

知识图谱：从 V1 依赖到 V2 的环境准备流程

下面这张图概括了从旧环境清理、依赖更新、SDK 安装到最终验证的完整路径。建议你照着走一遍，别跳步骤。

说白了，环境准备就三步：清干净、装全新、验得细。别贪图省事跳过任何一步，否则后面迁移业务代码时会反复撞墙。我当初就是觉得“没事，直接覆盖安装”，结果花了两天排一个导入错误——教训深刻。

现在你的开发环境已经就绪，SDK 跑通了。下一件事是什么？当然是开始真正写迁移代码了。