脚本升级依赖：从旧版迁到新版并跑一遍对照

依赖升级最危险的不是报错，是跑通了但结果变了。一个默认值反转、一次排序不再稳定，脚本照常产出文件，数字却和上个月对不上。本文给一套四步对照法：先录黄金样本，再逐个升，最后逐字段 diff。

一句话结论

升级要分三层验：能不能导入（语法层）、能不能调用（接口层）、结果是不是同一个（行为层）。前两层会直接报错，第三层不会——它会静默产出不一样的数字。所以升级前必须先录黄金样本：固定输入 + 完整输出快照，升级后重放并逐字段比对。一次只升一个依赖，因为一次升五个时，结果变了你不知道是谁干的。我这次 6 个直接依赖、23 个传递依赖，升级后报错 1 处、静默行为变化 2 处，12 组样本里 2 组结果不同。

这篇解决什么问题

三种情况最常见。一是升完跑通了就上线，一周后发现汇总数字比上月少了 3%，回头查不出是哪天开始的。二是一次把所有依赖升到最新，出错后无从定位，只好整体回退，白升一遍。三是依赖没锁，某天重装环境自动装了新版本，本地和服务器结果开始不一致。

根子是把升级当成安装任务，而它其实是回归验证：升级的价值在于安全与性能，代价是行为可能变。五步做完，得到一份黄金样本、一份依赖分层清单、一份逐字段差异报告，以及一份写清「哪些行为变了」的迁移说明。

开始前要准备什么

• 完整依赖清单，含传递依赖：直接写的 6 个之外，还有 20 多个被间接装进来的。只升直接依赖，传递依赖照样会跟着动。
• 12 组黄金样本：覆盖主流程、边界值、空输入、异常输入四类。样本要固定成文件，不要每次现造。
• 输出快照的粒度：表格（逐行逐列）、日志（关键行）、JSON（逐字段）、生成的文件（哈希）。粒度太粗会漏掉静默变化。
• 能回退的环境：锁文件 + 虚拟环境。没有回退能力时，不要在有流量的机器上直接升。

具体怎么做

第一步：先在旧版本上录黄金样本

这一步必须在升级之前做，而且要在旧环境里做。12 组输入跑完，把四类输出全部存成文件：结果表格、运行日志、结构化输出、生成文件的哈希。存的时候连同环境版本一起记——否则一周后你不知道这份样本是哪套依赖跑出来的。

我要升级一个数据处理脚本的依赖，升级前需要先建立黄金样本。这是我的脚本功能与输入输出结构：
（粘贴）

请帮我设计样本集，要求：
1. 12 组输入覆盖四类：主流程、边界值、空输入、异常输入，说明每组想验证什么；
2. 每组要保存哪些输出（表格逐行、日志关键行、JSON 逐字段、文件哈希），以及为什么这一组需要这个粒度；
3. 给一份样本清单表头：样本编号、输入文件、验证目标、输出类型、采集时间、环境版本；
4. 指出哪几组最可能暴露「静默行为变化」（提示：涉及默认值、排序、日期与浮点的部分）。

不要建议具体依赖版本，只设计验证方案。

第二步：把依赖分成三层，先看传递依赖

三层是：直接依赖（代码里 import 的）、传递依赖（被直接依赖拉进来的）、系统级（解释器版本、C 库、编解码器）。传递依赖最容易被忽略，而行为变化往往发生在它身上——你升了一个库，它顺手把一个底层库从 1.x 拉到 2.x。

这是我的依赖清单（直接依赖 6 个，锁定文件里的全部依赖 29 个）与脚本里实际 import 的位置：
（粘贴）

请帮我做四件事：
1. 按「直接依赖 / 传递依赖 / 系统级」三层归类，标出每个直接依赖拉进来的传递依赖有哪些；
2. 指出哪几个传递依赖的风险最高（被多个直接依赖共用、或版本跨度大）；
3. 给一份升级顺序建议：先升哪些、为什么，以及哪几个建议单独升、不与别的混在一起；
4. 标出哪些依赖一旦升级会要求更高的解释器版本，导致连锁升级。

要求：只做分析与排序，不要给具体版本号。

第三步：一次只升一个，升完立刻重放

升一个、跑 12 组样本、比对、通过再升下一个。听起来慢，但比一次升完再回溯快——后者出错时无定位能力，只能整体回退。每轮记录三件事：升了哪个、哪些样本结果变了、变化是预期还是意外。预期变化（比如弃用接口的替代写法）要在迁移说明里写清。

