
两个配置文件可以逐字节都不相同,却描述同一个系统。这是配置文件语义 Diff(Config File Semantic Diff)的前提。我重写了它的比较逻辑,再拿工具自己的解析器去跑,确认 JSON 和 YAML 都成立。这篇里的每个数字都是这样量出来的。但有两种输入会打破这个前提,其中一种是 08080 这个数。
四种差异,差异的种类比它的值更重要
这个工具的承诺很窄,也很精确:按键路径比较,忽略排序和格式噪声。实现确实守住了它。两边先各自解析成普通值,JSON 走 JSON 解析器,YAML 走 js-yaml,TOML 走 TOML 解析器,dotenv 走一个手写的解码器,解析完才开始比。
比较是对两棵值树的递归遍历。到每个节点,它先问一个问题:类型一样吗?不一样,就把这个节点记成类型变化,遍历到此为止。类型一样且两边都是对象,就降进两者键的并集,按键名字母序走。类型一样且两边都是数组,就按下标走。类型一样且两边都是标量,直接比。
拿工具自己公布的两个例子来量,这套遍历两个都精确复现:跨格式的 JSON/YAML 那一对报 1 处 changed,其余各类都是 0;dotenv 审计报 1 处 added、1 处 removed、2 处 changed。这些数和工具元数据里写的完全一致,在拿它去处理更大的文件之前,这是一次有用的校验。
于是有了四类差异:added、removed、changed、type-changed。工具自己的第一个例子,把一个 JSON 部署配置和同一份文件的 YAML 版本放在一起,键的顺序打乱了,端口从 8080 挪到 9090。工具只报了 1 处差异:server.port 从数字 8080 变成数字 9090,顺序重排没有贡献任何一条。
这是个好设计,也解释了为什么语义 diff 会比同样两个文件的逐行 diff 短。它的意义在于换掉了工具所回答的问题:它问的是哪几项设置挪了,不是哪几行挪了。代价是,要理解变化必须去读路径,因为整条信息都在路径里。
想拿自己的一对文件跟着做,可以在配置文件语义 Diff里跑一遍。
键路径才是真正的接口
输出不做逐行对比,给的是一张键路径表,每行标着种类,带着新旧两个值。这张表好不好读,取决于路径的语法规则。
知道规则就很简单。由字母、数字、下划线、美元符或连字符组成的键,用点号接在父级后面。数组下标放进方括号。键本身含点号的,方括号再加引号,因为裸的点号会有歧义。文档的根写作 $。
所以 server.port 是名为 server 的对象里一个叫 port 的键。plugins[0] 是 plugins 数组的第一个元素。outer["my.key"] 是一个字面上就含点号的键,m[0].k 则是数组第一个元素里叫 k 的键。
这种不对称值得记住。像 my-key 这样带连字符的键渲染成 outer.my-key,读起来像个点分路径;像 my.key 这样含点号的键渲染成 outer["my.key"],读起来完全是另一回事。同样的逻辑结构,只因为键里恰好有什么字符,就产出了两种样子差得很远的地址。
实际用起来,你搜的就是这个。diff 给你一个 server.port,你要在仓库里定位它,搜的是路径,不是值。一个键多了个点号、路径就变样的设计,会给你每一次对 CI 输出跑 grep 加一点税,而这笔税只在你已经没时间的那一场事故里冒出来。
接着看哪些路径会出现。对象键的顺序被忽略。遍历前会先对键的并集排序,所以同一个对象用两种顺序序列化,差异是 0 条。数组按下标比较,工具也明说了理由:数组内部的顺序通常就是配置语义。
按下标对齐有几个后果,很容易看错。拿一个三元素数组 ["a","b","c"] 来量,五种比法是这样:
- 顺序完全相同:0 处差异。
- 末尾追加一个元素:1 处差异,位置
p[2],种类 added。 - 改动最后一个元素:1 处差异,位置
p[2],种类 changed。 - 倒序成
["c","b","a"]:2 处差异,位置p[0]和p[2]。 - 轮转成
["b","c","a"]:3 处差异,位置p[0]、p[1]和p[2]。
这张表值得看两遍。三个元素倒序只产生两行 changed,不是三行,因为中间那个还在中间,根本不出现在 diff 里。追加一个元素和改动最后一个元素,都落在同一条路径 p[2] 上,只靠种类那一列区分。所以如果你扫一眼 diff 想数「改了几处」,行数是不可靠的替代品;真正告诉你一条路径是新出现的还是被覆盖的,是种类。
举个例子,一次部署把三条插件条目换了个顺序重写,报出来是两行 changed,读起来像某个插件被改了两次,实际上只是两个插件调换了位置。如果你更想看着它重排而不是读文字,JSON 差异可视化会把这次比较渲染成并排视图。
dotenv 解码器替你定了类型
dotenv 没有类型,于是这个工具自己定。不加引号的值若不区分大小写地匹配 true 或 false,变成布尔值。值为 null 或 ~,变成 null。匹配数字模式的值,变成 Number。空值变成空字符串。其余的保持 String。加引号会改变结果:PORT=8080 是数字 8080,PORT="8080" 是字符串 "8080",两者一比,报的是类型变化,值本身没变。

