Python参数类型检查：typing与装饰器应用

本文深入剖析了Python中函数参数类型检查的实战方案，指出仅靠`get_type_hints`无法真正实现运行时类型校验，必须结合`get_origin`、`get_args`递归解析泛型与联合类型（如`Optional`、`list[str]`、`int | str`），再通过定制化的`isinstance`逻辑逐层验证实际参数值；文章手把手实现了一个轻量、纯标准库的`@typechecked`装饰器，清晰揭示其原理、边界与局限（如不支持嵌套泛型），并强调它与静态类型检查工具mypy的互补关系——前者捕获动态运行时错误，后者保障代码整体类型一致性，二者协同才是健壮Python类型实践的正确打开方式。

Python 运行时不强制检查函数参数类型，但开发中常需要提前发现类型错误——typing 本身不执行检查，必须配合运行时校验机制（如装饰器）才能真正生效。

为什么 type_check 装饰器不能只靠 get_type_hints 就完事

get_type_hints 只能提取注解，无法处理：可选参数（Optional[T]）、联合类型（Union[int, str] 或 int | str）、泛型（List[str]）、以及 Any / Never 等特殊类型。更关键的是，它不检查实际传入值是否满足类型约束。

• 必须用 isinstance 做基础判断，但 isinstance(val, list) 无法区分 List[str] 和普通 list
• typing.get_origin 和 typing.get_args 才能拆解泛型结构，比如从 List[str] 中拿到 list 和 (str,)
• Union 类型需逐个尝试 isinstance，且要小心 None 在 Optional[T] 中的特殊处理

如何写一个轻量但可用的 @typechecked 装饰器

核心是拦截调用、读取参数注解、对每个实参做类型验证。不依赖第三方库，仅用标准库 typing 和 inspect。

from typing import get_type_hints, get_origin, get_args, Union, Optional
import inspect
def typechecked(func):
sig = inspect.signature(func)
type_hints = get_type_hints(func)
def wrapper(*args, **kwargs):
    # 绑定参数，获得实际传入值与形参名的映射
    bound = sig.bind(*args, **kwargs)
    bound.apply_defaults()

    for name, value in bound.arguments.items():
        if name not in type_hints:
            continue
        expected_type = type_hints[name]

        if not _is_instance(value, expected_type):
            raise TypeError(
                f"Argument '{name}' of {func.__name__} expects {expected_type}, got {type(value).__name__}"
            )
    return func(*args, **kwargs)
return wrapper
def _is_instance(val, typ):
origin = get_origin(typ)
args = get_args(typ)
if origin is Union:
    return any(_is_instance(val, arg) for arg in args)
if origin is Optional:
    return val is None or _is_instance(val, args[0])
if origin in (list, dict, tuple, set):
    if not isinstance(val, origin):
        return False
    if not args:
        return True
    # 简单泛型校验：只检查第一层元素类型（如 list[str]）
    elem_type = args[0]
    if origin is list:
        return all(_is_instance(x, elem_type) for x in val)
    # 其他容器类型可依此类推，此处略
return isinstance(val, typ)

• 该装饰器不支持嵌套泛型（如 list[list[int]]），也不校验 Callable 或 Literal，够日常调试用，但别当生产级校验器
• get_origin(typ) 对普通类（如 str、int）返回 None，此时直接走 isinstance(val, typ)
• 注意 Python 3.10+ 的 int | str 语法会被 get_origin 识别为 types.UnionType，需额外分支处理

typechecked 和 mypy 是什么关系？能互相替代吗

不能替代。二者定位完全不同：mypy 是静态分析工具，在代码运行前扫描类型注解并报错；而 @typechecked 是运行时校验，在每次函数调用时检查。

• mypy 查不出动态构造的值（如 json.loads(input_str) 返回的 dict 是否真含 "id": int 字段）
• @typechecked 查不出未被调用的函数路径，也增加运行时开销（尤其高频小函数）
• 最佳实践是：用 mypy 做 CI 检查 + 关键入口函数（如 API handler、CLI 主函数）加 @typechecked

真正容易被忽略的是：类型校验一旦开启，就要求整个调用链上的中间函数也补全注解，否则 get_type_hints 返回空字典，校验直接跳过——这不是 bug，是设计使然。

到这里，我们也就讲完了《Python参数类型检查：typing与装饰器应用》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！