Python装饰器从入门到精通：带参数装饰器与类装饰器实战指南

11次阅读

共计 6969 个字符，预计需要花费 18 分钟才能阅读完成。

Python 装饰器是 Python 语言中一个强大且优雅的特性，它允许开发者在不修改原有函数或类定义的情况下，动态地增加或修改其功能。这不仅极大地提高了代码的复用性，也使得代码结构更加清晰，符合“开放 / 封闭原则”——对扩展开放，对修改封闭。从日志记录、性能监控、权限验证到缓存机制，装饰器在实际项目中无处不在，是每一位 Python 开发者从“会用”到“精通”的必经之路。

本文将带领你深入探索 Python 装饰器的世界，从最基础的概念出发，逐步掌握带参数装饰器的强大用法，并最终触及类装饰器这一高级主题。通过丰富的代码示例和详尽的解释，你将学会如何在实际开发中灵活运用装饰器，编写出更优雅、更高效的 Python 代码。

要理解装饰器，我们首先需要理解 Python 中的几个核心概念：函数可以作为参数传递、函数可以返回函数，以及闭包（Closure）。装饰器本质上就是一个接收一个函数作为输入，并返回一个新函数的函数。

其基本语法是使用 @ 符号，放置在被装饰函数定义的前一行。

import functools

def simple_logger(func):
    """一个简单的日志装饰器"""
    @functools.wraps(func) # 使用 functools.wraps 保留原函数的元信息
    def wrapper(*args, **kwargs):
        print(f"INFO: Calling function'{func.__name__}'with args: {args}, kwargs: {kwargs}")
        result = func(*args, **kwargs)
        print(f"INFO: Function'{func.__name__}'finished. Result: {result}")
        return result
    return wrapper

@simple_logger
def add(a, b):
    """一个执行加法运算的函数"""
    return a + b

@simple_logger
def multiply(x, y):
    """一个执行乘法运算的函数"""
    return x * y

# 调用被装饰的函数
print("--- 调用 add 函数 ---")
add_result = add(10, 20)
print(f"Add result: {add_result}n")

print("--- 调用 multiply 函数 ---")
multiply_result = multiply(x=5, y=6)
print(f"Multiply result: {multiply_result}n")

在上面的例子中：

simple_logger 是一个装饰器函数，它接收一个函数 func 作为参数。
wrapper 是 simple_logger 内部定义的一个内层函数，它会封装 func 的调用。
@simple_logger 等同于 add = simple_logger(add)。
functools.wraps(func) 是一个非常重要的辅助装饰器。它会将被装饰函数 func 的元信息（如 __name__, __doc__, __module__ 等）复制到 wrapper 函数上。如果不使用它，当你查看 add 函数的 __name__ 或 __doc__ 时，会得到 wrapper 的信息，而不是 add 本身的信息，这会给调试和文档生成带来困扰。

简单的装饰器足以满足许多场景，但有时我们希望装饰器本身也能接收参数，以便更灵活地配置其行为。例如，一个日志装饰器可能需要指定日志级别，或者一个权限检查装饰器需要知道用户所需的角色。这时，我们就需要带参数的装饰器。

带参数的装饰器实现起来会稍微复杂一些，因为它涉及三层嵌套函数：最外层接收装饰器参数，中间层接收被装饰函数，最内层才是实际执行增强逻辑的 wrapper 函数。

import functools

def permission_required(role):
    """
    一个带参数的权限检查装饰器
    只有拥有指定角色的用户才能访问被装饰的函数
    """
    def decorator(func):
        @functools.wraps(func)
        def wrapper(user, *args, **kwargs):
            if user.get('role') == role:
                print(f"SUCCESS: User'{user.get('name')}'with role'{user.get('role')}'has permission to call'{func.__name__}'.")
                return func(user, *args, **kwargs)
            else:
                print(f"ACCESS DENIED: User'{user.get('name')}'with role'{user.get('role')}'does not have'{role}'permission for'{func.__name__}'.")
                return None # 或者抛出权限异常
        return wrapper
    return decorator

