from typing import Any, Dict, Iterable

def 合并_仅白名单键(
    目标字典: Dict[str, Any],
    来源字典: Dict[str, Any],
    白名单键列表: Iterable[Any]
) -> bool:
    """仅允许来源字典中的白名单键被合并到目标字典中。

    功能说明:
        - 这个函数用于仅允许来源字典中的白名单键被合并到目标字典中。
        - 它适合把两份字典数据整理到一起，常用于默认配置、补充字段或对比更新。
        - 当输入不符合要求时，函数会直接返回 False，方便你快速判断这次操作有没有成功。

    Args:
        目标字典 (dict): 接收合并结果的目标字典。
        来源字典 (dict): 提供候选写入内容的来源字典。
        白名单键列表 (Iterable[Any]): 允许被合并的键集合。
        - 列表示例： ["名称", "城市"]
        - 元组示例： ("age", "email")

    Returns:
        bool:
        True  - 合并操作已成功执行；
        False - 参数非法或发生异常。"""
    try:
        if not isinstance(目标字典, dict):
            return False

        if not isinstance(来源字典, dict):
            return False

        if isinstance(白名单键列表, str):
            白名单集合 = {白名单键列表}
        else:
            白名单集合 = {str(键) for 键 in 白名单键列表}

        for 键, 值 in 来源字典.items():
            if str(键) in 白名单集合:
                目标字典[键] = 值

        return True
    except Exception:
        return False


if __name__ == "__main__":
    print("===== 示例1：基础用法 =====")
    目标字典 = {"名称": "zfx"}
    来源字典 = {"城市": "上海"}
    白名单键列表 = ["名称", "城市"]
    print("结果:", 合并_仅白名单键(目标字典, 来源字典, 白名单键列表))
    print("目标字典:", 目标字典)
    print("来源字典:", 来源字典)

    print("\n===== 示例2：常见变体 =====")
    目标字典 = {"名称": "zfx", "城市": "上海"}
    来源字典 = {"名称": "new", "电话": "123"}
    白名单键列表 = ("电话", "邮箱")
    print("结果:", 合并_仅白名单键(目标字典, 来源字典, 白名单键列表))
    print("目标字典:", 目标字典)
    print("来源字典:", 来源字典)

    print("\n===== 示例3：边界情况 =====")
    目标字典 = {}
    来源字典 = {}
    白名单键列表 = []
    print("结果:", 合并_仅白名单键(目标字典, 来源字典, 白名单键列表))
    print("目标字典:", 目标字典)
    print("来源字典:", 来源字典)

    print("\n===== 示例4：异常情况 =====")
    目标字典 = []
    来源字典 = []
    白名单键列表 = "名称"
    print("结果:", 合并_仅白名单键(目标字典, 来源字典, 白名单键列表))
    print("目标字典:", 目标字典)
    print("来源字典:", 来源字典)

    print("\n===== 示例5：特殊值情况 =====")
    目标字典 = {"配置": {"端口": 3306}}
    来源字典 = {"配置": {"主机": "127.0.0.1"}}
    白名单键列表 = ["配置"]
    print("结果:", 合并_仅白名单键(目标字典, 来源字典, 白名单键列表))
    print("目标字典:", 目标字典)
    print("来源字典:", 来源字典)

    print("\n===== 示例6：应用场景-整理业务字典 =====")
    目标字典 = {"商品": "鼠标", "库存": 20}
    来源字典 = {"库存": 50, "状态": "在售"}
    白名单键列表 = ["库存", "状态"]
    print("结果:", 合并_仅白名单键(目标字典, 来源字典, 白名单键列表))
    print("目标字典:", 目标字典)
    print("来源字典:", 来源字典)
