from typing import Any, Dict, Iterable, List

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

    功能说明:
        - 这个函数用于按候选键顺序返回第一个存在的值。
        - 它把字典里的常见操作单独封装好了，调用时不用自己反复写判断逻辑。
        - 当输入不符合要求时，函数会返回约定好的兜底结果，避免程序因为异常中断。

    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 默认值


if __name__ == "__main__":
    print("===== 示例1：基础用法 =====")
    数据 = {"名称": "zfx", "年龄": 18, "城市": "上海"}
    候选键列表 = ["name", "名称", "用户名"]
    默认值 = "默认值"
    print("结果:", 取值_多个键(数据, 候选键列表, 默认值))
    print("数据:", 数据)

    print("\n===== 示例2：常见变体 =====")
    数据 = {"name": "zfx", "phone": None, "items": [1, 2]}
    候选键列表 = ("phone", "手机号")
    默认值 = "未找到"
    print("结果:", 取值_多个键(数据, 候选键列表, 默认值))
    print("数据:", 数据)

    print("\n===== 示例3：边界情况 =====")
    数据 = {}
    候选键列表 = []
    默认值 = "空"
    print("结果:", 取值_多个键(数据, 候选键列表, 默认值))
    print("数据:", 数据)

    print("\n===== 示例4：异常情况 =====")
    数据 = []
    候选键列表 = "名称"
    默认值 = "失败"
    print("结果:", 取值_多个键(数据, 候选键列表, 默认值))
    print("数据:", 数据)

    print("\n===== 示例5：特殊值情况 =====")
    数据 = {"名称": "", "备注": None, "标签": []}
    候选键列表 = ["备注", "说明"]
    默认值 = 0
    print("结果:", 取值_多个键(数据, 候选键列表, 默认值))
    print("数据:", 数据)

    print("\n===== 示例6：应用场景-整理业务字典 =====")
    数据 = {"订单号": "A001", "状态": "待发货", "数量": 3}
    候选键列表 = ["order_status", "状态"]
    默认值 = "未知状态"
    print("结果:", 取值_多个键(数据, 候选键列表, 默认值))
    print("数据:", 数据)
