TypeError常见诱因是参数类型不匹配但未在调用点暴露，应在函数入口用isinstance做输入守卫，优先校验对外参数；Union等类型需手动展开为元组，Optional需显式处理None，Literal等不可校验类型应改用值判断，高频或鸭子类型场景慎用isinstance。
TypeError常见诱因：参数类型不匹配但没报在调用点
Python运行时报TypeError，比如unsupported operand type(s) for +: 'int' and 'str'或object is not callable，往往不是函数定义写错了，而是传进去的值在函数内部参与运算时“突然”类型不对。静态类型注解（typing）本身不拦截运行时错误——它只帮IDE提示、供mypy检查，不改变执行逻辑。
真正能拦住问题的，是运行时校验。但别一上来就全量加isinstance：校验位置很关键，应在函数入口做输入守卫（guard clause），而不是等a + b炸了才回头查。
- 优先校验「对外暴露的参数」，而非内部中间变量
- 对可选参数（
Optional[T]）要单独处理None分支，isinstance(None, T)永远为False - 避免校验过于宽泛，比如用
isinstance(x, (int, float))代替只接受int的场景，可能掩盖业务语义错误
typing注解怎么配合isinstance做有效校验
typing里的很多类型（如Union、Literal、Generic）无法直接传给isinstance——后者只认运行时存在的具体类。所以得把注解“降级”成可校验的类型元组。
例如函数声明为def process_id(user_id: Union[int, str]) -> None:，不能写isinstance(user_id, Union[int, str])（会报TypeError: isinstance() arg 2 must be a type or tuple of types）。正确做法是手动展开：
立即学习“Python免费学习笔记（深入）”；
from typing import Union
<p>def process_id(user_id: Union[int, str]) -> None:
if not isinstance(user_id, (int, str)):
raise TypeError(f"expected int or str, got {type(user_id).<strong>name</strong>}")</p><h1>后续逻辑</h1><p>-
Optional[T]等价于Union[T, None]，校验时必须显式包含type(None)或写isinstance(x, T) or x is None -
Literal["a", "b"]无法用isinstance校验，改用if user_role not in ("a", "b"): -
Callable、Dict、List这类泛型，取其原始类型：isinstance(data, dict)而非isinstance(data, Dict[str, int])
什么时候不该用isinstance——性能与设计权衡
高频调用函数（如每秒上千次的API内层逻辑）加isinstance会引入可观开销，尤其是嵌套结构或大对象。更糟的是，过度校验会让函数失去灵活性——比如一个本可接受任何支持__len__的对象的函数，硬写成isinstance(obj, list)，就拒绝了tuple或自定义容器。
- 先问：这个参数的类型契约是否真由我控制？如果是下游传来的JSON解析结果，
dict/list校验合理；如果是同项目内另一个模块传来的对象，优先靠单元测试+mypy覆盖，而非运行时锁死 - 对“鸭子类型”明显的接口（如要求有
.read()方法），用hasattr或getattr(..., None) is not None比isinstance更贴合意图 - 校验失败时，抛
TypeError比ValueError更准确——前者表示“类型错”，后者表示“值错但类型对”
调试TypeError的最小排查路径
遇到TypeError别急着加校验，先定位爆炸点在哪一行、哪个变量。尤其注意隐式类型转换场景：
# 常见陷阱：f-string里混用类型
user_count = 42
msg = f"Found {user_count} users" # OK
msg = f"Found {user_count} and {None} users" # TypeError: unsupported format string passed to NoneType.__format__
- 用
print(type(x), repr(x))快速确认可疑变量的实际类型和值，比猜更可靠 - 检查是否误把函数当值用了：
result = some_func（漏了括号）→ 类型是function，后续result + 1就炸 - 留意第三方库返回值的文档说明，比如
pandas.Series.iloc[0]可能返回numpy.int64而非原生int，跟纯Python代码混用时容易触发TypeError
类型校验不是银弹，它解决的是“明确知道该是什么类型”的场景。如果连你都不确定参数该长什么样，与其加一堆isinstance，不如先厘清接口契约——那才是错误真正的源头。
