如何为Python装饰器编写正确的类型注解？

你现有示例代码中的注解写法存在语法层面的误区：Callable[[*args,**kwargs], <返回类型>]不符合Python类型系统的规则，typing.Callable的第一个参数位仅接受固定的入参类型序列，或省略号...代表任意入参，不能直接写可变参数、关键字可变参数的语法占位。

核心注解逻辑 #

装饰器的本质是接收一个函数作为入参，返回一个与原函数签名完全兼容的新函数，对应两个存疑的注解位规则如下：

• func参数的类型：无需硬填固定的入参、返回值类型，通过泛型保存原函数的完整签名即可
• 装饰器自身的返回值类型：与func参数的类型保持一致，避免丢失原函数的类型信息

初学者可直接复用的基础写法 #

以下写法兼容Python 3.7及以上版本，逻辑简单易理解，不需要掌握复杂的高级类型语法：

from typing import Callable, TypeVar, Any

# 定义泛型变量，匹配所有可被装饰的函数类型
FuncT = TypeVar("FuncT", bound=Callable[..., Any])

def decorator(func: FuncT) -> FuncT:
    def new_func(*args: Any, **kwargs: Any) -> Any:
        # 此处编写装饰器的实际逻辑，如日志打印、权限校验
        return func(*args, **kwargs)
    # 临时类型忽略标记：静态检查器暂无法直接识别内部new_func与泛型FuncT的匹配关系，不影响代码运行
    return new_func  # type: ignore[return-value]

• 该写法不会丢失原函数的类型信息：比如被装饰的原函数是def add(a: int, b: int) -> int，经过装饰后，调用add时如果传入非int类型参数，静态检查器可以正常识别报错。
• 禁止偷懒将func和装饰器返回值都写为Callable[..., Any]：这种写法会让所有被装饰的函数类型退化为模糊的“任意可调用对象”，完全失去类型注解的检查价值。

进阶高精度写法（Python 3.10+） #

如果需要100%匹配类型、无需额外的类型忽略标记，可以使用ParamSpec捕获原函数的完整参数签名，静态检查精度最高：

from typing import Callable, ParamSpec, TypeVar

# 捕获原函数的全部入参结构
ParamsT = ParamSpec("ParamsT")
# 捕获原函数的返回值类型
ReturnT = TypeVar("ReturnT")

def decorator(func: Callable[ParamsT, ReturnT]) -> Callable[ParamsT, ReturnT]:
    def new_func(*args: ParamsT.args, **kwargs: ParamsT.kwargs) -> ReturnT:
        return func(*args, **kwargs)
    return new_func

新手常见踩坑提醒 #

• 不要在Callable的参数列表中硬写[*args, **kwargs]：这是无效语法，静态检查器会直接报错，需要表达“任意入参”时直接使用...占位即可，如Callable[..., Any]
• 不要为了凑注解写和原函数不兼容的返回类型：比如装饰后返回与原函数签名无关的函数类型，会导致静态检查结果与实际运行逻辑脱节

内容的提问来源于stack exchange，提问作者Taiki Okano