如何递归重命名嵌套字典中的键名（基于映射字典）

本文介绍一种通用、健壮的递归方法，用于根据指定的键映射字典（key_dict）批量重命名嵌套字典中任意层级的键名，支持多级嵌套映射，避免浅层匹配错误与空字典返回问题。

本文介绍一种通用、健壮的递归方法，用于根据指定的键映射字典（key_dict）批量重命名嵌套字典中任意层级的键名，支持多级嵌套映射，避免浅层匹配错误与空字典返回问题。

在处理车载诊断（如UDS/DTC）、配置文件转换或API响应标准化等场景时，常需将原始嵌套字典的字段名按规范批量重命名。例如，将 code → udsDtcValue、failure_name → failname，且该映射仅作用于特定子路径（如 dtc_all 下的子字段），而非全局替换。此时，简单遍历或单层递归极易出错：原代码中误用 key.keys()（key 是字符串，无 .keys() 方法）、未处理嵌套映射传递、且构造新字典逻辑断裂，导致返回空字典。

以下是一个生产就绪的通用解决方案，采用原地修改 + 深度优先递归策略，支持多级嵌套 key_dict（即 key_dict 本身可含子映射），并确保映射作用域精准：

def replace_keys_in_place(data, key_mapping):
    """
    递归重命名嵌套字典中的键，依据 key_mapping 进行精准映射。

    Args:
        data (dict): 待处理的嵌套字典（将被原地修改）
        key_mapping (dict): 键映射字典，支持嵌套结构，例如：
            {'dtc_all': {'code': 'udsDtcValue', 'failure_name': 'failname'}}

    Returns:
        dict: 修改后的原字典（返回值仅为链式调用便利，实际为 in-place 修改）
    """
    def _recursive_replace(d, mapping):
        # 遍历当前字典的键（使用 list(keys()) 防止运行时修改引发 RuntimeError）
        for old_key in list(d.keys()):
            # 若当前键在 mapping 中存在直接映射（且映射值为字符串），则重命名
            if old_key in mapping and isinstance(mapping[old_key], str):
                new_key = mapping[old_key]
                if new_key != old_key:
                    d[new_key] = d.pop(old_key)
                # 对新键对应的值继续递归（若为 dict），并传入该键对应的子映射（若有）
                if isinstance(d[new_key], dict):
                    sub_mapping = mapping.get(old_key, {})
                    _recursive_replace(d[new_key], sub_mapping)
            # 若当前键在 mapping 中存在子映射（即 mapping[old_key] 是 dict），则进入该分支处理其子结构
            elif old_key in mapping and isinstance(mapping[old_key], dict):
                if isinstance(d[old_key], dict):
                    _recursive_replace(d[old_key], mapping[old_key])
            # 若当前键不在 mapping 中，但值是 dict，则继续递归（保持原有结构遍历）
            elif isinstance(d[old_key], dict):
                _recursive_replace(d[old_key], mapping)

    _recursive_replace(data, key_mapping)
    return data

# 使用示例
old_dict = {
    'candela_samples_generic': {
        'drc_dtcs': {
            'domain_name': 'TEMPLATE-DOMAIN',
            'dtc_all': {
                '0x930001': {
                    'identification': {
                        'code': '0x9300', 
                        'fault_type': '0x11', 
                        'description': 'GNSS antenna short to ground'
                    },
                    'snapshots': {
                        'snapshot_record_content': 'base', 
                        'snapshot_records_numbers': ['0x01']
                    },
                    'functional_conditions': {
                        'failure_name': 'short_to_ground', 
                        'mnemonic': 'DTC_GNSS_Antenna_Short_to_ground'
                    }
                }
            }
        }
    }
}

key_dict = {
    'dtc_all': {
        'code': 'udsDtcValue',
        'failure_name': 'failname',
        'mnemonic': 'LongName',
        'fault_type': 'FaultType',
        'snapshot_records_numbers': 'snapshotrecordsnumbers'
    }
}

# 执行重命名（原地修改）
replace_keys_in_place(old_dict, key_dict)

# 输出验证（已按预期更新）
print(old_dict['candela_samples_generic']['drc_dtcs']['dtc_all']['0x930001']['identification'])
# → {'udsDtcValue': '0x9300', 'FaultType': '0x11', 'description': 'GNSS antenna short to ground'}

✅ 关键设计亮点：

作用域精准：仅当字典键 k 出现在 key_mapping 的顶层或其父路径映射中时，才应用对应子映射，避免跨层级误替换；
嵌套映射支持：key_dict['dtc_all'] 是一个独立映射表，专用于 dtc_all 下所有子键，天然支持 {'user': {'name': 'fullName', 'id': 'userId'}, 'config': {...}} 等复杂结构；
安全遍历：使用 list(d.keys()) 避免 RuntimeError: dictionary changed size during iteration；
无副作用返回：函数返回 data 本身，便于链式调用（如 json.dumps(replace_keys_in_place(d, m))），但核心逻辑为 in-place，内存高效。

⚠️ 注意事项：

此函数直接修改原字典。如需保留原始数据，请先深拷贝：from copy import deepcopy; safe_dict = deepcopy(old_dict)；
映射字典中，值为非字符串类型（如 None, int, dict）时，仅当其为 dict 才触发子路径映射；其他类型将被忽略（不重命名）；
若存在同名键在多层映射中被重复定义（如 key_dict['a']['b'] 和 key_dict['b'] 同时存在），以最内层匹配路径为准（深度优先）。

通过该方案，你可轻松扩展支持任意深度的字段标准化，无需为每个新结构重写逻辑——真正实现“一次编写，处处适用”的字典键重命名范式。