大模型 SDK 的函数签名里,经常能见到这样一行注解:content: str | list[str | dict[Any, Any]] | None = None。一行之内同时出现联合类型、嵌套泛型、可空标记和默认值,乍看密不透风;它想表达的意思其实很朴素——这个参数可以接收多种类型中的任意一种。
竖线写法是 Python 3.10 才有的新语法,往前是 typing.Union 的天下。本文按"拆解这行注解 → 三种写法与版本 → 注解不等于运行时检查 → 多模态消息场景 → 对照 Java 与 Kotlin → 使用要点"展开。
1、拆解这行注解
读这种注解的节奏是"从外往里,遇到竖线念或"。最外层是一个三成员联合:字符串、列表、None;列表内部还嵌着一个小联合,元素可以是字符串或字典。各片段的含义对比如下:
| 片段 | 含义 |
|---|---|
str |
纯文本,联合的第一个成员 |
list 及其内部联合 |
列表,元素可为字符串或字典 |
None |
允许空值 |
末尾的 = None |
默认值,不传参时生效 |
| 中间的竖线 | 联合类型的分隔符,"或"的关系 |
按这个口径检验赋值,示例如下:
content = "你好" # str,在联合内
content = ["你好", {"a": 1}] # 列表混排字符串与字典,合法
content = [{"name": "张三", "age": 18}] # 全字典列表,合法
content = None # None,合法
content = 123 # int 不在联合内,类型检查器报错
解读:前四行都落在联合的覆盖范围内,最后一行则出了界——但这个"不合法"要打引号:纯 Python 在运行时不会拦截这行赋值,它照常执行,报错发生在静态检查器那里。这个边界第 3 节专门展开。
2、联合类型的三种写法
今天的写法是三个版本时代叠出来的,各写法的版本门槛对比如下:
| 写法 | 最低版本 | 现状 |
|---|---|---|
Union[str, int] |
3.5 | 仍合法,新代码渐少 |
内置泛型 list[str] |
3.9 | 推荐写法 |
| 竖线联合 | 3.10 | 首选 |
新旧两代写法对照,示例如下:
from typing import Optional, Union, List, Dict, Any
# 3.9 及以前:typing 泛型加 Union,层层嵌套
content: Optional[Union[str, List[Union[str, Dict[Any, Any]]]]] = None
# 3.10 起:竖线联合加内置泛型,可读性大增
content: str | list[str | dict[Any, Any]] | None = None
解读:两种写法语义完全等价。竖线来自 PEP 604,内置泛型来自 PEP 585,Union 与 Optional 的定义见 typing 文档。这里有个经典误解要点破:Optional[X] 只是 X | None 的别名,它不表示"参数可省"——参数能不能不传由 = 默认值 决定,与 Optional 无关。Kotlin 开发者可以借力理解:String? 对应 str | None,"可省参数"对应 = None,这两个概念在 Kotlin 里本来就分属两处。
3、注解不等于运行时检查
注解只是声明"预期",先看它在裸 Python 里的真实行为:
content: str | None = None
content = 123 # 运行时照常执行,注解不做任何拦截
print(content) # 123
解读:静态检查器报的错,解释器不报。content = 123 在 mypy、pyright 眼里是类型违规,在解释器眼里只是普通赋值——要让类型在运行时被强制,得靠主动读注解的框架:Pydantic 构造模型时按注解逐项校验、拒绝越界类型,这正是它能当数据校验器用的根基。
联合类型还有个运行时能用的伙伴特性,示例如下:
print(isinstance("hi", str | list)) # True
print(isinstance(3.14, str | list)) # False
解读:PEP 604 让联合不局限于注解位置,还能直接作为 isinstance 的第二个参数,替代 isinstance(x, (str, list)) 的元组写法。注解管静态、isinstance 管动态,两副面孔都认同一套联合表达式。
4、多模态消息的通用形态
为什么联合类型在大模型 SDK 里扎堆?因为消息的 content 天然就是"或"的关系。OpenAI 风格的消息结构,示例如下:
# 纯文本消息
{"role": "user", "content": "你好"}
# 多模态消息:文本与图片的分段列表
{"role": "user", "content": [
{"type": "text", "text": "这张图里是什么?"},
{"type": "image_url", "image_url": {"url": "..."}},
]}
解读:content 要么是整段字符串,要么是分段列表、每段自带 type 标记——两种形态共用一个字段,联合声明正是对这种结构的刻画,正式格式见 OpenAI 视觉指南。生产代码里更进一步的做法,是用 TypedDict 或 Pydantic 模型给那些 dict 段落定义真实字段,让检查器看得见 type、text、image_url 这些键——宽松联合管入口,严格模型管内部。
5、对照 Java 与 Kotlin
Java 没有联合类型,历史上靠方法重载或 Object 配 instanceof 硬凑,Java 17 的密封接口加模式匹配 switch 才补上大半。Kotlin 的惯用答案是 sealed 接口,示例如下:
sealed interface Part
data class Text(val text: String) : Part
data class Image(val url: String) : Part
fun render(content: List<Part>): String =
when (val first = content.first()) { // when 对 sealed 做穷尽检查
is Text -> first.text
is Image -> "图片:${first.url}"
}
解读:sealed 把"可能的类型"收拢成有限集合,when 覆盖全部分支时不需要 else,漏掉一个分支编译器直接报错——这就是穷尽检查,机制见 Kotlin sealed 文档。三门语言的路线对照如下:
| 维度 | Java | Kotlin | Python |
|---|---|---|---|
| 联合类型 | 无,靠重载或密封接口 | sealed 接口,名义化 | 竖线联合,结构化 |
| 可空表示 | 注解约定 | 内建可空后缀 | 显式写进联合 |
| 穷尽检查 | switch 模式匹配 | when 配合 sealed | 无 |
从表里可以看出取舍:Python 的竖线联合胜在轻——随手组合现成类型,不必先造一套类层级;代价是没有穷尽检查,match 语句漏了分支没有任何工具提醒。轻联合配重校验(Pydantic),是 Python 生态里常见的互补搭配。
6、使用要点与版本门槛
第一,版本门槛是硬约束:竖线联合要求 3.10,内置泛型要求 3.9。from __future__ import annotations 虽能让旧解释器容忍注解里的竖线写法(注解被当作字符串不再求值),可一旦有代码在运行时求值——Pydantic、get_type_hints——就会现出原形,多版本兼容的项目老老实实用 Union。
第二,None 必须显式写进联合。Python 没有 Kotlin 那种"默认不可空、加问号才可空"的类型系统,忘了写 | None,静态检查器就会拒绝 None 赋值——这不是检查器苛刻,是语言把可空性完全交给了注解。
第三,警惕过度嵌套。三层以上的联合套泛型,读起来已经需要动笔拆解,本篇主角那行注解就接近上限;能收敛时就收敛,把 dict[Any, Any] 升级成 TypedDict、把长联合提炼成类型别名,都是立竿见影的减负手段。
7、总结
回顾要点:竖线联合读作"或",str | list | None 表示三种形态任选其一,注解从外往里拆、遇到竖线念或即可;三种写法对应三个版本时代,Optional[X] 等价于 X | None,而"参数可省"由默认值决定;注解不做运行时拦截,静态检查器与 Pydantic 各司其职,联合本身还能直接进 isinstance;多模态消息是联合类型最典型的用武之地;对照 Kotlin 的 sealed 体系,Python 走的是轻量结构化路线,代价是没有穷尽检查。对于正在读写 LLM SDK 签名的开发者,建议养成两个习惯:读不长的注解时按"从外往里"的节奏拆,写不下的注解时用 TypedDict 或类型别名把结构收紧——联合类型宜短不宜深。

