装饰器

是什么，为什么存在

Python 装饰器把一个可调用对象转换成另一个对象。最常见的函数装饰器接收函数，返回一个在调用前后加入行为的包装函数；类也可以作为输入。@trace 写在 def 上方时，名称最终绑定的是 trace() 的返回值，不一定还是原函数。

这种机制建立在 一等函数（first-class function） 之上：函数能作为实参传入，也能作为返回值传出。包装函数通常还是 闭包（closure） ，通过外层绑定找到原函数和配置。装饰器本身也可以是函数、类或其他可调用对象。

装饰器适合表达多个函数都必须遵守的窄规则，例如记录调用、授权检查、重试入口或注册声明。它把规则放在一个实现中，又让被装饰函数保留自己的业务主体。规则若改变返回类型、吞掉异常或依赖隐式全局状态，@ 语法反而会藏住重要行为，此时显式函数调用或对象组合更清楚。

你会在标准库的 @property、@classmethod、@staticmethod、@functools.cache 和 @functools.singledispatch 中遇到装饰器。Web 路由、测试夹具和命令注册也经常采用同一语法，但各框架为返回对象规定了额外契约。理解 Python 自己的替换规则，是阅读这些框架约定的前提。

装饰器不是运行函数时临时打开的开关。执行到定义语句时，Python 就会计算装饰器表达式、调用装饰器并完成名称绑定；模块导入通常会触发这一过程。包装器的函数体则要等到之后真正调用时才运行。

工作原理

执行一个带装饰器的函数定义时，Python 先在外层作用域中从上到下计算各装饰器表达式，再创建原函数对象。得到的可调用对象从内到外接收该对象。最外层装饰器的返回值最后绑定到函数名称。

下面的等价关系最值得记住。若源码从上到下写成 @outer(config)、@inner 和 def handle(...): ...，最终绑定近似为 handle = outer(config)(inner(handle))；差别是原函数不会先临时绑定到 handle。装饰器表达式按书写顺序求值，应用则从最靠近 def 的一层向外进行。

定义阶段和调用阶段必须分开分析。工厂 outer(config) 在定义阶段运行并产生真正的装饰器，inner(handle) 与外层应用也在该阶段完成。以后调用 handle() 时，控制流从最外层包装器进入，逐层到达原函数，再按相反方向返回。

包装器必须保住契约

一个透明函数装饰器至少要转发所有实参、返回原结果，并让未处理异常继续传播。*args 和 **kwargs 能转发调用形状，但它们本身没有保留 函数签名（function signature） 。包装器若故意增加参数、改变同步形式或修改返回类型，就应把变化当成新的公开 API，而不是继续声称完全透明。

functools.wraps(func) 会把常用元数据复制到包装函数，并设置 __wrapped__ 指回被包装对象。inspect.signature() 默认沿着这条链寻找原签名，文档工具和部分框架也依赖它。wraps() 不会修复错误的参数转发、返回值、异常策略或同步／异步边界。

运行时元数据与静态类型是两套机制。类型保持型装饰器可以用 ParamSpec 表示原参数列表，用 TypeVar 表示返回类型；@wraps 仍然需要保留运行时检查链。类型注解不会验证调用，也不能证明包装器确实原样返回结果。

函数、方法与类

普通函数实现了描述符绑定，因此放在类属性中后，通过实例访问会自动得到绑定方法。返回普通函数的装饰器通常自然保留这一行为。若装饰器返回只有 __call__()、却没有合适 __get__() 的实例，obj.method() 不会自动注入 self。

@classmethod、@staticmethod 与 @property 返回的是描述符对象，次序会影响外层装饰器收到什么。一个只接受普通函数并读取 __name__ 的装饰器，未必能包装任意描述符。对每种支持的目标都应明确约束，并通过类和实例两种访问路径测试。

类装饰器在类对象创建后接收它，并把返回值绑定到类名。它可以登记或修改这个类，但装饰过程不会因为之后定义了子类而自动再执行。若类装饰器返回函数来实现单例，原名称就不再是类，isinstance()、继承和类型工具会得到完全不同的对象。

示例

下面四个示例依次展示透明包装、带参数工厂、堆叠顺序与异步边界。输出来自本地 Python 3.12.13；示例同时按目标版本 Python 3.14 的文档核对，未使用两者之间有差异的 API。

透明地记录一次调用

trace() 返回的新函数负责记录入口和返回值，然后把结果交还调用方。@wraps(func) 让名称、文档和默认检查签名仍指向 total() 的公开契约。

total 是包装函数，但 total.__wrapped__ 保留了通往原函数的明确链接。直接调用这个属性会绕过日志，所以它适合检查、测试或有意绕过某层行为，不应被当作普通业务入口。

日志代码使用 repr() 展示实参只是为了得到确定输出。真实系统不应无条件记录口令、令牌或个人数据，而且打印完整返回对象可能既泄密又很昂贵。数据脱敏属于装饰器契约的一部分。

用装饰器工厂配置重试

retry_on() 先接收异常类型与次数，再返回接收函数的装饰器。真正的包装器只捕获声明过的异常；次数无效时，工厂在定义阶段立刻拒绝配置。

from functools import wraps


