from typing import Any, Dict, Iterable, List


def 取值_多个键(
    数据: Dict[str, Any],
    候选键列表: Iterable[Any],
    默认值: Any = None
) -> Any:
    """
    按候选键顺序返回第一个存在的值。

    本函数用于处理“同一语义字段可能存在多个备选键名”的场景，
    例如接口兼容、旧版字段迁移、不同来源数据字段名不统一等情况。

    设计特性：
        - 若传入对象不是字典类型，直接返回默认值；
        - 候选键会按传入顺序依次查找，命中即返回，不继续向后判断；
        - 键会被统一转换为字符串，以保证与本模块其他函数行为一致；
        - 判断依据是“键是否存在”，不会因值为 None、0、False、"" 而误判；
        - 不抛出任何异常，适合作为底层兼容型工具函数使用。

    行为说明：
        - 数据为 dict 且命中首个存在键   → 返回对应值；
        - 数据为 dict 但所有候选键都不存在 → 返回默认值；
        - 数据不是 dict                  → 返回默认值。

    Args:
        数据 (dict): 用于取值的字典对象。
        候选键列表 (Iterable[Any]): 候选键序列，按顺序逐个尝试。
            - 列表示例： ["name", "名称", "用户名"]
            - 元组示例： ("phone", "手机号", "mobile")
        默认值: 当所有候选键都不存在时返回的值，默认为 None。

    Returns:
        Any:
            - 成功：返回第一个命中键对应的值；
            - 失败：返回默认值。
    """
    try:
        if not isinstance(数据, dict):
            return 默认值

        if isinstance(候选键列表, str):
            待查键列表: List[Any] = [候选键列表]
        elif isinstance(候选键列表, (list, tuple)):
            待查键列表 = list(候选键列表)
        else:
            待查键列表 = list(候选键列表)

        if len(待查键列表) == 0:
            return 默认值

        for 键 in 待查键列表:
            键名 = str(键)
            if 键名 in 数据:
                return 数据[键名]

        return 默认值
    except Exception:
        return 默认值