Python 装饰器:我以为的语法糖,其实是定义时立刻执行的函数调用

这个坑我是被项目逼着学会的。
有一次产品要求给所有接口加耗时统计,我打开函数,开头写一行 start_time = time.time(),return 前再写一行 print。改到第三个函数时我开始怀疑人生——同样的代码复制粘贴几十遍,以后改格式还得逐个文件翻。于是搜索"Python 不修改函数添加日志",所有答案都指向同一个词:装饰器。
但学装饰器的过程比改代码还痛苦。教程上来就甩一个 @xxx,看不懂为什么 @ 后面跟函数名、为什么有的装饰器带括号有的不带、为什么 wrapper 里要写 *args, **kwargs、为什么还要 import 一个叫 wraps 的东西。我一度把它当成需要背下来的语法咒语。
直到后来才明白:装饰器没有任何魔法,它只是一个普通的函数调用,@ 只是 Python 官方提供的一个缩写。 把这层窗户纸捅破,所有"为什么"就都有了答案。这篇笔记就是从头捅到底。

一、先补两块地基:函数是对象,闭包是记忆

装饰器踩坑的根源,是很多人跳过了两个基础概念直接学语法。快速补齐。
第一块:函数是对象。 Python 里函数和字符串、整数一样,是普通值——可以赋给变量、装进列表、当参数传给另一个函数、当返回值返回:

def hello(name):
    return f"Hello, {name}"
greet = hello           # 函数赋给变量,注意没有括号——不是调用,是传递
funcs = [hello, greet]  # 装进列表
print(funcs[0]("Bob"))  # Hello, Bob
def call_it(func, arg): # 函数当参数
    return func(arg)
print(call_it(hello, "Carol"))

hello 和 hello() 的区别是理解一切后续内容的钥匙:前者是"函数对象本身",后者是"执行它并取结果"。
第二块:闭包。 函数里定义函数,内层函数能访问外层函数的变量——而且即使外层函数已经 return 了,这个"记忆"依然保留:

def outer(x):
    def inner(y):
        return x + y    # inner 记住了 x
    return inner
add5 = outer(5)          # outer 执行完毕、已经返回
print(add5(10))          # 15 —— x=5 还活着

可以把闭包理解成:函数对象随身带一个小背包,里面装着它定义时所在作用域的变量引用。这个小背包正是装饰器能"记住"原函数的根本。
两块地基铺好,装饰器只剩一件事要做:把函数传进函数、包装、返回。

二、撕开 @:它就是一行赋值语句

先完全不用语法糖,手写一个"包装":

def add_log(func):
    def wrapper():
        print("函数执行前")
        func()
        print("函数执行后")
    return wrapper
def say_hello():
    print("Hello!")
# 手动包装:传进去,拿回新的,替换原名
say_hello = add_log(say_hello)
say_hello()
# 输出:函数执行前 / Hello! / 函数执行后

看最后那行赋值:say_hello = add_log(say_hello)。这个动作就是装饰器的全部——把原函数传给包装函数,返回增强版,用原名指回它。
而 Python 觉得这行赋值写起来啰嗦,就发明了 @ 缩写:

@add_log
def say_hello():
    print("Hello!")

这两段代码在 Python 解释器眼里一模一样。 遇到 @add_log,解释器的翻译动作就是执行 say_hello = add_log(say_hello)。
这是全文最重要的一句话,值得单独放大:

@ 不是"注解"或"标记",它是一条在函数定义完成的瞬间立刻执行的语句。 带括号就立即执行——这是函数调用的基本规则,@ 不会豁免它。
这个认知直接解释了新手最容易栽的坑,第五节会回来收割。

三、造一个万能模板:*args、**kwargs 和 @wraps

上一节的 wrapper() 只能包装无参数无返回值的函数——真实代码几乎不存在这种函数。需要两个补丁,补完就是一个可以无脑复用的模板。
补丁一:适配任意签名。 让 wrapper 接收任意位置参数和关键字参数,原封不动转发给原函数:

def wrapper(*args, **kwargs):
    result = func(*args, **kwargs)   # 转发,并接住返回值
    return result

补丁二:治"身份失忆症"。 包装之后 say_hello 这个名字指向的其实是 wrapper——于是 say_hello.__name__ 变成了 'wrapper',文档字符串也丢了。这会破坏调试信息,更严重的是让依赖函数名做路由注册的框架(Flask、FastAPI)直接失效。
解药是标准库的 functools.wraps,它把原函数的元数据(__name__、__doc__ 等)拷贝给 wrapper:

from functools import wraps
def add_log(func):
    @wraps(func)                    # 一行,身份找回
    def wrapper(*args, **kwargs):
        print(f"调用 {func.__name__}")
        result = func(*args, **kwargs)
        print(f"{func.__name__} 返回 {result!r}")
        return result
    return wrapper

两块补丁打完,这就是通用装饰器的标准模板——计时、重试、缓存、权限校验,全都长这个骨架。

四、带参数的装饰器:为什么要套三层

下一个拦路虎是这种写法:

@repeat(num_times=3)
def greet(name):
    print(f"Hello, {name}!")