# 模拟用户数据
admin_user = {'name': 'Alice', 'role': 'admin'}
guest_user = {'name': 'Bob', 'role': 'guest'}

@permission_required('admin')
def delete_data(user, data_id):
    """只有管理员才能删除数据"""
    print(f"Deleting data with ID: {data_id} by {user['name']}.")
    return True

@permission_required('guest')
def view_page(user, page_name):
    """游客及以上权限都能查看页面"""
    print(f"Viewing page'{page_name}'by {user['name']}.")
    return True

# 测试带参数装饰器
print("--- 测试 delete_data 函数 ---")
delete_data(admin_user, 123)
delete_data(guest_user, 456)
print("n--- 测试 view_page 函数 ---")
view_page(admin_user, 'dashboard')
view_page(guest_user, 'public_page')

实现原理分析：

permission_required(role): 这是最外层函数，它接收装饰器的参数 role（例如 'admin'）。这个函数并没有直接返回 wrapper，而是返回了 decorator 函数。
decorator(func): 这是中间层函数，它接收被装饰的函数 func（例如 delete_data）。这个函数会返回真正的 wrapper 函数。
*`wrapper(user, args, kwargs)`: 这是最内层函数，它就是实际替换 delete_data 的新函数。它包含了权限检查的逻辑，并决定是否调用原始的 func。

当你在函数上方写 @permission_required('admin') 时，Python 的执行流程是这样的：

首先调用 permission_required('admin')，它会返回 decorator 函数。
然后，这个返回的 decorator 函数会被用来装饰 delete_data，即 delete_data = decorator(delete_data)。
最终，delete_data 变量指向的就是 wrapper 函数。

这样，每次调用 delete_data 时，实际上都是在调用 wrapper 函数，从而执行了权限检查逻辑。

除了使用函数作为装饰器，Python 也允许我们使用类作为装饰器。类装饰器提供了更强大的功能，例如可以维护状态，或者在初始化时执行更复杂的逻辑。

类作为装饰器主要有两种形式：

类实例作为装饰器 ：通过实现 __call__ 方法，使类的实例可以像函数一样被调用。
装饰一个类 ：将装饰器应用到整个类定义上，而不是单个方法。

当一个类被用作装饰器时，它的实例将取代被装饰的函数。因此，这个类的实例必须能够像函数一样被调用，这意味着它需要实现 __call__ 方法。

import functools
import time

