Python 装饰器

Python 装饰器（Decorator）是一种高级语法，用于在不修改原函数代码的前提下，动态扩展函数或类的功能。它本质上是一个接收函数 / 类作为参数，并返回新函数 / 类的可调用对象，是函数式编程的典型应用。

1、核心原理

装饰器的核心依赖于 Python 的两个特性：

1. 函数：函数可以作为参数传递、作为返回值返回、赋值给变量。
2. 闭包：嵌套函数可以访问外层函数的变量和参数（即使外层函数已执行完毕）。

1.1 装饰器的基本结构

一个最简单的装饰器由外层函数（接收原函数） 和内层函数（包装原函数） 组成，最终返回内层函数：

def decorator(func):  # 外层函数：接收原函数作为参数
    def wrapper(*args, **kwargs):  # 内层函数：包装原函数（*args, **kwargs 兼容任意参数）
        print("装饰器逻辑：执行前")  # 扩展功能（执行前）
        result = func(*args, **kwargs)  # 调用原函数
        print("装饰器逻辑：执行后")  # 扩展功能（执行后）
        return result  # 返回原函数结果
    return wrapper  # 返回内层函数

# 使用装饰器（语法糖：@装饰器名）
@decorator
def target_func():
    print("原函数逻辑")

# 调用被装饰的函数
target_func()

执行结果：

装饰器逻辑：执行前
原函数逻辑
装饰器逻辑：执行后

说明：@decorator 等价于 target_func = decorator(target_func)，即原函数被装饰器返回的 wrapper 函数替换。

1.2 装饰器的执行时机

装饰器在模块加载时（导入时） 就会执行，而非函数调用时。例如：

print("模块加载中...")

def decorator(func):
    print(f"装饰器执行：装饰 {func.__name__}")
    return func

@decorator
def func1():
    pass

@decorator
def func2():
    pass

print("模块加载完成")

执行结果（先执行装饰器，再执行后续代码）：

模块加载中...
装饰器执行：装饰 func1
装饰器执行：装饰 func2
模块加载完成

2、进阶用法

2.1 带参数的装饰器

若需要给装饰器传递参数（如日志的级别、缓存的过期时间），需在外层再套一层 “参数接收函数”：

def log_decorator(level):  # 最外层：接收装饰器参数
    def decorator(func):  # 中间层：接收原函数
        def wrapper(*args, **kwargs):
            print(f"[{level}] 函数 {func.__name__} 开始执行")  # 使用装饰器参数
            result = func(*args, **kwargs)
            print(f"[{level}] 函数 {func.__name__} 执行结束")
            return result
        return wrapper
    return decorator

# 使用带参数的装饰器
@log_decorator(level="INFO")
def add(a, b):
    return a + b

print(add(1, 2))

执行结果：

[INFO] 函数 add 开始执行
[INFO] 函数 add 执行结束
3

2.2 类装饰器

类也可以作为装饰器，核心是实现 __call__ 方法（使类实例可调用）：

class TimerDecorator:
    def __init__(self, func):  # 初始化时接收原函数
        self.func = func

    def __call__(self, *args, **kwargs):  # 调用时执行装饰逻辑
        import time
        start = time.time()
        result = self.func(*args, **kwargs)  # 调用原函数
        end = time.time()
        print(f"函数 {self.func.__name__} 执行耗时：{end - start:.2f}s")
        return result

# 使用类装饰器
@TimerDecorator
def slow_func(seconds):
    import time
    time.sleep(seconds)  # 模拟耗时操作

slow_func(1)  # 执行被装饰的函数

执行结果：

函数 slow_func 执行耗时：1.00s

2.3 装饰器的嵌套

多个装饰器可以叠加使用，嵌套装饰器的核心是装饰顺序和调用顺序的区别，理解这两个顺序是掌握嵌套装饰器的关键。

# 定义两个装饰器
def decorator_a(func):
    def wrapper(*args, **kwargs):
        print("装饰器 A 开始")
        result = func(*args, **kwargs)
        print("装饰器 A 结束")
        return result
    return wrapper

def decorator_b(func):
    def wrapper(*args, **kwargs):
        print("装饰器 B 开始")
        result = func(*args, **kwargs)
        print("装饰器 B 结束")
        return result
    return wrapper

# 嵌套应用装饰器
@decorator_a
@decorator_b
def target():
    print("执行目标函数")

# 调用目标函数
target()

执行结果：

装饰器 A 开始
装饰器 B 开始
执行目标函数
装饰器 B 结束
装饰器 A 结束

2.3.1 装饰顺序：从下到上（“包裹顺序”）

装饰器的应用过程发生在函数定义时，本质是对函数的 “层层包裹”。对于上面的例子：

@decorator_a
@decorator_b
def target(): ...

等价于手动执行：

# 第一步：用 decorator_b 装饰原始 target，得到新函数 wrapper_b
wrapper_b = decorator_b(target)
# 第二步：用 decorator_a 装饰 wrapper_b，得到最终函数 wrapper_a
target = decorator_a(wrapper_b)

