DeepDiff 默认启用“阈值深度比较”机制，当字典键交集过小时会将整个子结构标记为 values_changed；通过设置 threshold_to_diff_deeper=0 可禁用该机制，强制逐层比对，从而准确识别 dictionary_item_added、dictionary_item_removed 和细粒度 values_changed。
deepdiff 默认启用“阈值深度比较”机制，当字典键交集过小时会将整个子结构标记为 `values_changed`；通过设置 `threshold_to_diff_deeper=0` 可禁用该机制，强制逐层比对，从而准确识别 `dictionary_item_added`、`dictionary_item_removed` 和细粒度 `values_changed`。
在使用 DeepDiff 对嵌套 JSON（或 Python 字典）进行差异比对时，你可能遇到一个常见但易被忽视的问题：本应被识别为键新增/删除的变更，却统一被归类为 values_changed，且整个嵌套字典被当作一个整体处理。例如：
from deepdiff import DeepDiff
expected = {"name": "Cake", "image": {"width": 200, "height": {"cm": 200, "inch": 15, "mile": 20}}}
actual = {"name": "Cake", "image": {"width": 250, "height": {"cm": 290, "foot": 10, "yard": 90}}}
ddiff = DeepDiff(expected, actual)
print(ddiff.to_dict())默认输出中，root['image']['height'] 被整体视为 values_changed，而 foot/yard（新增）和 inch/mile（删除）未被单独捕获——这显然不符合精细调试或自动化报告的需求。
根本原因：threshold_to_diff_deeper 的默认行为
DeepDiff 自 v7.1.0 起引入了 threshold_to_diff_deeper 参数（默认值 0.33），其逻辑是：
若两个字典的键交集比例 低于该阈值（即公共键数 ÷ 总唯一键数 values_changed）。
在上述例子中，{"cm", "inch", "mile"} 与 {"cm", "foot", "yard"} 的交集仅 {"cm"}（占比 1/5 = 0.2 height 子字典被“短路”处理。
解决方案：显式禁用阈值优化
将 threshold_to_diff_deeper=0 即可完全关闭该启发式策略，强制 DeepDiff 逐层深入比较每个键路径：
ddiff = DeepDiff(
expected,
actual,
threshold_to_diff_deeper=0 # 关键配置：禁用自动聚合
)
print(ddiff.to_dict())
# 输出：
# {
# 'dictionary_item_added': ["root['image']['height']['foot']", "root['image']['height']['yard']"],
# 'dictionary_item_removed': ["root['image']['height']['inch']", "root['image']['height']['mile']"],
# 'values_changed': {
# "root['image']['width']": {'new_value': 250, 'old_value': 200},
# "root['image']['height']['cm']": {'new_value': 290, 'old_value': 200}
# }
# }✅ 此时所有变更均按语义精确分类：
- 新增键 →
dictionary_item_added - 删除键 →
dictionary_item_removed - 值变更 →
values_changed（含完整路径与新旧值）
注意事项与最佳实践
-
性能权衡：设为
0会增加计算开销（尤其对超大嵌套结构），但在多数测试/配置校验场景中影响可忽略；若需兼顾性能与精度，可尝试threshold_to_diff_deeper=0.1等中间值。 -
版本兼容性：该参数在 DeepDiff ≥7.1.0 中有效；旧版本（≤7.0.1）默认行为即等效于
threshold_to_diff_deeper=0。 -
配合其他参数使用：建议同时启用
ignore_order=True（应对列表顺序无关场景）或report_repetition=True（检测重复元素），构建更鲁棒的比对逻辑。 - 生产环境建议：将此配置封装为可复用的比对函数，并添加日志记录变更类型统计，便于问题定位与审计。
通过这一配置，DeepDiff 即可真正发挥其“深度差异分析”的设计初衷，让嵌套结构的变更一目了然。