def retry_on(exception_type, *, attempts):
    if attempts < 1:
        raise ValueError("attempts must be at least 1")

    def decorate(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(1, attempts + 1):
                try:
                    return func(*args, **kwargs)
                except exception_type as error:
                    print(f"attempt {attempt}: {error}")
                    if attempt == attempts:
                        raise

        return wrapper

    return decorate


responses = iter([
    ConnectionError("temporary outage"),
    ConnectionError("temporary outage"),
    "12 units",
])


@retry_on(ConnectionError, attempts=3)
def fetch_inventory():
    outcome = next(responses)
    if isinstance(outcome, Exception):
        raise outcome
    return outcome


print(fetch_inventory())

attempt 1: temporary outage
attempt 2: temporary outage
12 units

三层调用各有一个职责：retry_on(...) 配置工厂，decorate(func) 接收被装饰函数，wrapper(...) 处理每次调用。把其中两层混在一起，常会导致 @retry_on(...) 得到的不是装饰器，或者定义时就误调业务函数。

这个示例刻意没有加入等待。生产重试还要规定退避、抖动、截止时间、取消和幂等性，而且只能重试被判定为临时故障的异常。装饰器能复用策略，却不能替业务操作决定重复执行是否安全。

看清堆叠的两个顺序

layer() 在定义阶段打印 build，返回的装饰器打印 apply，包装器在调用阶段打印 enter 与 leave。一份输出同时暴露表达式求值、装饰器应用和包装链调用的顺序。

from functools import wraps


def layer(name):
    print(f"build {name}")

    def decorate(func):
        print(f"apply {name} to {func.__name__}")

        @wraps(func)
        def wrapper():
            print(f"enter {name}")
            result = func()
            print(f"leave {name}")
            return result

        return wrapper

    return decorate


@layer("outer")
@layer("inner")
def render_invoice():
    print("body")
    return "done"


print(render_invoice())

build outer
build inner
apply inner to render_invoice
apply outer to render_invoice
enter outer
enter inner
body
leave inner
leave outer
done

表达式从上到下求值，所以先出现 build outer。应用从下到上，调用从外到内，返回再从内到外。仅说「装饰器从下到上执行」会把三个不同阶段混为一谈。

顺序会改变真实语义。把审计放在授权外层，可以记录被拒绝的尝试；放在授权内层，只能看到通过的调用。事务、缓存和重试的次序也会改变哪些结果被缓存、哪次尝试属于同一事务。

保持异步边界

异步函数的透明包装器也必须是 async def，并在自己的 try 范围内 await 原函数。这样异常和清理发生在包装器仍控制的执行期间，调用方看到的仍是协程函数。

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


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


def trace_async(func: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
    @wraps(func)
    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        print(f"start {func.__name__}")
        try:
            return await func(*args, **kwargs)
        finally:
            print(f"finish {func.__name__}")

    return wrapper


@trace_async
async def load_order(order_id: int) -> str:
    await asyncio.sleep(0)
    return f"order:{order_id}"


async def main():
    print(inspect.iscoroutinefunction(load_order))
    print(await load_order(42))


asyncio.run(main())

True
start load_order
finish load_order
order:42

如果普通 def wrapper 只返回 func(...)，返回的是尚未执行的协程对象。包装器里的计时、异常捕获和清理会覆盖「创建协程」而不是「运行协程」，inspect.iscoroutinefunction() 也会把外层视为同步函数。

finally 会在成功、异常和取消路径上执行，但它不应吞掉异常或取消。需要同时支持同步与异步函数时，应在装饰阶段检查目标并生成两种不同包装器，而不是让一个同步包装器猜测返回值是否可等待。

陷阱

忘记 functools.wraps

修复方法： 在每个返回普通函数的透明包装层上使用 @wraps(func)，并断言 __name__、inspect.signature() 与 __wrapped__。若装饰器故意改签名，就明确发布新签名，不要借 wraps() 假装没有变化。

丢失返回值或异常

修复方法： 透明包装器直接返回原结果，并只捕获策略明确要求处理的异常。测试一个非 None 返回值、一个预期异常，以及包装器自身前置或后置逻辑失败的路径。

把定义时副作用当成调用时行为

修复方法： 只把稳定配置验证和必要注册留在定义阶段。资源获取应放进有明确生命周期的调用或应用启动流程，并分别测试「只导入模块」和「实际调用函数」。

凭直觉排列多个装饰器

修复方法： 把堆叠展开成嵌套调用，为每层写出输入、输出和异常边界。用事件列表断言进入与退出顺序，并覆盖拒绝、缓存命中、一次失败后成功和最终失败。

用一个实现同时包装同步与异步函数

修复方法： 在装饰阶段用 inspect.iscoroutinefunction() 分支，生成 def 和 async def 两个包装器，或者提供两个明确装饰器。两条路径都要测试成功、异常与元数据；异步路径还要测试取消。

让装饰器实例意外共享状态

修复方法： 标明状态属于装饰器配置、被装饰函数、实例、请求还是调用。至少装饰两个函数并交错调用；共享若不是明确契约，就在每次装饰时创建独立状态，或改用更容易表达所有权的类。

延伸阅读

• Python 术语表：装饰器
• Python 语言参考：函数定义与装饰器应用
• Python functools.wraps()
• Python inspect.signature()
• Python typing.ParamSpec
• Python 描述符指南：函数与方法