Python 类型注解实战：`Optional` 与安全数据处理的艺术

在 Python 开发中，类型注解（Type Hints）已经成为现代 Python 项目的标配。本文将通过一个真实的认证令牌获取函数 get_auth_token()，深入解析 Optional 类型的应用场景和最佳实践。

一、案例函数解析

from typing import Optional
import requestsdef get_auth_token(phone_number: str) -> Optional[str]:"""获取手机号对应的认证令牌Args:phone_number: 用户手机号码字符串Returns:成功时返回令牌字符串，失败时返回None"""auth_url = "https://api.example.com/auth"payload = {"phone": phone_number}try:response = requests.post(auth_url, json=payload, timeout=5)response.raise_for_status()return response.json().get('data', {}).get('token')except (requests.RequestException, ValueError):return None

二、`Optional` 类型详解

1. 基本概念

Optional[str] 是 Union[str, None] 的语法糖，表示：

可能返回字符串类型的 token
可能返回 None（认证失败时）

2. 使用场景对比

传统写法（无类型提示）

def get_auth_token(phone_number):# 可能返回str或None，但调用方无法直观知晓

现代写法（带类型提示）

def get_auth_token(phone_number: str) -> Optional[str]:# 明确告知调用方可能的返回类型

3. 为什么比异常更合适？

方案	适用场景	本案例选择理由
返回None	业务逻辑上的正常失败	手机号认证失败是正常业务场景
抛出异常	意外错误（如网络中断）	已在try块中处理网络异常

三、调用方的正确处理方式

1. 基础检查

token = get_auth_token("13800138000")
if token is None:print("认证失败，请检查手机号")return

2. 类型守卫（Python 3.10+）

from typing import TypeGuarddef is_valid_token(token: str | None) -> TypeGuard[str]:return token is not Nonetoken = get_auth_token("13800138000")
if not is_valid_token(token):print("无效令牌")return# 此处token会被类型检查器识别为str类型
make_authenticated_request(token)

3. 与Pydantic模型结合

from pydantic import BaseModel, validatorclass AuthResponse(BaseModel):token: Optional[str]@validator('token')def validate_token(cls, v):if v is None:raise ValueError("认证失败")return v

四、进阶应用模式

1. 带默认值的封装

def get_token_or_default(phone: str, default: str = "guest") -> str:return get_auth_token(phone) or default

2. 函数组合

from typing import CallableAuthFunc = Callable[[str], Optional[str]]def compose_auth(f1: AuthFunc, f2: AuthFunc) -> AuthFunc:def wrapper(phone: str) -> Optional[str]:return f1(phone) or f2(phone)return wrapper