框架小版本升级不是改个版本号：SAPI 一致、依赖门槛与缓存重建
一、先分清”声明的版本”和”实际加载的版本”
该升级说明把第一条动作写得很直白：先用命令行查实际加载的版本，不要相信包里声明的版本。这句话看着啰嗦，实际是所有小版本升级事故的第一现场。
声明版本和加载版本会在四种情况下分岔。一是仓库里存在多份同名包，项目根一份、某个子模块里又一份，自动加载顺序决定了哪一份生效；二是传递依赖被锁死，升级命令跑完显示成功，那个被别的包约束的组件根本没动；三是部署包里没打进要更新的那部分，本地开发环境已经是新版，线上还是旧版；四是节点没更新到，滚动过程里有一台因为磁盘满或者权限问题静默失败，只有它的目录里还是旧代码。这四种情况的共同点是版本号看起来都对，报错一个也没有。
所以我们把”版本探针”当成上线前的固定动作：一个只返回框架版本、运行时版本与关键组件版本的接口，加上一条在命令行上打印同一组信息的脚本。两个出口都要有，因为线上出问题时你需要分别确认两种运行环境下加载的是不是同一份。探针本身要放在内网或者加鉴权，不要把版本号大方地塞进公开响应里。
二、命令行与 Web 侧的解释服务必须同版
该升级说明里另一条硬性要求是运行时版本区间与推荐档，并要求命令行与 Web 侧的解释服务版本完全一致。这里要注意分寸：那份说明给出的兼容区间与推荐版本是它针对自己项目的口径，我们不能把它写成放之四海的选择依据，更不该据此推断性能提升或者安全性。
要讲的是”为什么必须一致”这一条通用原因。同一段代码在两种运行环境里行为可能不同：序列化格式对不齐，命令行生成的缓存或队列消息，Web 侧解不出来，反过来也一样；时区与本地化处理的默认值不同，日期字符串的格式化结果就差一个时刻；整数与浮点的转换边界、字符串拼接时的隐式类型，不同编译选项下表现并不完全一样。这类问题的表现极具欺骗性：页面点击按钮一切正常，同一个逻辑跑成定时任务就写坏了数据，或者反过来。排查时人的第一反应是”代码只有一份”，于是把力气全花在业务分支上，实际是运行环境不一致。
一致性检查要落到三个可核对的东西上：两条命令各自打印的版本、各自加载的配置文件路径、各自的接口类型。只看版本号是不够的，这一点在运行时升级里同样成立。
三、升级前的三张清单
这份说明之所以值得当成一套验收方法来读，是因为它把动作拆到了可以照抄成清单的程度。我们把它整理成升级前必须填完的三张表。
| 清单 | 要填的字段 | 填不出来时说明什么 |
|---|---|---|
| 节点与运行环境矩阵 | 主机标识、角色、运行时版本、接口类型、配置文件路径、该节点的包目录位置 | 有人只知道自己那台能跑，没人有全环境视图 |
| 依赖版本门槛 | 直接依赖与传递依赖的当前版本、要求版本、被谁约束、是否存在冲突 | 升级命令会静默保留旧版本 |
| 缓存与持久化格式兼容 | 结构缓存、路由缓存、日志目录、会话存储、已落库数据的序列化格式，逐项标新旧可读性 | 回滚方案其实是不可执行的 |
第二张清单里，该说明给出的做法值得单独一说：更新框架要把依赖一起更新，并用依赖树查询命令定位到底是哪个包在阻塞。”哪个包在阻塞”是个非常具体的问题，答案要么是一个可以直接松绑的约束，要么是一个不能动的旧组件，两条路的工期完全不同。不查清楚就开始升级，等于把可控操作换成不可控操作。
第三张清单最容易被跳过，因为它的价值要到回滚那天才体现。
四、故障行为开关怎么评审
该说明里有一条容易被当成脚注的信息：缓存组件新增了一个名为 fail_delete 的配置，默认为关闭，用途是在缓存后端故障时决定是保留旧缓存还是删掉。同时它列出另两个强依赖组件的最低版本门槛，一个关系到枚举绑定能力，一个修复多种存储驱动并发写入的问题。按说明的口径转述即可，不宜外推。
真正值得抄下来的是这类开关的通用形状。所谓”故障时行为开关”，是把系统在依赖不可用时的选择显式写成一个配置项，并且默认值保持旧行为。它的评审要点只有四条：
- 默认值是不是最保守的那个。默认关闭意味着升级当天没有人被新行为影响，这是对的；但如果你的业务其实需要”故障时立刻删掉脏值”，那默认值要在评审时被明确改成开启并记录理由。
- 两种选择各自对应什么故障。保留旧缓存意味着读到过期数据但服务不断；删掉意味着读不到数据但不会给出错的。前者适合展示型内容，后者不能接受错误值时才有意义。这两条判断必须写进文档，不能留在配置名里。
- 开关生效是否需要重启，能不能只对某个缓存分组生效，以及配置来源在哪。
- 有没有做过故障演练。没在受控环境里把缓存后端真的停过一次，这个开关的语义就还是纸面理解。
日志侧同理，那份说明提醒要检查单文件与按日切分两种配置以及标识项——升级时最常丢的不是日志内容，而是”这条日志是哪个节点哪个分组产生的”这个标识。
五、上线五步验收与回滚的最小方案
该说明给出的收尾动作是：上线前清空各节点的运行目录，包括缓存、日志与路由那几处，再逐台重启，并重建结构缓存，最后核对响应头里的框架版本字段。把它按顺序展开，就是分布式小版本升级的五步验收。
- 灰度一台：清运行目录、重启、跑关键路径，确认这一台的行为与旧版一致或按预期变化。
- 重建结构缓存：模型结构缓存与路由缓存必须由升级动作触发重建，不能指望它自己过期。
- 逐台滚动：每台重复第一步与第二步，节点之间不留混合运行时间过长。
- 全节点核对探针：版本探针接口与命令行输出逐台比对，同时核对响应头里的版本字段，确认没有节点掉队。
- 关键路径回归：登录、写入、跨存储驱动的文件操作、按方法装配中间件的那几条路由，跑固定用例。说明里新增的分组级路由默认地址与绑定也归到这一轮：没有启用的部分，行为要与旧版逐项一致；启用了的，单独出一条用例，不要混在通用回归里看结果。
结构缓存与路由缓存残留的故障表现要说得具体才有人信。字段加了一个，模型仍按旧结构写入，新字段在库里是默认值，界面上看着”存了但没生效”；路由规则改了，请求还走旧分支，改的代码在仓库里躺着，测试却复现不出来。这两种都不会报错，只会让一部分节点跑旧逻辑。这也是为什么”清空运行目录再重启”是验收步骤而不是清理习惯。
回滚的最小方案要回答两个问题：代码回退之后，新版写下的数据与已经重建的缓存旧版能不能读；以及能不能只回滚一台。第二个问题的答案通常是否定的——结构缓存与路由缓存不一致的节点会给出另一种旧行为。所以回滚单元是”全部节点加一次缓存重建”，不是某个部署包。这就是第三张清单存在的意义。
六、对交付项目意味着什么
站在洹拓做交付的位置，这类升级的合同范围必须写清三件事：升级是否包含依赖门槛的松绑与随之而来的兼容性验证；命令行与 Web 侧解释服务的一致性是否算验收项；版本探针与关键路径回归由谁执行、结果以什么形式存档。没写进去的，客户会认为是”你们顺手就该做完的”，而我们只能按变更单报价。
客户环境的现实样子也值得提前说明：多台老节点、运行时版本不统一、有按站点绑定的历史配置、有的节点上还跑着没人维护的旧入口。在这种环境里说”已经升级完成”，判据只能是节点一致加探针核对通过，不是仓库里的版本号变了。把这句话写进验收单，比多解释十遍技术细节有用。