jq 默认值处理：别把缺失、null 和 false 混为一谈
配置文件里 enabled=false 明明表示关闭，经过一段 jq 过滤后却变成 true，问题往往出在默认值语义。字段不存在、字段显式为 null，以及字段为 false，是三种不同输入。本文以 jq 1.7 手册为依据，使用 POSIX shell 风格引用；在其他 shell 中运行时需调整引用方式，不能直接假设单引号行为相同。
AI生成概念配图：缺失字段、空值和关闭开关被分别放入不同数据槽。仅辅助理解，不代表真实界面或实测结果。
先用最小样本观察差异
printf '%s\n' '{}' '{"enabled":null}' '{"enabled":false}' |
jq '{present: has("enabled"), value: .enabled}'访问不存在的对象字段时，.enabled 也会产生 null，所以只看这个值无法区分前两种输入。has("enabled") 检查键是否存在，即使它的值为 null 或 false，也仍然返回存在。这里假定输入为对象；若实际可能混入数组、数字或字符串，应先检查类型，不要用错误抑制把结构异常静默隐藏。
替代运算符会跳过 false
printf '%s\n' '{"enabled":false}' | jq '.enabled // true'
printf '%s\n' '{"count":0}' | jq '.count // 10'
printf '%s\n' '{"name":""}' | jq '.name // "default"'第一条会得到 true，后两条则保留零和空字符串。jq 的 // 会在左侧没有合适输出，或仅有 null、false 时使用右侧结果，并不等于“只在 null 时回退”。这与某些语言的空值合并写法不同，尤其不能直接用在允许 false 的开关配置上。空数组也不是自动触发默认值的条件。
另一个容易混淆的点是 jq 处理的是输出流。empty 表示不输出任何结果，不是输出一个 null；过滤器可能产生多个结果。若下游期望恰好一个配置对象，应显式保证输出数量和结构，不能把“命令成功退出”当成已得到一个完整对象。
先写清需要哪一种默认规则
# 仅在字段不存在时使用默认值，显式 null 仍保留
jq 'if has("enabled") then .enabled else true end' config.json
# 缺失或显式 null 时回退，但保留 false
jq 'if .enabled == null then true else .enabled end' config.json这两条解决的契约不同。第一种适合 null 本身有业务含义的接口，第二种适合把 null 当作未设置的配置。示例依旧假设 config.json 是对象，且只演示读取结果。真正落盘时，应先写新文件、检查结构与权限，再执行经过批准的替换；不要用同一路径同时做输入与 shell 输出重定向，否则可能先把输入文件清空。
不要让默认值代替类型验证
jq -e '
if type == "object" then
has("enabled") and (.enabled | type == "boolean")
else false end
' config.json如果业务要求字段必须存在且为布尔值，验证比回退更清楚。上例产生布尔结果，并用 -e 让 false 对应非零退出状态，方便脚本阻止后续步骤。它不会自动把字符串 "false" 转成布尔 false；自动转换应有明确规则，否则拼写错误可能被掩盖。多个 JSON 文档输入时，还要注意 -e 与最后输出结果的关系，不能拿一次状态替代逐项校验。
当过滤条件来自外部变量时，使用 --arg 或 --argjson 等数据参数机制，不要把用户输入拼进 jq 程序。JSON 字符串转义与 shell 引用是不同层，混在一起容易出现代码注入或意外改变查询含义。日志中只记录必要的校验失败信息，避免把完整配置和密钥打印出来。
用边界样本固定契约
为缺失、null、false、true、零、空字符串、错误类型和多文档输入分别保存预期输出。每次修改默认规则时重跑这些样本，尤其检查开关是否被意外打开。jq 很擅长精确变换数据，但它不会替你决定“未设置”与“明确关闭”是否同义；这项决定应该先写进配置规范。