我采用「一次升一个」的策略，当前要升的是 ______ 到 ______。请在每轮升级后帮我做一次对照：
1. 给出本轮的双跑脚本思路：用同一批 12 组输入，在旧环境与新环境下各跑一遍，输出到两个目录；
2. 给一份逐字段 diff 的检查顺序（先结构、再数值、后格式），以及每一层常见的假差异（例如时间戳、绝对路径、浮点尾数）；
3. 判断某个差异是「预期变化」还是「回归 bug」的三条判据；
4. 如果发现回归，给出最小回退动作（只回退这一个依赖，不动其他）。

补充：我的脚本会生成 CSV 与 JSON 两种输出。

第四步：逐字段 diff，别只看跑通没报错

比对顺序固定：① 结构（列数、字段名、行数是否变）→ ② 数值（逐行逐列的绝对差与相对差）→ ③ 格式（小数位数、日期格式、编码、换行符）。静默变化几乎都藏在第 2 层：列名没变、行数没变、格式没变，只有几个数字不一样。

这是我新旧两版的输出（两个目录，同名文件）。请帮我写一个比对脚本的规格说明：
1. 结构层：比对列名、列顺序、行数，输出差异表；
2. 数值层：对数值列算绝对差与相对差，超过阈值（绝对值 ______ 或相对 ______%）的列出来源行；
3. 格式层：比对小数位数、日期字符串格式、文件编码与换行符（CRLF/LF）；
4. 明确忽略项：时间戳、临时路径、随机 ID、日志里的耗时；

输出一份「差异报告」模板，要求能直接贴进迁移说明。我的环境是 Windows，脚本用 Python 写。

第五步：锁版本，写迁移说明

升级通过后立刻锁版本：直接依赖写精确版本，传递依赖用锁文件固定。然后写一页迁移说明，只写三件事：升了什么（含传递依赖）、哪些行为变了（默认值、排序、格式、精度）、下次升级要注意什么。这一页的读者是三个月后的自己。

这是我本轮的升级结果与差异报告（粘贴）。请帮我写一份迁移说明，结构如下：
1. 升级清单：直接依赖与随之变动的传递依赖、解释器版本；
2. 行为变化：逐条写「哪个依赖、什么默认值或行为、影响哪些输出、如何适配」；
3. 未变化但需注意：本次没变但下次可能变的地方（例如已出现弃用警告的接口）；
4. 回退方式：一行命令，以及回退后要重跑哪几组样本。

风格要求：写给三个月后的自己看，不要写给外部读者；每条都要能独立看懂，不依赖上下文。

实测记录

口径：脚本 420 行，直接依赖 6 个、锁定文件里 29 个依赖，12 组黄金样本（主流程 5、边界 3、空输入 2、异常 2），输出为 CSV + JSON + 日志。

• 升级范围：6 个直接依赖里 3 个有大版本变化，连带 4 个传递依赖升版，解释器从旧版升到新版。
• 报错：1 处，是弃用接口被移除，改写法后通过——这类最容易发现，因为直接报错。
• 静默变化：2 处。一是某依赖的默认参数反转，导致一列缺失值从「保留空值」变成「填 0」；二是字典遍历顺序不再保证，导致输出的行顺序与旧版不同（内容相同，顺序不同）。
• 样本命中：12 组里 2 组结果不同，都来自上面两处静默变化；如果只跑主流程 5 组，第 2 处会被漏掉。
• 耗时：录样本 1.5 小时、逐依赖升级与对照 2 小时、写迁移说明 20 分钟，合计约 4 小时。对照一次性全升的做法：出错后整体回退再重来，实测同样 4 小时以上，但没有定位能力。

最容易错的 3 个地方

第一，只测主流程。主流程 5 组覆盖的是「正常数据」，而静默变化常发生在边界与空值上：默认值反转后，空值被填成 0，正常数据看不出差别。这次第 2 处变化就是靠异常输入的样本才发现的。

第二，一次升全部依赖。升五个之后结果变了，你无法判断是哪个造成的，只能整体回退。一次一个虽然要跑五轮样本，但每轮都能定位到具体依赖，四小时能收工；整体回退再重来通常超过四小时，而且第二次仍可能踩同一个坑。

第三，不锁版本。不锁的后果不是当天出问题，是某次重装环境后自动装了新版本，本地与服务器开始不一致，而你会先怀疑代码。锁文件进版本库，是让「环境可复现」的最低成本。

可复用的东西

黄金样本 12 组：主流程 5、边界 3、空输入 2、异常 2。少一组异常输入，就可能漏掉默认值反转。

三层验证：能导入 → 能调用 → 结果同一个。前两层报错，第三层静默。

diff 顺序：结构 → 数值 → 格式。忽略项固定为时间戳、临时路径、随机 ID、耗时。

迁移说明三段：升了什么、哪些行为变了、下次注意什么。附一行回退命令。

如果你也经常要做这件事，欢迎在评论区说说你的卡点和做法；也可以留言告诉我，你想看哪个岗位的哪件活怎么用 AI 拆。

admin 普通

收藏 海报 链接