即：先执行下方的装饰器，再执行上方的装饰器，最终得到的 target 是最外层装饰器（decorator_a）返回的 wrapper 函数。

2.3.2 调用顺序：从外到内（“执行顺序”）

当调用被装饰的函数（如 target()）时，执行流程是从最外层装饰器的 wrapper 开始，逐层进入内层，最后执行原始函数，再逐层返回。

以上面的 target() 调用为例，执行流程拆解：

1. 调用 target() 实际是调用 decorator_a 返回的 wrapper_a；
2. wrapper_a 中先执行自身逻辑（print("装饰器 A 开始")），然后调用 func（此时 func 是 decorator_b 返回的 wrapper_b）；
3. wrapper_b 中先执行自身逻辑（print("装饰器 B 开始")），然后调用 func（此时 func 是原始 target 函数）；
4. 执行原始 target 函数（print("执行目标函数")）；
5. 原始函数执行完毕，返回结果给 wrapper_b，wrapper_b 执行后续逻辑（print("装饰器 B 结束")）；
6. wrapper_b 执行完毕，返回结果给 wrapper_a，wrapper_a 执行后续逻辑（print("装饰器 A 结束")）；
7. 最终结果返回给调用者。

简言之：调用时先执行外层装饰器的 “前置逻辑”，再执行内层装饰器的 “前置逻辑”，然后是原始函数，最后按相反顺序执行各装饰器的 “后置逻辑”。

2.4 保留原函数元信息

装饰器默认会覆盖原函数的元信息（如 __name__、__doc__），需使用 functools.wraps 修复：

import functools

def bad_decorator(func):
    def wrapper():
        func()
    return wrapper  # 未保留元信息

def good_decorator(func):
    @functools.wraps(func)  # 保留原函数元信息
    def wrapper():
        func()
    return wrapper

@bad_decorator
def f1():
    """f1 的文档字符串"""
    pass

@good_decorator
def f2():
    """f2 的文档字符串"""
    pass

print(f1.__name__)  # 输出：wrapper（错误）
print(f1.__doc__)   # 输出：None（错误）
print(f2.__name__)  # 输出：f2（正确）
print(f2.__doc__)   # 输出：f2 的文档字符串（正确）

2.5 装饰类的方法

2.5.1 装饰实例方法

实例方法是类中最常见的方法，第一个参数默认是 self（指向实例本身）。装饰实例方法时，装饰器需要正确传递 self 及其他参数。

用装饰器记录实例方法的调用日志

import functools

# 定义装饰器：记录方法调用的参数、返回值
def log_instance_method(func):
    @functools.wraps(func)  # 保留原方法的元信息（如 __name__、__doc__）
    def wrapper(self, *args, **kwargs):
        # 打印实例信息、方法名、参数
        print(f"[日志] 实例 {self} 调用方法 {func.__name__}，参数：{args}，关键字参数：{kwargs}")
        # 调用原始方法（注意传递 self）
        result = func(self, *args, **kwargs)
        # 打印返回值
        print(f"[日志] 方法 {func.__name__} 返回：{result}")
        return result
    return wrapper

# 定义类，用装饰器装饰实例方法
class User:
    def __init__(self, name):
        self.name = name  # 实例属性

    # 用装饰器装饰实例方法
    @log_instance_method
    def greet(self, prefix):
        """向用户打招呼"""
        return f"{prefix}，我是 {self.name}"

# 测试
user = User("Alice")
user.greet("你好")

执行结果：

[日志] 实例 <__main__.User object at 0x102b5a4d0> 调用方法 greet，参数：('你好',)，关键字参数：{}
[日志] 方法 greet 返回：你好，我是 Alice

关键说明：

• 装饰器的 wrapper 函数第一个参数必须是 self（或用 *args 兼容），否则无法传递实例引用；
• func(self, *args, **kwargs) 确保原始方法能正确接收 self 及其他参数；
• functools.wraps(func) 保留原方法的元信息（如 user.greet.__name__ 仍为 greet，而非 wrapper）。

2.5.2 装饰类方法

类方法用 @classmethod 装饰，第一个参数默认是 cls（指向类本身）。装饰类方法时，需注意装饰器与 @classmethod 的顺序，以及 cls 参数的传递。

用装饰器验证类方法的参数

import functools

# 定义装饰器：检查类方法的参数是否为正数
def validate_positive(func):
    @functools.wraps(func)
    def wrapper(cls, *args, **kwargs):
        # 检查所有位置参数是否为正数
        for arg in args:
            if not isinstance(arg, (int, float)) or arg <= 0:
                raise ValueError(f"类方法 {func.__name__} 接收无效参数：{arg}（必须为正数）")
        # 调用原始类方法（传递 cls）
        return func(cls, *args, **kwargs)
    return wrapper

