python 3.10+ 推荐用 str | none，兼容旧版本用 optional[str]；它仅表示值类型可为 str 或 none，与参数是否可选无关；避免 union[str, none] 和嵌套 optional；可选依赖用字符串注解或 type_checking 保护；typeddict 中可选字段需配合 total=false 及 notrequired（3.11+）或 optional（旧版）；函数标 | none 意味着必须有返回 none 的路径且调用方须处理。
typing.Optional 和 Union[None, T] 到底用哪个
Python 3.10+ 推荐直接用 None | T，但老项目或需要兼容 3.9 及以下时，Optional[T] 是更安全、更明确的选择。它本质就是 Union[T, None] 的语法糖，不是类型运行时的“可选值”，只是告诉类型检查器“这里可以是 T 或 None”。
常见错误是把 Optional[str] 当成“这个参数可传可不传”——其实不是：Optional 描述的是值的类型，和函数参数是否带默认值无关。参数要不要设 default=None，是调用逻辑的事；Optional 只管你传进来的东西是不是 str 或 None。
- 3.10+ 优先写
name: str | None：简洁、原生、无导入依赖 - 跨版本项目统一用
from typing import Optional+Optional[str]：避免 3.9- 环境报错 - 别写
Union[str, None]：冗长且易误写成Union[str, none]（大小写错）或漏逗号 -
Optional不能嵌套：比如Optional[Optional[str]]合法但无意义，等价于Optional[str]
给可选依赖加类型提示时怎么避免 ImportError
当某个类型只在可选依赖里（比如 pydantic、numpy），又不想让所有用户都装它，就不能在模块顶层直接 from pydantic import BaseModel 再写 data: BaseModel——否则没装 pydantic 就 import 失败。
正确做法是把类型引用“延迟化”：用字符串字面量或 TYPE_CHECKING 保护真实 import。
立即学习“Python免费学习笔记（深入）”；
- 简单场景（仅类型注解，不运行时使用）：直接写字符串
data: "BaseModel"，mypy/pyright 都认 - 需要运行时访问类型（比如
isinstance或泛型构造）：用if TYPE_CHECKING:包住 import - 别在函数签名里做条件 import：比如在 def 里 try-import 再注解，类型检查器看不到
- 如果用了
from __future__ import annotations（推荐），字符串写法更稳，连引号都能省（但建议保留，更清晰）
TypedDict 中的可选字段怎么标
TypedDict 本身不支持默认值，所谓“可选字段”是指构造字典时可以不提供该 key，但一旦提供，值必须符合声明类型。用 total=False 控制整体是否强制包含全部字段，再配合 NotRequired（3.11+）或 Optional（旧版）标单个字段。
- 3.11+ 推荐：
class Config(TypedDict, total=False): host: NotRequired[str] - 3.8–3.10：
class Config(TypedDict, total=False): host: Optional[str]——注意必须配total=False，否则Optional无效 - 别混用：
total=True下写host: Optional[str]没用，类型检查器仍要求必须传host -
NotRequired不等于 “可以为None”，而是“可以不出现”。如果字段存在但值是None，仍需类型允许None（比如用NotRequired[str | None]）
函数返回可选值时，类型和实际逻辑要对齐
写 def find_user(id: int) -> User | None: 很常见，但容易忽略两点：一是函数体里真得有路径返回 None，二是调用方得处理 None 分支。类型提示不是装饰，是契约。
- 如果函数逻辑上“一定有结果”，就别标
| None：比如数据库查不到就 raiseKeyError，那返回类型就该是User - 如果标了
| None，但所有分支都 return 实例，mypy 会警告“unreachable code”，说明类型和实现脱节 - 调用时别裸用
result.name：先if result is not None:或用assert result（后者只适合调试） - 性能上无影响：类型提示纯静态，运行时不占内存、不拖慢执行
最常被绕开的问题是：以为加了 Optional 就自动处理了空值逻辑。类型系统不会帮你加 if 判断，也不会阻止你调 .lower() 在 None 上——它只在你写错的时候提醒你。所以类型写得再漂亮，运行时崩不崩，还是看那几行 if 写没写对。