@repeat 后面怎么带括号了?之前的 @add_log 不带啊?
回到那个核心认知:@ 后面跟的是一个"会返回装饰器的调用"。拆解执行过程:

@repeat(num_times=3)
def greet(name): ...

等价于:

greet = repeat(num_times=3)(greet)

从里往外读:先执行 repeat(num_times=3),它返回一个装饰器;这个装饰器再吃掉 greet,返回 wrapper。所以 repeat 的结构必须是三层嵌套:

def repeat(num_times):          # 第一层:装饰器工厂,吃配置
    def decorator(func):        # 第二层:真正的装饰器,吃函数
        @wraps(func)
        def wrapper(*args, **kwargs):   # 第三层:干活的人
            for _ in range(num_times):
                result = func(*args, **kwargs)
            return result
        return wrapper
    return decorator

为什么必然三层?因为配置和函数是两次分开的投喂:num_times 在 @repeat(num_times=3) 时进来,func 在函数定义完成时才进来。两次投喂,需要两层函数分别接住,加上最里面干活的 wrapper,正好三层。这不是设计炫技,是逻辑推论——想通了这一点,"带参装饰器要套三层"就从需要背的规则变成了显然的事实。
顺带补一条堆叠规则:多个装饰器从下往上应用,等价于从上往下嵌套包裹:

@a
@b
def f(): ...
# 等价于 f = a(b(f))

五、三大踩坑实录

学完结构,该收割第二节埋下的那个认知了。三个坑都源于对"@ 是语句"理解不彻底。

坑一:装饰器在导入时就"偷跑"(杀伤力最大)

我在生产环境栽过的具体场景:为了发监控日志,装饰器里初始化了一个数据库连接池。结果容器启动后 K8s 健康检查超时,直接杀 Pod——明明一个接口都没被调用,启动却卡在 import 某个模块那里两分钟。
还原现场:

import time
def monitor_decorator(func):
    print(f"正在初始化监控,绑定 {func.__name__}")
    time.sleep(3)                        # 模拟连接池初始化
    print("监控就绪")
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper
@monitor_decorator
def get_user_info(user_id):
    return f"用户 {user_id}"

只是 import 这个模块、一次都没调用,控制台照样输出那两行、照样等 3 秒。因为 @monitor_decorator 就是 get_user_info = monitor_decorator(get_user_info)——只要模块被加载,这行就执行,装饰器外层的代码就跑完。我当年"以为它在等指令,其实它第一眼看到我就动手了"。
正确姿势:所有重操作(连数据库、读文件、建连接)必须挪进 wrapper 内部,实现懒加载——第一次真正调用时才初始化。装饰器外层只做轻量的准备工作。

坑二:忘了 @wraps,框架炸了

代码本地跑得好好的,接上 Flask/FastAPI 后路由全失效。排查半天,发现 __name__ 全是 'wrapper'——框架靠函数名注册路由,包装后名字丢了。习惯:写 wrapper 之前先敲 @wraps(func),把它当成模板的一部分,而不是可选项。

坑三:三层漏写一层,报错看不懂

带参数装饰器少嵌套一层,@repeat(3) 会把 3 当函数传进去,报错完全对不上号。定位办法就是心里默背那句等价式 f = repeat(3)(f),检查每一层吃的是什么。

六、三个可以直接抄走的实战装饰器

学习笔记的终点是工具箱。三个高频场景的成品代码,均已含 @wraps、均已懒加载。
计时器:

import time
from functools import wraps
def timing(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__}: {elapsed:.4f}s")
        return result
    return wrapper

重试器(带参数版):

def retry(max_attempts=3, delay=1):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_attempts):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    if attempt == max_attempts - 1:
                        raise
                    time.sleep(delay * (2 ** attempt))  # 指数退避
        return wrapper
    return decorator
@retry(max_attempts=3, delay=0.5)
def fetch_api(url):
    ...

缓存器——其实标准库已经写好了,functools.cache 就是一个官方装饰器,直接用:

from functools import cache
@cache
def fibonacci(n):
    return n if n < 2 else fibonacci(n-1) + fibonacci(n-2)

看到 @cache 时可以顺便检验一下自己的理解:它是无参数装饰器(两层结构),在定义时执行,wrapper 里带着对原函数的闭包引用。

结语

回头看这篇笔记走过的路,其实只有一句话:

@ 不是魔法,是 f = decorator(f) 这行赋值的官方缩写——它在函数定义完成的瞬间执行,仅此而已。
这句话往前推,得到"装饰器在导入时就运行",于是坑一的启动卡死可以推演出来;往前推,得到"带参数时 @ 后面是一次调用返回装饰器",于是三层嵌套的必然性可以推演出来;往前推,得到"原名被 wrapper 顶替",于是 @wraps 的必要性也可以推演出来。学语法的痛苦,九成来自把"可推导的东西"当"需要背诵的东西"。
这也是技术学习笔记这个方向的价值所在:踩坑的意义从来不是记住坑的位置,而是把坑背后的机制挖出来。机制有了,下一个没见过的语法糖——@property、@staticmethod、@dataclass——你都能自己拆开看。

posted @ 2026-10-18 23:11  汤姆百宝箱  阅读(15)  评论(0)    收藏  举报