从零看懂 Python 装饰器:函数穿上的那件＂魔法外套＂

你有没有在别人的代码里看到过 @staticmethod、@property、@app.route('/login') 这样的写法，心里犯嘀咕：这个 @ 到底在干嘛？

更扎心的是，你可能已经"会用"装饰器了——复制粘贴，跑得起来，但一旦要自己写一个，就两眼一抹黑。

其实，装饰器一点也不神秘。只要搞懂两个底层概念——函数是一等公民和闭包——装饰器的逻辑就能迎刃而解。

打个比方：装饰器就像是给函数"穿外套"。函数本来只穿着内衣（核心逻辑），你给它套上一件外套（装饰器），它就多了保暖（额外功能）的能力，但内衣还是那件内衣，核心逻辑没有变。

接下来，我们一层一层剥开它。

第一层：函数是一等公民

在 Python 中，函数是"一等公民"（first-class citizen）。这句话听着学术，意思是：函数和整数、字符串一样，也是一种普通的对象。它可以被赋值给变量，可以当作参数传递，也可以当作返回值返回。

用三个例子感受一下：

# 1. 函数可以赋值给变量
defgreet(name):
returnf"Hello, {name}!"

say_hello = greet  # 把函数赋值给另一个变量
print(say_hello("Alice"))  # Hello, Alice!

# 2. 函数可以作为参数传递
defapply(func, value):
return func(value)  # 把收到的函数拿来调用

print(apply(greet, "Bob"))  # Hello, Bob!

# 3. 函数可以作为返回值
defmake_multiplier(factor):
defmultiply(n):
return n * factor
return multiply  # 返回的不是结果，而是一个函数

double = make_multiplier(2)
print(double(5))  # 10复制

你看，函数在 Python 里就像快递包裹一样，可以被传来传去。这个特性是装饰器存在的根基——因为装饰器本质上就是一个"接收函数、返回函数"的函数。

第二层：闭包

理解了函数是一等公民，我们再往前走一步：闭包。

闭包听起来很玄，其实就一句话：内层函数引用了外层函数的变量，并且外层函数已经返回了，但那个变量依然活着。

看代码：

defmake_counter():
    count = 0# 外层函数的局部变量

definner():
nonlocal count  # 声明：我要用的是外层的 count
        count += 1
return count

return inner  # 返回内层函数

counter = make_counter()
print(counter())  # 1
print(counter())  # 2
print(counter())  # 3复制

注意，make_counter() 执行完返回后，count 这个变量按理说应该被回收。但实际上，inner 函数"记住"了它，每次调用 counter() 都会修改同一个 count。

这就是闭包：一个带"记忆"的函数。就像一个旅行者背着背包，背包里装着出发前别人塞给他的东西，走到哪儿都带着。

为什么闭包是装饰器的基础？ 因为装饰器的核心操作就是：定义一个外层函数接收被装饰的函数，在里面定义一个内层函数（wrapper）来"包装"它，然后返回这个内层函数。wrapper 需要记住外层传进来的那个原函数——这就是闭包。

第三层：手写第一个装饰器

现在，把前面两层拼起来，手写一个最实用的装饰器——计时器。

需求：给一个函数套上"计时外套"，调用时自动打印执行耗时。

import time

deftimer(func):
defwrapper(*args, **kwargs):
        start = time.time()
        result = func(*args, **kwargs)  # 调用原函数
        end = time.time()
print(f"{func.__name__} 执行耗时：{end - start:.4f} 秒")
return result  # 别忘了把原函数的结果返回
return wrapper复制

这就是一个完整的装饰器。timer 接收一个函数 func，返回一个新的函数 wrapper。wrapper 在调用 func 前后插入了计时代码。

怎么用？两种方式：

# 方式一：手动赋值（让你看清楚本质）
defslow_function():
    time.sleep(1)
print("函数执行完毕")

slow_function = timer(slow_function)  # 用 wrapper 替换原函数
slow_function()
# 输出：
# 函数执行完毕
# slow_function 执行耗时：1.0012 秒

# 方式二：@ 语法糖（优雅写法，和上面完全等价）
@timer
defslow_function():
    time.sleep(1)
print("函数执行完毕")

slow_function()复制

关键理解：@timer 这行代码，本质上就是 slow_function = timer(slow_function) 的语法糖。Python 看到 @timer，就会自动把下面的函数传给 timer，然后用返回的 wrapper 替换掉原函数名。

一句话总结：装饰器 = 接收函数 → 返回新函数 → 用新函数替换旧函数。

第四层：带参数的装饰器

有时候你需要给装饰器传参，比如 @repeat(times=3) 表示"重复执行 3 次"。这时候需要再多嵌一层函数。

为什么？因为 @repeat 后面跟的函数会被传给 repeat 的返回值。如果你想传参数，就得让 repeat 先接收参数，返回一个"真正的装饰器"。

defrepeat(times):  # 第一层：接收参数
defdecorator(func):  # 第二层：接收被装饰的函数
defwrapper(*args, **kwargs):  # 第三层：实际包装逻辑
            result = None
for i inrange(times):
                result = func(*args, **kwargs)
return result
return wrapper
return decorator

@repeat(times=3)
defsay_hi(name):
print(f"Hi, {name}!")

say_hi("Alice")
# 输出：
# Hi, Alice!
# Hi, Alice!
# Hi, Alice!复制

执行过程：@repeat(times=3) → 先调用 repeat(3) 得到 decorator → 再用 decorator 装饰 say_hi → 即 say_hi = decorator(say_hi) = wrapper。

