Python 装饰器怎样保留原函数参数类型

给一个业务函数加日志、鉴权或重试时，装饰器最容易留下的类型问题是：原函数明明接收 user_id: int 和 verbose: bool，包装函数却被写成了 Callable[..., Any]。这样运行时通常没有问题，但调用方的参数检查会退化成“什么都可以传”。

更合适的做法是用 ParamSpec 表示“原函数整组参数”，再用 TypeVar 表示返回值。本文只讨论 ParamSpec、Callable 和 Concatenate 这条装饰器签名链路。

官方资料：https://docs.python.org/3.14/library/typing.html

只转发原函数参数时使用 Callable[P, R]；装饰器给被调用函数增加固定参数时，再使用 Concatenate[固定参数, P]。functools.wraps 负责运行时元数据，不会单独让静态类型检查器恢复参数签名。

先把运行时名称和静态签名分开

functools.wraps 很有用：它会把被装饰函数的名称、文档字符串等元数据复制到包装函数上，让调试信息和文档更接近原函数。但它的职责不是声明类型变量，不能替代 ParamSpec。

下面这种写法虽然简短，却把参数和返回值都放宽了。静态检查器只知道装饰器接收一个“任意参数、任意返回值”的可调用对象。

from collections.abc import Callable
from functools import wraps
from typing import Any

def log_call(func: Callable[..., Any]) -> Callable[..., Any]:
    # wraps 保留名称和文档；Any 不会保留原函数的参数契约。
    @wraps(func)
    def wrapper(*args: Any, **kwargs: Any) -> Any:
        # 这里负责记录调用，再把参数原样交回原函数。
        print("call", func.__name__)
        return func(*args, **kwargs)
    return wrapper

如果装饰器只是增加横切逻辑、没有改变调用参数，目标应是让输入函数和输出函数共享同一个参数规格，而不是用省略号掩盖差异。

用 ParamSpec 把原函数参数整体转发

ParamSpec 是给参数列表使用的类型变量。它不像 TypeVar 那样只代表一个值类型，而是可以在 Callable[P, R] 中代表一整组位置参数和关键字参数。包装函数里对应的 P.args 与 P.kwargs 就是这组参数的转发入口。

from collections.abc import Callable
from functools import wraps
from typing import ParamSpec, TypeVar

P = ParamSpec("P")
R = TypeVar("R")

def log_call(func: Callable[P, R]) -> Callable[P, R]:
    # P 绑定原函数的整组参数，R 绑定原函数的返回值类型。
    @wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        # args 和 kwargs 只做透传，横切逻辑不会改变调用契约。
        print("call", func.__name__)
        return func(*args, **kwargs)
    return wrapper

这里有两个对称的 P：装饰器参数里的 Callable[P, R] 说明“传入函数接受什么”，返回值里的 Callable[P, R] 说明“装饰后仍接受同样的什么”。包装函数的两个展开式把这组参数转发回去。

这也是 Callable[..., Any] 与 Callable[P, R] 的关键差别：前者只表达“能调用”，后者表达“调用形状由传入函数决定”。Python 官方文档把这种用途定义为在高阶函数和装饰器之间转发参数类型。

用 TypeVar 让返回值也保持精确

只写好 P 还不够。如果装饰器的返回标注固定成 object 或 Any，调用方仍然拿不到原函数的返回值类型。R 把这部分关系连接起来：传入函数返回 Invoice，装饰后的函数也返回 Invoice。

from dataclasses import dataclass

@dataclass
class Invoice:
    # 业务对象只用于说明返回值类型会被 R 传递。
    number: str

@log_call
def load_invoice(number: str, *, strict: bool = True) -> Invoice:
    # strict 是关键字参数，用来观察 P.kwargs 是否仍然有效。
    return Invoice(number=number)

invoice = load_invoice("A-100", strict=False)
# invoice 仍可被静态检查器推断为 Invoice，而不是 Any。
print(invoice.number)

如果调用处把 strict 写成不存在的参数，或者把 number 传成不符合检查器规则的类型，问题就有机会在静态检查阶段暴露。需要注意的是，Python 运行时本身不会强制执行这些注解，真正的检查由类型检查器、编辑器或相关工具完成。

装饰器新增固定参数时用 Concatenate

前面的装饰器没有改变参数，只是把参数原样转发。如果装饰器会在内部替调用方注入一个固定对象，例如统一传入 Logger，这时新函数对外暴露的参数会比内部原函数少一个。仅写 Callable[P, R] 无法表达这个变化。

Concatenate[Logger, P] 表示原函数的参数由一个固定的 Logger 加上剩余的 P 组成，而装饰后的函数只暴露 P。Concatenate 的最后一项必须是 ParamSpec 或省略号。

from collections.abc import Callable
from logging import Logger
from typing import Concatenate, ParamSpec, TypeVar

P = ParamSpec("P")
R = TypeVar("R")

def with_logger(func: Callable[Concatenate[Logger, P], R]) -> Callable[P, R]:
    # 原函数需要 Logger，装饰后的函数把 Logger 隐藏在包装层内。
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        # logger 的来源由装饰器控制，调用方不必重复传入。
        logger = Logger("service")
        return func(logger, *args, **kwargs)
    return wrapper

这种写法适合“注入依赖但不想让每个调用点重复传参”的场景。反过来，如果装饰器实际上给调用者新增了参数，也要按真实的对外签名调整 Concatenate 和返回的 Callable，不要只为了通过检查器而隐藏参数变化。

版本写法和兼容范围怎么选

ParamSpec 与 Concatenate 在 Python 3.10 加入 Callable 相关支持。Python 3.12 又支持了 PEP 695 的类型参数语法，但项目如果需要兼容更早版本，使用 ParamSpec("P") 和 TypeVar("R") 的传统写法更稳妥。

# Python 3.10+：兼容性较宽的声明方式
from typing import ParamSpec, TypeVar

P = ParamSpec("P")  # 让检查器追踪一整组参数
R = TypeVar("R")    # 让检查器追踪返回值

# Python 3.12+ 也可以把类型参数写进函数定义：
# def log_call[T, **P](func: Callable[P, T]) -> Callable[P, T]: ...

选择时看项目的解释器版本、类型检查器版本和团队的可读性偏好。不要把“运行时能导入 ParamSpec”误认为“所有静态检查器都已经按同样规则分析了项目”，升级后应在项目现有检查命令中确认报告变化。

一个简单的决策表

常见问题

ParamSpec 和 TypeVar 是一回事吗？

不是。TypeVar 通常表示一个类型位置，例如返回值 R；ParamSpec 表示可调用对象的整组参数，并能拆成 P.args 与 P.kwargs。

用了 wraps 还需要 ParamSpec 吗？

如果希望静态检查器保留调用契约，仍需要。wraps 解决运行时的名称、文档等元数据问题，ParamSpec 解决类型参数的传递问题。

所有装饰器都应该使用 Concatenate 吗？

不应该。只有装饰器确实增加、删除或变换固定参数时才需要它；纯转发场景使用 Callable[P, R] 更直接。

Python 会在运行时拒绝错误参数吗？

类型注解本身不会让 Python 运行时自动执行静态检查。运行时参数错误仍由函数调用规则、显式校验和业务逻辑处理，静态检查器则帮助你在提交代码前发现一部分不匹配。