Linux工具配置升级：写一个保留原文件的迁移器，比自动改完更可靠

工具更新后，旧配置不再符合新格式，用户常遇到两种糟糕体验：程序直接启动失败，却没说怎么改；或者启动时自动迁移，等出问题才发现原文件已经被覆盖。

配置迁移值得成为独立、可检查的操作。它负责解释旧格式并生成候选，是否启用候选则是另一项决定。本文用一个很小的版本变更演示这条边界，不修改任何实际工具配置。

示例只改结构，不偷偷改单位

假设旧格式为：

{"version": 1, "timeout_ms": 1500}

新格式将请求相关参数归到同一个对象：

{"version": 2, "request": {"timeout_ms": 1500}}

这次迁移只移动字段位置，超时单位仍是毫秒，值保持1500。没有理由在格式迁移时顺便调整默认值。若确实需要改变语义，应另外写清变更规则与影响，而不是让用户从运行行为中猜出来。

本文示例接受100到60000之间的整数，这是人为设计的输入合同，不是所有工具都适用的超时范围。

转换函数先严格检查

import copy, json, tempfile
from pathlib import Path
def migrate(old):
 if type(old) is not dict or set(old)!={'version','timeout_ms'}:
  raise ValueError('unknown or missing fields')
 if type(old['version']) is not int or old['version']!=1:
  raise ValueError('unsupported version')
 ms=old['timeout_ms']
 if type(ms) is not int or not 100<=ms<=60000:
  raise ValueError('invalid timeout')
 return {'version':2,'request':{'timeout_ms':ms}}

函数不原地修改输入，返回一个新的对象。未知字段直接拒绝，是为了让评审者注意到尚未定义的迁移规则。真实产品也可以选择保留扩展字段，但应明确哪些字段可扩展，以及旧程序能否忽略它们；不能悄悄丢掉用户配置。

这里用 type(ms) is int，避免把布尔值当作整数接受。版本号也需要明确类型，不能只因为数值比较相等就认成受支持版本。

这段函数假设已经拿到解析后的字典。JSON解析错误、重复键检测、文件大小限制等属于输入读取层，本文没有实现完整的配置加载器。不要直接把示例当成面向任意不可信文件的生产工具。

输出候选时，不覆盖同名文件

解析并转换成功后，可以把结果写到单独的候选路径：

with open(candidate_path, 'x', encoding='utf-8') as f:
    json.dump(new_config, f, ensure_ascii=False, indent=2)

candidate_path 应是用户确认的输出位置，不能从旧配置里的任意字段直接拼出。Python官方open文档说明，x 模式用于独占创建，目标已存在时失败；它与会截断已有文件的 w 不同。

独占创建防止覆盖已有候选，但不保证写入过程一定完整。中途磁盘错误或程序退出，仍可能留下不完整文件。工具应把“已生成并检查完成”和“残留候选”区分开，失败后明确报告位置，让用户复核处理。本文不承诺断电持久性，也没有测试磁盘故障。

图中目标程序验证是拟定的交付流程，本文没有真实目标程序，尚未执行这一阶段。候选文件可解析，只能说明格式读取成功，不代表业务行为符合预期。

本次实际验证的范围

本次用本机Python和独立临时目录完成以下检查：旧版本合法输入得到预期新结构；原字典未被修改；未知版本、布尔超时值、额外未知字段分别被拒绝；写入候选后重新解析得到预期对象；原文件字节保持不变；再次向同名候选独占创建会失败。

所有断言通过。实验没有覆盖在用配置、没有重启服务、没有执行Linux部署，也没有安装软件。测试值均为合成数据，不涉及真实项目。

给使用者看的迁移说明要具体

工具可以在写入前展示变化摘要：版本从1变成2，timeout_ms 移入 request，单位和值不变，原文件保留。报错也应指出是版本不支持、字段不认识，还是候选路径已经存在，不要统一归为“配置错误”。

候选启用前还需要适合目标程序的验证入口。若程序支持只检查配置、不启动任务的模式，可在独立环境中调用并记录结果；若不支持，就应设计可控的试运行方法。本文没有虚构一个检查命令来冒充已有能力。

回退也不能只写“复制回去”。需要知道旧程序是否仍可用，旧配置与旧程序是否匹配，以及切换后是否已经产生了新格式状态。配置备份只解决了文件保留问题，未必解决版本兼容问题。

把转换、候选复核、运行验证和启用分开，用户遇到失败时才知道自己停在哪一步。对需要独立维护的Linux工具来说，这种清楚的操作边界，比一键迁移的表面顺滑更有价值。