1. 为什么我们需要Union和Optional类型注解

刚开始用Python做项目的时候，我经常遇到这样的场景：从数据库查出来的用户年龄字段，有时候是字符串"18"，有时候是数字18，有时候干脆是None。每次处理这种数据都要写一堆if-else判断，代码看起来就像打满了补丁的旧衣服。直到发现了typing模块里的Union和Optional，才明白原来类型注解可以这么优雅地处理"薛定谔的数据类型"。

Union联合类型就像是给变量上了多重保险。比如一个变量可能是int也可能是str，用Union[int, str]就能明确表达这种灵活性。而Optional本质上是Union[T, None]的语法糖，专门用来处理那些"可能有值也可能为None"的情况。这两个工具配合使用，能完美解决日常开发中90%的类型不确定问题。

记得有一次我写API接口，前端传过来的参数可能是字符串、数字或者干脆不传。用Union和Optional定义参数类型后，不仅PyCharm能智能提示，mypy静态检查还能提前发现类型错误，调试时间直接减少了一半。这种在编码阶段就能发现潜在问题的感觉，就像有个经验丰富的老司机在旁边帮你指路。

2. Union联合类型的基本用法

2.1 从生活场景理解Union

想象你在处理一份国际化的用户资料，年龄字段可能有三种形式：

• 数字形式的年龄（如18）
• 字符串形式的年龄（如"18"）
• 未填写的年龄（None）

这就像点奶茶时选择甜度：全糖、半糖或无糖。Union和Optional就是帮我们规范这种"多选一"场景的类型工具。下面这段代码展示了如何用Union处理这种情况：

from typing import Union

def process_age(age: Union[int, str, None]) -> int:
    if age is None:
        return 0
    return int(age) if isinstance(age, str) else age

2.2 容器类型中的Union应用

实际项目中更常见的是容器里装着混合类型的数据。比如从CSV文件读取的数据，同一列可能包含数字和字符串：

from typing import List, Union

def calculate_total(prices: List[Union[float, str]]) -> float:
    return sum(float(p) for p in prices)

# 能正确处理以下各种情况
print(calculate_total([10.5, "20.3", 30]))  # 输出60.8
print(calculate_total(["15.99", "24.01"]))  # 输出40.0

对于字典这种复杂结构，Union能发挥更大作用。比如处理API返回的JSON数据：

from typing import Dict, Union

ApiResponse = Dict[str, Union[int, str, List[Dict[str, Union[float, str]]]]]

def parse_response(response: ApiResponse) -> None:
    # 类型安全的处理逻辑
    if isinstance(response.get("code"), int):
        print(f"状态码: {response['code']}")

3. Optional的妙用与注意事项

3.1 Optional的本质揭秘

第一次看到Optional[int]时，我以为是什么高级魔法，后来发现它其实就是Union[int, None]的快捷写法。这个语法糖让代码更简洁，特别是处理那些允许为None的参数时：

from typing import Optional

def get_user_name(user_id: int) -> Optional[str]:
    # 模拟数据库查询可能返回None
    return "Alice" if user_id == 1 else None

name = get_user_name(2)
if name is not None:
    print(name.upper())  # PyCharm会智能提示str方法

3.2 避免Optional的常见陷阱

但Optional也不是银弹，我踩过的一个坑是过度使用Optional导致代码充满None检查。比如下面这个反模式：

def bad_design(data: Optional[Dict[str, Optional[Union[int, str]]]]) -> Optional[int]:
    # 多层嵌套Optional会让代码难以维护
    if data is None:
        return None
    value = data.get("key")
    if value is None:
        return None
    return int(value) if isinstance(value, str) else value

更优雅的做法是使用数据类配合Optional：

from dataclasses import dataclass
from typing import Optional

@dataclass
class UserProfile:
    name: str
    age: Optional[int] = None

def create_profile(name: str, age: Optional[int] = None) -> UserProfile:
    return UserProfile(name=name, age=age)

4. 实战：构建类型安全的API处理器

4.1 设计请求参数类型

