Python类型提示：Union和Optional的5个实际应用场景对比（附代码示例）

Python类型提示：Union与Optional的实战抉择——从API响应到数据库查询的五个关键场景

最近在重构一个中型项目的后端时，我再次被Python的类型提示给“教育”了一番。事情是这样的：团队里一位新同事在写一个用户信息处理的函数时，对于返回值的类型标注犹豫不决——这个函数可能返回一个完整的用户对象字典，也可能因为用户不存在而返回None，还可能在某些边缘情况下返回一个简化版的数据结构。他先是用了Optional[Dict]，但review时发现漏掉了简化版的情况；改成Union[Dict, None]后，又觉得和Optional好像没什么区别，反而更冗长。

这让我意识到，Union和Optional这两个看似简单的类型工具，在实际开发中的选择远不止“多类型”和“可空”这么表面。它们背后对应的是不同的设计意图和错误处理哲学。今天我就结合这几年踩过的坑和总结的经验，聊聊在五个具体场景下，如何在这两者之间做出更明智的选择。

1. API响应解析：当数据结构存在多种可能形态时

处理外部API的响应可能是日常开发中最常遇到类型不确定性的场景之一。一个设计良好的第三方API通常会返回结构化的JSON数据，但现实往往是：成功时返回一种结构，错误时返回另一种，部分成功时可能又是第三种。

1.1 典型的三态API响应模式

很多RESTful API会采用类似下面的响应结构：

from typing import TypedDict, Union, Optional
from datetime import datetime

class SuccessResponse(TypedDict):
    status: str  # "success"
    data: dict
    timestamp: datetime

class ErrorResponse(TypedDict):
    status: str  # "error"
    error_code: int
    message: str
    timestamp: datetime

class PartialResponse(TypedDict):
    status: str  # "partial"
    data: dict
    warnings: list[str]
    timestamp: datetime

APIResponse = Union[SuccessResponse, ErrorResponse, PartialResponse]

这里使用Union而不是多个Optional字段的原因在于：这三种响应在语义上是互斥的。一个响应不可能同时是成功和错误，也不可能既有完整数据又有警告信息但状态却是成功。

注意：当不同类型的响应共享部分字段时（如上面的timestamp），可以考虑使用Union配合isinstance检查，或者更优雅地使用Literal类型来区分。

1.2 实际解析中的类型守卫技巧

定义了联合类型后，如何在函数中安全地处理这些不同类型的响应呢？我推荐使用类型守卫（Type Guards）：

def parse_api_response(response: APIResponse) -> Optional[dict]:
    """解析API响应，提取核心数据或记录错误"""
    
    # 类型守卫函数
    def is_success(resp: APIResponse) -> TypeGuard[SuccessResponse]:
        return resp.get("status") == "success"
    
    def is_error(resp: APIResponse) -> TypeGuard[ErrorResponse]:
        return resp.get("status") == "error"
    
    if is_success(response):
        # 这里IDE能正确推断response是SuccessResponse类型
        process_data(response["data"])
        return response["data"]
    elif is_error(response):
        # 记录错误日志
        log_error(response["error_code"], response["message"])
        return None
    else:
        # 通过排除法，这里一定是PartialResponse
        handle_warnings(response["warnings"])
        return response["data"]

这种模式的优势在于：

• 类型安全：每个分支内都能获得正确的类型提示
• 可扩展性：新增响应类型时，只需添加新的类型守卫和分支
• 代码清晰：业务逻辑与类型检查分离

1.3 为什么不使用Optional字段？

有些开发者可能会想：为什么不把所有字段都设为Optional，然后用一个大的字典类型呢？比如：

class UnifiedResponse(TypedDict):
    status: str
    data: Optional[dict]
    error_code: Optional[int]
    message: Optional[str]
    warnings: Optional[list[str]]
    timestamp: datetime

问题在于这种设计违反了最小惊讶原则。当status为"success"时，error_code字段理论上应该是None，但类型系统无法保证这一点。其他开发者看到这个类型定义时，无法立即理解哪些字段组合是有效的。

2. 数据库查询结果处理：空值、未找到与多表联查

数据库操作是另一个Union和Optional频繁出现的领域。这里的情况比API响应更微妙，因为除了“有数据”和“没数据”之外，还有“数据格式可能不同”的情况。

2.1 简单的单记录查询：Optional的经典场景

对于根据主键查询单条记录的场景，Optional几乎总是正确的选择：

from typing import Optional
from dataclasses import dataclass

@dataclass
class User:
    id: int
    username: str
    email: str
    is_active: bool

def get_user_by_id(user_id: int) -> Optional[User]:
    """根据ID查询用户，未找到时返回None"""
    # 模拟数据库查询
    if user_id in user_cache:
        return user_cache[user_id]
    
    # 实际可能是: result = db.session.query(User).filter_by(id=user_id).first()
    result = mock_db_query(f"SELECT * FROM users WHERE id = {user_id}")
    
    if result:
        return User(**result)
    return None

这种模式如此普遍，以至于很多ORM都内置了对Optional的支持。比如SQLAlchemy的.first()方法返回的就是Optional[T]类型。

2.2 复杂查询：当单条记录可能有多种形态

但现实中的查询往往没那么简单。考虑一个电商系统的订单查询：

from typing import Union, Literal
from datetime import datetime
from dataclasses import dataclass

@dataclass
class BasicOrder:
    """基础订单信息，用于列表展示"""
    order_id: int
    total_amount: float
    status: str
    created_at: datetime

@dataclass 
class DetailedOrder(BasicOrder):
    """详细订单信息，包含商品明细"""
    items: list[OrderItem]
    shipping_address: Address
    payment_method: str
    discounts: list[Discount]

@dataclass
class DeletedOrder:
    """已删除的订单（软删除）"""
    order_id: int
    deleted_at: datetime
    deleted_reason: str

OrderResult = Union[BasicOrder, DetailedOrder, DeletedOrder]

def get_order(order_id: int, detail: bool = False) -> OrderResult:
    """
    获取订单信息
    
    Args:
        order_id: 订单ID
        detail: 是否获取详细信息
        
    Returns:
        可能是基础订单、详细订单或已删除订单
    """
    # 先检查是否已删除
    deleted_info = check_if_deleted(order_id)
    if deleted_info:
        return DeletedOrder(**deleted_info)
    
    # 根据detail参数决定返回详细还是基础信息
    if detail:
        return fetch_detailed_order(order_id)
    else:
        return fetch_basic_order(order_id)

这里使用Union而不是让DetailedOrder的所有字段都可空，是因为：

• 性能考虑：获取详细订单需要联查多张表，不应该在只需要基础信息时付出这个代价
• 语义清晰：调用者明确知道可能得到什么类型的结果
• 错误处理：已删除订单需要特殊处理流程

2.3 多表联查的结果处理

在多表联查时，情况会更加复杂。比如查询用户及其最近的订单：

from typing import Tuple, Optional

def get_user_with_recent_order(user_id: int) -&g