Python ≥3.10 时，函数签名、变量注解、类属性中可用 int | str 替代 Union[int, str]，提升简洁性与IDE补全；但 isinstance 和旧工具需 typing.Union，嵌套复杂时建议仍用 Union。
直接用 int | str 替代 Union[int, str]，不是为了“时髦”，而是能立刻减少导入、提升 IDE 补全准确率、降低嵌套括号混乱风险——但前提是 Python 版本 ≥ 3.10 且类型检查器配置正确。
哪些地方能直接换，哪些必须保留 Union
绝大多数函数签名、变量注解、类属性声明中，| 可无痛替换 Union：
-
def parse(x: bytes | str) -> dict | None:✅ 安全、简洁、IDE 可识别 -
data: list[int] | dict[str, float]✅ 3.9+ 原生容器语法 +|组合更自然 -
Optional[str]可直接写成str | None✅（3.10+ 推荐） -
isinstance(x, int | str)❌ 运行时报错：TypeError: isinstance() arg 2 must be a type or tuple of types -
type_union = int | str后传给需要typing.Union实例的工具（如旧版 mypy 插件或自定义反射逻辑）❌ 返回的是types.UnionType，非typing.Union
PyCharm / VS Code 补全和类型推导差异
| 不是纯语法糖，它改变了底层类型对象，直接影响编辑器行为：
huaweicloud-python-sdk-helper
下载
华为云 Python SDK 查询工具。自动发现已安装 SDK 的服务包、Client类、API 方法、入参详情、类信息（__init__ 参数、属性、类型、描述），支持关键字搜索，快速定位目标 API 使用方法。
- PyCharm 在未识别项目为 Python 3.10+ 时，输完
int |可能不提示str，需确认解释器版本和from __future__ import annotations是否启用 - mypy 默认只在
--python-version 3.10或更高时解析|；否则报SyntaxError: invalid syntax -
get_type_hints()返回值中，int | str会被标准化为Union[int, str]（取决于是否启用了from __future__ import annotations），但中间过程可能影响自定义类型检查逻辑
嵌套联合类型：可读性比简洁更重要
简单联合用 | 没问题，但嵌套越深，越容易误读：
立即学习“Python免费学习笔记（深入）”；
- ✅ 清晰：
list[str] | dict[str, int] - ⚠️ 易混淆：
list[str | int] | dict[str, set[float | bool]]—— 此时括号语义模糊，建议拆开或改用Union显式分组 - ✅ 更稳：
Union[list[Union[str, int]], dict[str, set[Union[float, bool]]]]（尤其在团队协作或对接旧工具时）
真正容易被忽略的点在于：类型提示不是写给解释器看的，而是写给类型检查器、IDE 和下一个读代码的人。用 | 省下的几个字符，如果换来补全失效或同事调试半天才发现 int | str 在运行时根本不能当类型对象用，就得不偿失了。