假设我们要处理一个用户注册接口，请求参数可能有以下特点：

• username必须是字符串
• age可以是数字或字符串
• email是可选的
• preferences是可选字典

对应的类型定义可以这样设计：

from typing import Union, Optional, Dict, Any

RegisterRequest = Dict[
    str,
    Union[
        str,
        int,
        Optional[Dict[str, Any]],
    ]
]

def validate_request(data: RegisterRequest) -> bool:
    if not isinstance(data.get("username"), str):
        return False
    if "age" in data and not isinstance(data["age"], (int, str)):
        return False
    return True

4.2 处理响应数据

对于API响应，我们通常需要更精确的类型控制。下面是一个电商订单响应的例子：

from typing import TypedDict, Union, List, Optional

class OrderItem(TypedDict):
    product_id: str
    quantity: int
    price: Union[float, str]

class ApiResponse(TypedDict):
    success: bool
    code: int
    data: Optional[Union[List[OrderItem], Dict[str, str]]]
    message: Optional[str]

def handle_response(response: ApiResponse) -> None:
    if response["success"] and response["data"]:
        if isinstance(response["data"], list):
            print(f"订单包含{len(response['data'])}件商品")
        else:
            print("单商品订单详情")

5. 类型检查工具链的最佳实践

5.1 配置mypy进行静态检查

光有类型注解还不够，需要mypy来强制执行。在pyproject.toml中添加：

[tool.mypy]
python_version = "3.8"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
check_untyped_defs = true
no_implicit_optional = true

这样运行mypy时，它会严格检查所有Union和Optional的使用是否合理。比如下面这段代码就会报错：

def unsafe_function(data: Optional[str]) -> str:
    return data.upper()  # mypy会报错：Item "None" of "Optional[str]" has no attribute "upper"

正确的写法应该是：

def safe_function(data: Optional[str]) -> Optional[str]:
    return data.upper() if data is not None else None

5.2 在PyCharm中最大化利用类型提示

现代IDE能基于类型注解提供强大的智能提示。比如当你使用Union类型时：

1. 自动补全会过滤掉不匹配的方法
2. 类型错误会有波浪线提示
3. 快速文档会显示完整的类型签名

试试这个例子：

def process_value(value: Union[int, str]) -> int:
    # 在这里输入value.，PyCharm会同时提示str和int的方法
    return value if isinstance(value, int) else len(value)

6. 高级技巧：类型别名与泛型结合

当Union类型变得复杂时，可以用类型别名提高可读性：

from typing import Union, Dict, List, TypeVar

T = TypeVar('T')
JsonValue = Union[None, int, str, bool, List['JsonValue'], Dict[str, 'JsonValue']]

def deep_parse(data: JsonValue) -> T:
    # 处理任意嵌套的JSON结构
    ...

对于经常重用的复杂类型，可以创建专门的类型别名：

from typing import Union, Optional, Dict, List

# 电商领域特定类型
Sku = str
Price = Union[float, str]
Inventory = Dict[Sku, Union[int, str]]
ProductListing = List[Dict[str, Union[Sku, Price, Optional[Dict[str, str]]]]]

7. 性能考量与运行时类型检查

虽然类型注解主要在静态检查时有用，但有时我们也需要在运行时验证类型。这时候可以使用pydantic这样的库：

from pydantic import BaseModel
from typing import Union

class Item(BaseModel):
    name: str
    price: Union[float, str]
    
    @validator('price')
    def normalize_price(cls, v):
        return float(v)

这样既能享受类型提示的好处，又能自动处理类型转换：

item = Item(name="Coffee", price="3.99")  # 自动将字符串转为浮点数
print(item.price)  # 输出3.99，类型是float

在性能敏感的场景，要注意Union类型在isinstance检查时的开销。对于高频调用的函数，可以考虑使用单分派(single dispatch)：

from functools import singledispatch

@singledispatch
def process(data):
    raise NotImplementedError

@process.register
def _(data: str):
    return data.upper()

@process.register
def _(data: int):
    return data * 2