# 定义类，用装饰器装饰类方法
class MathUtils:
    # 注意装饰器顺序：先应用功能装饰器，再用 @classmethod（从下到上装饰）
    @classmethod
    @validate_positive
    def multiply(cls, a, b):
        """计算两个正数的乘积（类方法）"""
        return a * b

# 测试
print(MathUtils.multiply(3, 4))  # 正常调用：输出 12
MathUtils.multiply(-2, 5)  # 触发验证失败：ValueError

执行结果：

12
ValueError: 类方法 multiply 接收无效参数：-2（必须为正数）

关键说明：

• 装饰器顺序：@classmethod 必须放在功能装饰器的下方（即先被装饰），因为 @classmethod 会将方法转换为类方法，功能装饰器需要装饰转换后的方法；
• wrapper 函数第一个参数是 cls，确保原始类方法能接收类引用；
• 类方法操作的是类本身（如 cls.__name__），而非实例，装饰器可基于类属性做校验。

2.5.3 装饰静态方法

静态方法用 @staticmethod 装饰，无默认参数（与普通函数类似）。装饰静态方法时，处理逻辑与装饰普通函数一致。

用装饰器记录静态方法的执行时间

import functools
import time

# 定义装饰器：记录方法执行时间
def timer(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.time()
        result = func(*args, **kwargs)  # 静态方法无 self/cls，直接传递参数
        end = time.time()
        print(f"[计时] 静态方法 {func.__name__} 执行耗时：{end - start:.4f} 秒")
        return result
    return wrapper

# 定义类，用装饰器装饰静态方法
class StringUtils:
    # 装饰器顺序：@staticmethod 在下，功能装饰器在上
    @staticmethod
    @timer
    def reverse(s):
        """反转字符串（静态方法）"""
        time.sleep(0.1)  # 模拟耗时操作
        return s[::-1]

# 测试
print(StringUtils.reverse("hello"))  # 输出：olleh

执行结果：

[计时] 静态方法 reverse 执行耗时：0.1002 秒
olleh

关键说明：

• 静态方法无 self 或 cls，装饰器的 wrapper 函数直接用 *args, **kwargs 接收参数即可；
• 装饰器顺序与类方法类似：@staticmethod 在下，功能装饰器在上，确保装饰的是静态方法。

3、装饰器的应用场景

1. 日志记录：自动记录函数的调用参数、返回值、执行时间。

2. 权限验证：调用函数前检查用户权限（如登录状态）。

   def login_required(func):
       @functools.wraps(func)
       def wrapper(user, *args, **kwargs):
           if not user.is_login:
               raise PermissionError("请先登录")
           return func(user, *args, **kwargs)
       return wrapper
   
   @login_required
   def pay(user, amount):
       print(f"{user.name} 支付 {amount} 元")
   

3. 缓存结果：缓存函数的计算结果，避免重复计算。

   from functools import lru_cache
   
   @lru_cache(maxsize=128)
   def expensive_calculation(x, y):
       # 模拟耗时计算
       time.sleep(1)
       return x * y + x**2 + y**2
   # 第一次调用会计算
   result1 = expensive_calculation(10, 20)
   # 第二次相同参数的调用会直接从缓存返回
   result2 = expensive_calculation(10, 20)
   

4. 异常处理：统一捕获函数执行中的异常，避免程序崩溃。

   import functools
   from typing import Callable, Any, Type, Tuple, Optional
   
   def exception_handler(
       exceptions: Tuple[Type[Exception], ...] = (Exception,),
       default: Any = None,
       re_raise: bool = False,
       error_msg: Optional[str] = None
   ) -> Callable:
       """
       异常处理装饰器：捕获指定异常并统一处理
       
       :param exceptions: 需要捕获的异常类型（元组），默认捕获所有Exception
       :param default: 异常发生时返回的默认值（若re_raise为False）
       :param re_raise: 捕获异常后是否重新抛出，默认False（不抛出）
       :param error_msg: 自定义错误提示信息，默认为异常自带消息
       :return: 装饰后的函数
       """
       def decorator(func: Callable) -> Callable:
           @functools.wraps(func)  # 保留原函数元信息
           def wrapper(*args: Any, **kwargs: Any) -> Any:
               try:
                   # 执行原函数
                   return func(*args, **kwargs)
               except exceptions as e:
                   # 若需要重新抛出异常，交给上层处理
                   if re_raise:
                       raise  # 保持原异常类型和堆栈
                   
                   # 否则返回默认值
                   return default
           return wrapper
       return decorator
   
   # 示例1：捕获ValueError和TypeError，返回默认值
   @exception_handler(
       exceptions=(ValueError, TypeError),
       default=-1,
       error_msg="数值转换失败"
   )
   def parse_number(s: str) -> int:
       """将字符串转换为整数"""
       return int(s)
   
   
   # 示例2：捕获IOError，重新抛出异常（让调用者处理）
   @exception_handler(
       exceptions=(IOError,),
       re_raise=True,
       error_msg="文件读取失败"
   )
   def read_file(path: str) -> str:
       """读取文件内容"""
       with open(path, "r") as f:
           return f.read()