Python 装饰器（Decorator）详解#

什么是装饰器？#

装饰器本质上是一个函数，它接收一个函数作为参数，并返回一个新的函数。它可以在不修改原函数代码的情况下，增强或改变函数的行为。

1
# 装饰器本质
2
@decorator
3
def func():
4
    pass
5

6
# 等价于
7
decorator(func)

最简单的装饰器示例#

1
def my_decorator(func):
2
    def wrapper():
3
        print("函数执行前...")
4
        func()
5
        print("函数执行后...")
6
    return wrapper
7

8
@my_decorator
9
def say_hello():
10
    print("Hello!")
11

12
say_hello()

输出：

1
函数执行前...
2
Hello!
3
函数执行后...

装饰器的执行流程#

1
┌─────────────────────────────────────────────────────────┐
2
│  @my_decorator                                          │
3
│  def say_hello():                                       │
4
│      print("Hello!")                                    │
5
└─────────────────────────────────────────────────────────┘
6
                          │
7
                          ▼
8
┌─────────────────────────────────────────────────────────┐
9
│  1. Python 解释器看到 @my_decorator                      │
10
│  2. 调用 my_decorator(say_hello)                        │
11
│  3. 返回 wrapper 函数                                    │
12
│  4. say_hello = wrapper                                 │
13
└─────────────────────────────────────────────────────────┘
14
                          │
15
                          ▼
16
┌─────────────────────────────────────────────────────────┐
17
│  调用 say_hello() 实际上是调用 wrapper()                  │
18
└─────────────────────────────────────────────────────────┘

使用场景#

1. 计时器 - 测量函数执行时间#

1
import time
2

3
def timer(func):
4
    def wrapper(*args, **kwargs):
5
        start = time.time()
6
        result = func(*args, **kwargs)
7
        end = time.time()
8
        print(f"{func.__name__} 执行耗时: {end - start:.4f} 秒")
9
        return result
10
    return wrapper
11

12
@timer
13
def slow_function():
14
    time.sleep(1)
15
    print("完成!")
16

17
slow_function()
18
# 输出:
19
# 完成!
20
# slow_function 执行耗时: 1.0012 秒

2. 日志记录#

1
def log(func):
2
    def wrapper(*args, **kwargs):
3
        print(f"调用函数: {func.__name__}, 参数: {args}, {kwargs}")
4
        result = func(*args, **kwargs)
5
        print(f"函数返回: {result}")
6
        return result
7
    return wrapper
8

9
@log
10
def add(a, b):
11
    return a + b
12

13
add(3, 5)
14
# 输出:
15
# 调用函数: add, 参数: (3, 5), {}
16
# 函数返回: 8

3. 权限验证#

1
def require_login(func):
2
    def wrapper(user, *args, **kwargs):
3
        if not user.get('is_logged_in'):
4
            print("请先登录!")
5
            return None
6
        return func(user, *args, **kwargs)
7
    return wrapper
8

9
@require_login
10
def view_profile(user):
11
    print(f"欢迎, {user['name']}!")
12

13
view_profile({'name': 'Alice', 'is_logged_in': False})  # 请先登录!
14
view_profile({'name': 'Alice', 'is_logged_in': True})   # 欢迎, Alice!

4. 缓存（记忆化）#

1
def cache(func):
2
    cached_results = {}
3
    def wrapper(*args):
4
        if args in cached_results:
5
            print(f"从缓存获取: {args}")
6
            return cached_results[args]
7
        result = func(*args)
8
        cached_results[args] = result
9
        return result
10
    return wrapper
11

12
@cache
13
def fibonacci(n):
14
    if n < 2:
15
        return n
16
    return fibonacci(n-1) + fibonacci(n-2)
17

18
print(fibonacci(10))  # 第一次计算
19
print(fibonacci(10))  # 从缓存获取

5. 重试机制#

1
import random
2

3
def retry(max_attempts=3):
4
    def decorator(func):
5
        def wrapper(*args, **kwargs):
6
            for attempt in range(max_attempts):
7
                try:
8
                    return func(*args, **kwargs)
9
                except Exception as e:
10
                    print(f"第 {attempt + 1} 次尝试失败: {e}")
11
            print("所有尝试均失败!")
12
        return wrapper
13
    return decorator
14

15
@retry(max_attempts=3)
16
def unstable_api():
17
    if random.random() < 0.7:
18
        raise ConnectionError("网络错误")
19
    return "成功!"
20

21
unstable_api()

带参数的装饰器#

1
def repeat(times):
2
    def decorator(func):
3
        def wrapper(*args, **kwargs):
4
            for _ in range(times):
5
                result = func(*args, **kwargs)
6
            return result
7
        return wrapper
8
    return decorator
9

10
@repeat(times=3)
11
def greet(name):
12
    print(f"Hello, {name}!")
13

14
greet("World")
15
# 输出:
16
# Hello, World!
17
# Hello, World!
18
# Hello, World!

结构对比：

1
普通装饰器（2层）          带参数的装饰器（3层）
2
─────────────────          ─────────────────────
3
def decorator(func):       def decorator_factory(arg):
4
    def wrapper():             def decorator(func):
5
        ...                        def wrapper():
6
    return wrapper                     ...
7
                                   return wrapper
8
                               return decorator

类装饰器#

装饰器也可以是一个类：

1
class CountCalls:
2
    def __init__(self, func):
3
        self.func = func
4
        self.count = 0
5

6
    def __call__(self, *args, **kwargs):
7
        self.count += 1
8
        print(f"{self.func.__name__} 被调用了 {self.count} 次")
9
        return self.func(*args, **kwargs)
10

11
@CountCalls
12
def say_hi():
13
    print("Hi!")
14

15
say_hi()  # say_hi 被调用了 1 次 \n Hi!
16
say_hi()  # say_hi 被调用了 2 次 \n Hi!

多个装饰器叠加#

1
@decorator1
2
@decorator2
3
@decorator3
4
def func():
5
    pass
6

7
# 等价于
8
func = decorator1(decorator2(decorator3(func)))

执行顺序： 从下往上装饰，从上往下执行

保留原函数信息#

使用 functools.wraps 保留原函数的元信息：

1
from functools import wraps
2

3
def my_decorator(func):
4
    @wraps(func)  # 保留原函数的 __name__, __doc__ 等
5
    def wrapper(*args, **kwargs):
6
        return func(*args, **kwargs)
7
    return wrapper
8

9
@my_decorator
10
def example():
11
    """这是文档字符串"""
12
    pass
13

14
print(example.__name__)  # 输出: example（而不是 wrapper）
15
print(example.__doc__)   # 输出: 这是文档字符串

总结#

使用场景	示例
日志/调试	记录函数调用信息
性能监控	计时、计数
权限控制	登录验证、角色检查
缓存	避免重复计算
重试机制	网络请求失败重试
输入验证	参数类型检查
注册机制	Flask 路由、d2l 的 `add_to_class`