class TimerDecorator:
    """一个使用类实现的统计函数执行时间的装饰器"""
    def __init__(self, message="Function'{func_name}'executed in {time:.4f} seconds."):
        self.message = message

    def __call__(self, func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            start_time = time.time()
            result = func(*args, **kwargs)
            end_time = time.time()
            execution_time = end_time - start_time
            print(self.message.format(func_name=func.__name__, time=execution_time))
            return result
        return wrapper

@TimerDecorator(message="性能报告：{func_name} 耗时 {time:.2f} 秒。")
def complex_calculation(n):
    """模拟一个耗时计算"""
    print(f"Starting complex calculation for n={n}...")
    time.sleep(n / 10) # 模拟计算耗时
    print(f"Finished complex calculation for n={n}.")
    return n * n

@TimerDecorator() # 使用默认消息
def another_task():
    """另一个任务"""
    time.sleep(0.05)
    return "Task Done"

print("--- 测试 complex_calculation 函数 ---")
complex_calculation(3)
complex_calculation(1)
print("n--- 测试 another_task 函数 ---")
another_task()

实现原理分析：

TimerDecorator 类 :
- __init__(self, message): 构造函数，接收装饰器参数（例如 message）。当你在 @TimerDecorator(...) 定义时，这个 __init__ 方法会被调用，创建一个 TimerDecorator 的实例。
- __call__(self, func): 这个方法使得 TimerDecorator 的实例可以像函数一样被调用。它接收被装饰的函数 func，然后返回一个 wrapper 函数。这里的 self 允许 wrapper 访问 TimerDecorator 实例的状态（例如 self.message）。

当 @TimerDecorator(message="...") 应用到 complex_calculation 上时：

首先，TimerDecorator(message="...") 被调用，创建了一个 TimerDecorator 实例。这个实例的 message 属性被设置为传入的值。
然后，这个实例被作为装饰器应用到 complex_calculation 上，即 complex_calculation = instance_of_TimerDecorator(complex_calculation)。
这时，实例的 __call__ 方法被调用，接收 complex_calculation 作为参数 func。
__call__ 方法返回了 wrapper 函数。最终，complex_calculation 变量指向的就是这个 wrapper 函数。

类装饰器也可以直接应用到整个类上，以修改类的行为，例如为类添加属性、方法，或者改变其创建实例的方式（通过元类）。

def add_method_to_class(cls):
    """一个装饰类的装饰器，为类添加一个新方法"""
    def greet(self):
        return f"Hello from {self.__class__.__name__}!"

    cls.greet = greet
    cls.added_attribute = "This attribute was added by a decorator."
    return cls

@add_method_to_class
class MyClass:
    def __init__(self, name):
        self.name = name

    def original_method(self):
        return f"Original method of {self.name}"

print("--- 测试装饰类 ---")
obj = MyClass("DecoratorTest")
print(obj.original_method())
print(obj.greet()) # 调用装饰器添加的方法
print(obj.added_attribute) # 访问装饰器添加的属性

# 验证 MyClass 是否被修改
print(f"MyClass has attribute'greet': {'greet'in dir(MyClass)}")
print(f"MyClass has attribute'added_attribute': {'added_attribute'in dir(MyClass)}")

在这个例子中，add_method_to_class 装饰器接收一个类 cls 作为参数，然后直接修改这个类（添加了一个 greet 方法和 added_attribute 属性），最后返回修改后的类。这种模式常用于框架中，例如 ORM 框架可能会使用类装饰器来注册模型，或者为模型自动生成一些数据库操作方法。

Python 装饰器的应用非常广泛，以下是一些常见的实战场景：

日志记录和监控 ：记录函数调用、参数、返回值、执行时间等信息，便于调试和性能分析。
权限管理和认证 ：在视图函数或业务逻辑函数前检查用户是否具有相应权限。
缓存机制 ：将被装饰函数的返回结果缓存起来，当下次以相同参数调用时直接返回缓存结果，避免重复计算。
重试机制 ：当函数执行失败时（例如网络请求），自动进行多次重试。
输入验证 ：对函数的输入参数进行校验，确保数据符合预期。
数据序列化 / 反序列化 ：在数据传输前后自动进行格式转换。
性能优化 ：如上面 TimerDecorator 所示，精确测量代码块的执行时间。
框架集成 ：Web 框架（如 Flask、Django）中的路由定义、中间件、信号处理等都大量使用装饰器。

在使用装饰器时，遵循一些最佳实践可以帮助你避免潜在问题并提高代码质量：

始终使用 functools.wraps：这可以确保被装饰函数的元信息（如函数名、文档字符串、模块路径等）得以保留，对于调试和内省（introspection）至关重要。
保持装饰器职责单一 ：一个装饰器最好只做一件事。如果需要多个功能，可以链式使用多个装饰器。
处理装饰器链 ：当多个装饰器作用于同一个函数时，它们的执行顺序是从离函数最近的装饰器开始，由内向外依次执行。例如：
```
@decorator_outer
@decorator_inner
def my_func():
    pass
```
这相当于 my_func = decorator_outer(decorator_inner(my_func))。
异常处理 ：在 wrapper 函数内部，要妥善处理被装饰函数可能抛出的异常。根据需求，可以选择捕获、重新抛出或转换为特定格式的异常。
可读性 ：装饰器虽然强大，但过度使用或编写过于复杂的装饰器会降低代码可读性。确保你的装饰器命名清晰，功能明确。
无参数装饰器的简化 ：如果你的带参数装饰器在不接收参数时（例如 @my_decorator 而非 @my_decorator()）也能工作，可以对其进行优化，使其能够兼容两种调用方式。但这会增加代码的复杂性，通常在需要极致灵活性时才考虑。