三层嵌套确实有点绕，但记住这个套路就行：参数在最外层，函数在中间层，逻辑在最内层。

第五层：三个最实用的实战场景

理论讲完了，来点实际的。以下是开发中最常用的三个装饰器场景，每个都附完整代码，可以直接复制使用。

场景一：计时性能分析

快速定位哪个函数慢，不需要手动在函数前后插 time.time()：

import time
import functools

deftimer(func):
    @functools.wraps(func)  # 先忽略这行，后面会讲
defwrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
print(f"[Timer] {func.__name__} 耗时 {elapsed:.6f}s")
return result
return wrapper

@timer
defprocess_data(data):
    time.sleep(0.5)
returnf"处理了 {len(data)} 条数据"

print(process_data([1, 2, 3, 4, 5]))
# [Timer] process_data 耗时 0.500312s
# 处理了 5 条数据复制

场景二：日志记录

自动记录函数的调用参数、返回值和异常，调试利器：

import functools
from datetime import datetime

deflog(func):
    @functools.wraps(func)
defwrapper(*args, **kwargs):
        args_str = ", ".join(
            [repr(a) for a in args] +
            [f"{k}={v!r}"for k, v in kwargs.items()]
        )
print(f"[{datetime.now():%Y-%m-%d %H:%M:%S}] 调用 {func.__name__}({args_str})")
try:
            result = func(*args, **kwargs)
print(f"[Log] {func.__name__} 成功，返回: {result!r}")
return result
except Exception as e:
print(f"[Log] {func.__name__} 失败: {e}")
raise
return wrapper

@log
defdivide(a, b):
return a / b

print(divide(10, 2))
# [2025-01-15 10:30:00] 调用 divide(10, 2)
# [Log] divide 成功，返回: 5.0
# 5.0

print(divide(10, 0))
# [2025-01-15 10:30:01] 调用 divide(10, 0)
# [Log] divide 失败: division by zero
# ZeroDivisionError: division by zero复制

场景三：缓存 @functools.lru_cache

这是 Python 内置的装饰器，自动缓存函数结果，递归计算性能提升立竿见影：

import functools
import time

# 不使用缓存
deffib_slow(n):
if n < 2:
return n
return fib_slow(n - 1) + fib_slow(n - 2)

# 使用缓存
@functools.lru_cache(maxsize=128)
deffib_fast(n):
if n < 2:
return n
return fib_fast(n - 1) + fib_fast(n - 2)

# 性能对比
start = time.perf_counter()
print(fib_slow(35))      # 9227465
print(f"无缓存: {time.perf_counter() - start:.4f}s")  # 约 2-3 秒

start = time.perf_counter()
print(fib_fast(35))      # 9227465
print(f"有缓存: {time.perf_counter() - start:.6f}s")  # 几乎 0 秒复制

同样的逻辑，加了 @functools.lru_cache，性能差距是数百倍。这就是装饰器的威力——一行代码，四两拨千斤。

第六层：functools.wraps 的作用

你可能注意到，上面的代码里都有一行 @functools.wraps(func)。它到底在干嘛？

先看不加的效果：

defmy_decorator(func):
defwrapper(*args, **kwargs):
return func(*args, **kwargs)
return wrapper

@my_decorator
defhello(name):
"""这是一个打招呼的函数"""
returnf"Hello, {name}"

print(hello.__name__)  # wrapper  ← 函数名变成了 wrapper！
print(hello.__doc__)   # None     ← 文档字符串丢了！复制

问题在于：装饰器用 wrapper 替换了原函数，所以 hello 现在实际上是 wrapper，原来的名字和文档都丢了。这在调试时会让人困惑——报错信息和堆栈里全是 wrapper，根本看不出是哪个函数出了问题。

加上 @functools.wraps(func) 就解决了：

import functools

defmy_decorator(func):
    @functools.wraps(func)  # 把原函数的元信息复制到 wrapper 上
defwrapper(*args, **kwargs):
return func(*args, **kwargs)
return wrapper

@my_decorator
defhello(name):
"""这是一个打招呼的函数"""
returnf"Hello, {name}"

print(hello.__name__)  # hello    ← 函数名保留
print(hello.__doc__)   # 这是一个打招呼的函数  ← 文档保留复制

functools.wraps 的作用就是把原函数的 __name__、__doc__、__module__ 等元信息复制到 wrapper 上，让 wrapper "伪装"成原函数。

一句话：写装饰器时，永远加上 @functools.wraps(func)，养成习惯，百利无一害。

回顾一下，装饰器的本质就两层：

1. 函数是一等公民
   ——函数可以被传来传去，这是前提。
2. 闭包
   ——内层函数记住外层函数的变量，这是装饰器能"包装"函数的机制。

掌握了这两点，@ 语法糖不过是 func = decorator(func) 的简写，带参数的装饰器不过是多套一层壳，functools.wraps 不过是保留元信息的小细节。

装饰器是 Python 中最优雅的特性之一。理解了它的底层逻辑，你不仅能看懂别人的代码，更能写出自己的"魔法外套"，给任何函数一键加上计时、日志、缓存、权限校验……只有你想不到，没有它包不到。

最好的学习方式就是动手。 打开你的编辑器，把文章里的代码敲一遍，再试着自己写一个装饰器——比如一个"限流"装饰器，限制函数每秒最多调用 N 次。你会发现，一旦理解了本质，动手写就是水到渠成的事。

标签：#Python #编程技巧 #装饰器 #Python进阶