from typing import Any, Dict

def 添加键值对(
    数据: Dict[str, Any],
    键: Any,
    值: Any
) -> bool:
    """向给定字典中添加或更新一个键值对。

    功能说明:
        - 这个函数用于向给定字典中添加或更新一个键值对。
        - 它主要返回 True 或 False，适合直接写在 if 判断里控制后续流程。
        - 当输入不符合要求时，函数会直接返回 False，方便你快速判断这次操作有没有成功。

    Args:
        数据 (dict): 目标字典对象，必须为可变字典。
        键: 要添加或更新的键，内部将统一转换为字符串。
        值: 要写入字典的值，类型不限。

    Returns:
        bool:
        - True  ：键值对成功写入字典；
        - False ：传入对象不是字典或发生异常。"""
    try:
        if not isinstance(数据, dict):
            return False

        数据[str(键)] = 值
        return True
    except Exception:
        return False


if __name__ == "__main__":
    print("===== 示例1：基础用法 =====")
    数据 = {"名称": "zfx", "年龄": 18, "城市": "上海"}
    键 = "名称"
    值 = "新值"
    print("结果:", 添加键值对(数据, 键, 值))
    print("数据:", 数据)

    print("\n===== 示例2：常见变体 =====")
    数据 = {"name": "zfx", "phone": None, "items": [1, 2]}
    键 = "name"
    值 = None
    print("结果:", 添加键值对(数据, 键, 值))
    print("数据:", 数据)

    print("\n===== 示例3：边界情况 =====")
    数据 = {}
    键 = "不存在"
    值 = "空"
    print("结果:", 添加键值对(数据, 键, 值))
    print("数据:", 数据)

    print("\n===== 示例4：异常情况 =====")
    数据 = []
    键 = "名称"
    值 = 1
    print("结果:", 添加键值对(数据, 键, 值))
    print("数据:", 数据)

    print("\n===== 示例5：特殊值情况 =====")
    数据 = {"名称": "", "备注": None, "标签": []}
    键 = "备注"
    值 = ""
    print("结果:", 添加键值对(数据, 键, 值))
    print("数据:", 数据)

    print("\n===== 示例6：应用场景-整理业务字典 =====")
    数据 = {"订单号": "A001", "状态": "待发货", "数量": 3}
    键 = "状态"
    值 = "已发货"
    print("结果:", 添加键值对(数据, 键, 值))
    print("数据:", 数据)
