本文介绍如何在 CI 环境中高效检测 JSON 文件的顶层键（top-level keys）是否重复，重点使用 jq 的流式解析能力实现零依赖、高可靠性的校验方案，并解释其原理与局限性。
本文介绍如何在 ci 环境中高效检测 json 文件的顶层键（top-level keys）是否重复，重点使用 `jq` 的流式解析能力实现零依赖、高可靠性的校验方案，并解释其原理与局限性。
在 JSON 规范中，重复键是语法合法但语义危险的：ECMA-404 明确允许重复键，而 RFC 8259 则强烈建议（SHOULD）键名唯一——因为不同解析器行为不一致：有的保留最后一个值，有的报错，有的静默丢弃。这使得重复键成为 CI/CD 流水线中典型的“隐性缺陷”，尤其当 JSON 用作配置文件或 API Schema 时，极易引发线上行为偏差。
幸运的是，标准工具链提供了无需编写脚本即可检测重复键的方法。核心思路在于：利用 JSON 解析器对重复键的两种不同处理时机产生可观察差异。
✅ 推荐方案：jq --stream + unique 校验（健壮、跨平台）
jq --stream 以“事件流”方式逐字节解析 JSON，在对象键被合并前就输出原始路径；而普通 jq . 会先完成完整解析（此时重复键已被后一个值覆盖）。我们提取所有顶层对象键（即流中形如 ["keyname"] 的路径），再判断去重前后是否一致：
# 检测顶层键重复：返回 true 表示无重复，false 表示存在重复 jq --stream -n ' [inputs[-2] | select(type == "string")] | sort == unique ' file.json
? 原理说明：inputs[-2] 提取流中每个对象成员的父级路径的倒数第二个元素——对顶层键而言，就是键名本身（如 "id1"）；select(type == "string") 过滤出纯字符串键名；sort == unique 判断排序后数组是否与去重后数组完全相等（二者均有序，可直接比较）。
✅ 优势：
- 不依赖 Python 或其他运行时，纯 Shell 可执行，天然适配 CI；
- 兼容 jqlang/jq 和 itchyny/gojq（后者虽自动排序键，但本方案在解析前提取，不受影响）；
- 仅扫描一次输入，性能优异（O(n log n) 主要在 sort，实际极快）。
⚠️ 替代方案：diff 对比法（需注意兼容性）
早期常见做法是对比 --stream 与 tostream 输出差异：
diff -q <(jq --stream . file.json) <(jq tostream file.json) >/dev/null && echo "OK" || echo "ERROR: duplicate keys"
⚠️ 风险提示：该方法在 gojq 中可能误报——因其 tostream 会先解析再排序键，导致无重复但顺序不同的 JSON 也被判定为不一致。不推荐用于生产 CI。
? 注意事项与最佳实践
- 仅检测顶层键：上述方案默认只检查根对象的直接子键（如 "id1"、"id2"）。若需递归检测嵌套对象中的重复键，需扩展逻辑（例如用 path(..) | select(length == 2 and .[0] == "some_nested_obj")），但通常配置文件只需保障顶层唯一性。
-
空文件/非对象输入需防护：添加前置校验避免 jq 报错：
jq 'if type == "object" then true else error("Not a JSON object") end' file.json >/dev/null || { echo "Invalid input"; exit 1; } -
CI 集成示例（GitHub Actions）：
- name: Validate JSON keys uniqueness run: | if ! jq --stream -n '[inputs[-2] | select(type == "string")] | sort == unique' data/config.json; then echo "❌ Duplicate top-level keys found in config.json" exit 1 fi shell: bash
✅ 总结
检测 JSON 重复键不应依赖语言特定解析器（如 Python 的 object_pairs_hook），而应利用成熟 CLI 工具的底层解析特性。jq --stream 方案以声明式、无副作用、高兼容的方式，在语法层捕获语义风险，完美契合自动化流水线对确定性、可观测性、低维护成本的要求。将此检查纳入 CI，是提升配置可靠性与团队协作质量的关键一步。
