from typing import Any, Dict


_未提供 = object()


def 取值_必填(
    数据: Dict[str, Any],
    键: Any,
    默认值: Any = None,
    失败标记: Any = _未提供
) -> Any:
    """
    获取指定键的值；若键不存在，则返回默认值或指定失败标记。

    本函数适用于“字段按业务要求必须存在，但仍希望以安全方式读取”的场景。
    与普通 `取值` 的区别在于：当读取失败时，可以显式返回一个专门的失败标记，
    方便上层逻辑区分“真实值为空”与“字段缺失”两种情况。

    设计特性：
        - 若传入对象不是字典类型，视为取值失败；
        - 键会被统一转换为字符串，以保持与本模块其他函数行为一致；
        - 若提供了失败标记，则取值失败时优先返回失败标记；
        - 若未提供失败标记，则取值失败时返回默认值；
        - 不抛出任何异常，适合作为业务字段读取工具函数使用。

    行为说明：
        - 数据为 dict 且键存在      → 返回对应值；
        - 数据为 dict 但键不存在    → 返回失败标记或默认值；
        - 数据不是 dict             → 返回失败标记或默认值。

    Args:
        数据 (dict): 用于取值的字典对象。
        键: 要读取的键，内部将转换为字符串。
        默认值: 当取值失败且未提供失败标记时返回的值，默认为 None。
        失败标记: 当取值失败时优先返回的专用标记。
            - 示例： "字段缺失"
            - 示例： False

    Returns:
        Any:
            - 成功：返回字典中对应键的值；
            - 失败：返回失败标记或默认值。
    """
    try:
        if not isinstance(数据, dict):
            return 默认值 if 失败标记 is _未提供 else 失败标记

        键名 = str(键)
        if 键名 in 数据:
            return 数据[键名]

        return 默认值 if 失败标记 is _未提供 else 失败标记
    except Exception:
        return 默认值 if 失败标记 is _未提供 else 失败标记