单引号是字面的,不做转义处理。双引号会处理标准转义序列。不加引号的值,在定类型之前会先剥掉行尾的 # comment。
跨格式比较能成立,靠的就是这一步定型。它让 dotenv 里的 PORT=8080 和 YAML 里的 port: 8080 认成同一个 Number,而不是两个长得不一样的 String。也正因为如此,下一节才重要:这个解码器是在真干活,真干活就有棱角。
一份合法的 TOML 文件,会解析成 JSON 而失败
第一个失败很响亮。粘进一份完全合法的 TOML 文件,一行节头写着 [server],下面一行是 port = 8080,让工具自动识别格式。

它不会比这个文件,它会拒收,报错里点的是 JSON,不是 TOML。原因是自动识别例程先看第一个字符,首字符是 [ 就当 JSON 开头。V8 那句经典报错是 Unexpected token s in JSON at position 1。文件是合法的,关于它格式的猜测不是。
修法是下拉框选一下。两边都把 Format 设成 TOML,同一对文件就能干净地比,报出 server.port 从 8080 变成 9090。
问题比一种畸形输入更广。自动识别例程里确实有 TOML 分支,但只有当先前的 JSON 检查和 dotenv 检查都失败,才会轮到它。dotenv 检查接受任何形如 key = value 或 key: value、键以字母开头的行,而所有不带节头的 TOML 文档都符合这个形状。于是没有节头的 TOML 被认成 dotenv,有节头的被认成 JSON。拿一批真实文档扫过去,TOML 分支只在 10 份里命中了 2 份,而这两份的键都以数字或连字符开头,实践中 TOML 很少长这样。
被认成 dotenv 也不是无害的兜底,因为 dotenv 解码器根本不知道 TOML 的值长什么样。内联表 server = { port = 8080 } 被读成字符串 "{ port = 8080 }"。数组 ports = [8080, 9090] 被读成字符串 "[8080, 9090]"。拿它去和含真对象、真数组的 JSON 文件比,你会得到根本不存在的类型变化。有个例子正好印证:节头前面带一行注释的 TOML 文件跳过了 JSON 检查,被 dotenv 检查接住,然后 [server] 那一整行消失,因为它不符合 dotenv 的赋值模式。这张表被压平成一个光秃秃的 port 键,diff 比的是错误的形状,一声不吭。
08080 和 8080 是同一个数
第二个失败一声不响。dotenv 解码器把不加引号的值丢进一个允许前导零的数字模式,再用 Number 转换,于是 CODE=08080 变成数字 8080,CODE=8080 也变成数字 8080。两者一比,工具报 0 处差异。工具认为两份配置一模一样,实际上它们不一样。

VERSION=1.50 和 VERSION=1.5 也是同样下场,两边都变成 1.5,diff 是空的。
这就是经典的前导零问题,而且它恰好落在人在意的那些值上:补零的标识符、账号、邮政编码、纯数字当键名的字符串、以补零数字编码的版本号。这些值任何一个拿去和它不补零的孪生版本比,都会拿到一张「健康证明」。拿四对补零值来量,08080/8080、012345/12345、007/7、1.50/1.5,四对全部报 0 处差异;一对确实不同的对照,被正确报成 1 处差异。
有两点让它比一个解析器怪癖更麻烦。第一,做坏事的是 dotenv 的类型推断,同样的字符串放在 YAML 文件里仍是 String,因为 YAML 有引号字符串这个类型可以退回,这个失败是 dotenv 独有的。第二,它完全没有警告通道:不会提示哪些值看着像数字、可能其实是标识符,也不会告诉你它悄悄做了多少次转换。摘要只说没变。
对策很无聊,也很可靠:把值加上引号。CODE="08080" 是字符串 "08080",拿它和 CODE="8080" 比,得到一行 changed,字符串类型保住了。
就算这样,diff 还是会在哪儿骗你
就算两边格式都手动指定了,这个比较仍在几处保持字面化,值得知道。
类型变化会让遍历停下。{"a": null} 对 {"a": {"x": 1, "y": 2}},是 1 处差异,不是 3 处。对象里的子树根本不会被比,因为遍历已经判定这两个节点不是同一种东西。整棵子树被换掉、diff 只报一处类型变化,它告诉你形状变了,没告诉你底下是什么。
扁平配置和嵌套配置永远不会碰面。dotenv 里的 SERVER_PORT=8080 和 YAML 里的 server.port,对应用而言是同一项设置,diff 却报了两处差异:SERVER_PORT 被移除,server 被添加,因为没有任何路径能让一个扁平键等于一个嵌套键。跨格式比较在两边形状相同时才成立,它不做形状的对齐。
YAML 自带类型惊喜。js-yaml 遵循 YAML 1.2,其中 yes、no、on、off 是 String 而不是布尔值,所以 flag: yes 拿去和 JSON 的 true 比,是 1 处类型变化。不加引号的 YAML 日期会变成 Date 对象,于是 d: 2020-01-01 和 JSON 字符串 "2020-01-01" 一比,是 date 与 string 之间的类型变化。实测下来,YAML 的 yes 那例报 1 处从 string 到 boolean 的类型变化,日期那例报 1 处从 date 到 string 的类型变化。这两种情况下,工具报的都是解析后值的真实差异,而这份真实差异,来自同一种意图的两种写法。
这些都不是缺陷报告,它们标出的是「语义」二字在这里的边界。工具比的是解析后的值。它不知道 PORT 和 server.port 是同一项设置,不知道 YAML 里的 yes 大概是想说 true,也不知道一个补零的代码从头到尾都是标识符。
怎么用才不被烧到
下拉框能选,就把格式指定死。自动识别对 JSON 和 dotenv 没问题,对 TOML 是错的。如果目的不在文件对文件,而在环境审计,环境配置差异可视化器是围绕变量漂移的形状做的。
先看种类列,再看值列。added、removed、changed、type-changed 是四种不同的紧急程度,只看值分不出来。
结果干净得可疑时,数路径,别数行。数组倒序和追加元素,都只出现在一条路径上。
语义上是字符串的 dotenv 值,一律加引号:补零的数字、邮政编码、账号标识、带前导零的版本号。dotenv 文件 diff 为空,请当成一个主张,别当成结论。值看着像数字,先查前导零。
格式本身要是需要转换,HCL-TOML转换器和HCL-YAML转换器在比较前搬动文档时有用。如果要跨一整个技术栈审计配置形状,可以再翻一翻开发工具。
diff 告诉你什么变了,不告诉你本想改什么
我本想指出语义 diff 在哪儿说谎,结果证明的是它比的是语法,而非含义。这不算工具的毛病。配置漂移本来就是这样:一个语法问题穿着语义的外套。让一份 diff 变得可执行的,只有人在某一刻判定,哪一层的含义本该成立。
所以值得留下的那个问题,恰恰是工具替你答不了的:当一条键路径读起来一样,系统行为却不同,你信哪一个?
Pingback: Config File Semantic Diff: When 08080 and 8080 Become the Same Number - COSESAI