Python类装饰器怎么实现?基于__call__方法的代码示例

桃夭
桃夭
发布时间:2026-11-20 | 13人浏览过
原创

本文详细讲解如何使用Python类和__call__魔术方法实现类装饰器,包括核心原理解析、不带参和带参装饰器的完整代码示例、状态保留特性以及修饰类方法时的注意事项。

在Python中,实现类装饰器的关键在于利用魔术方法 __call__。只要一个类定义了 __call__ 方法,其实例就会变成可调用对象(Callable)。当使用 @ClassName 语法修饰函数时,Python会在定义阶段把原函数传给该类的构造函数 __init__ 完成实例化,而在后续调用该函数名时,自动触发该实例的 __call__ 方法,从而在拦截入参、插入前置与后置逻辑后完成对原函数的包装增强。

一、类装饰器的核心原理与对象结构

要理解类装饰器的运作机制,首先需要明确Python中“装饰器”的语法本质。语法糖 @Decorator 本质上是一次重命名赋值:

# 使用装饰器语法糖
@MyDecorator
def my_func():
    pass

# 等价于显式实例化并重新赋值
my_func = MyDecorator(my_func)

当 MyDecorator 是一个类时,执行 MyDecorator(my_func) 会调用类的 __init__ 构造方法,返回一个 MyDecorator 的类实例。如果后续要让 my_func() 依然能像普通函数一样被括号 () 调用,这个类实例就必须实现 __call__ 方法。

Python类装饰器怎么实现?基于__call__方法的代码示例
图1:类装饰器的底层包装结构与属性引用关系

二、基础无参类装饰器的实现步骤与代码示例

编写一个基础类装饰器通常遵循以下三个步骤:

  1. 定义类并在 __init__ 中接收原函数:构造函数接收被修饰的函数对象,并将其赋值给实例属性(例如 self.func)。
  2. 在 __call__ 中实现拦截与调用:定义可变参数 *args, **kwargs 接收外部调用实参,在执行原函数前后编写拦截增强逻辑,并最终返回原函数的计算结果。
  3. 使用 @类名 修饰目标函数:完成装饰器应用。

下面是一个完整的可运行代码示例。该示例实现了一个统计函数执行耗时并记录调用次数的类装饰器:

import time
from functools import update_wrapper

class ExecutionTimer:
    def __init__(self, func):
        # 1. 保存目标函数的引用
        self.func = func
        # 2. 初始化持久状态:统计该函数被调用的总次数
        self.count = 0
        # 3. 复制被装饰函数的元信息(函数名、文档等)
        update_wrapper(self, func)

    def __call__(self, *args, **kwargs):
        self.count += 1
        start_time = time.perf_counter()
        
        # 调用原始函数
        result = self.func(*args, **kwargs)
        
        elapsed_time = time.perf_counter() - start_time
        print(f"[日志] 函数 '{self.__name__}' 第 {self.count} 次执行完成,耗时: {elapsed_time:.6f} 秒")
        return result

# 应用类装饰器
@ExecutionTimer
def calculate_sum(n):
    """计算 1 到 n 的累加和"""
    total = 0
    for i in range(1, n + 1):
        total += i
    return total

if __name__ == "__main__":
    # 第一次调用
    res1 = calculate_sum(100000)
    print(f"执行结果1: {res1}")

    # 第二次调用
    res2 = calculate_sum(500000)
    print(f"执行结果2: {res2}")

运行上述代码,控制台示例输出如下:

[日志] 函数 'calculate_sum' 第 1 次执行完成,耗时: 0.003412 秒
执行结果1: 5000050000
[日志] 函数 'calculate_sum' 第 2 次执行完成,耗时: 0.016982 秒
执行结果2: 125000250000
Python类装饰器怎么实现?基于__call__方法的代码示例
图2:类装饰器在定义时与运行时的完整生命周期流程

三、进阶实现:接收配置参数的类装饰器

很多实际场景需要装饰器支持传参,例如指定重试次数、超时阈值或环境前缀:@Retry(max_attempts=3, delay=1.0)。当装饰器本身带有参数时,语法结构发生了改变:

# 带参数的装饰器调用
@Retry(max_attempts=3)
def fetch_api():
    pass

# 等价于两层调用:
# 1. Retry(max_attempts=3) 先实例化
# 2. 调用该实例并传入 fetch_api: Retry(max_attempts=3)(fetch_api)
fetch_api = Retry(max_attempts=3)(fetch_api)

这意味着:

  • 类的 __init__ 此时接收的是装饰器的配置参数(如 max_attempts),而不是被装饰的目标函数。
  • 类的 __call__ 此时接收的是目标函数 func,并且必须返回一个真正的内层包装函数(wrapper)。

完整代码示例如下:

import time
from functools import wraps

class Retry:
    def __init__(self, max_attempts=3, delay=1.0):
        # 第一阶段:接收并存储装饰器本身的配置参数
        self.max_attempts = max_attempts
        self.delay = delay

    def __call__(self, func):
        # 第二阶段:接收目标函数 func,返回内层包装函数
        @wraps(func)
        def wrapper(*args, **kwargs):
            attempts = 0
            while attempts < self.max_attempts:
                try:
                    return func(*args, **kwargs)
                except Exception as err:
                    attempts += 1
                    print(f"[重试提示] 第 {attempts} 次调用失败: {err}")
                    if attempts >= self.max_attempts:
                        print(f"[错误] 已达到最大重试次数 {self.max_attempts},异常向外抛出")
                        raise
                    time.sleep(self.delay)
        return wrapper

# 应用带参类装饰器
@Retry(max_attempts=3, delay=0.5)
def unstable_network_request(success_after=2):
    """模拟可能失败的网络请求"""
    if not hasattr(unstable_network_request, "current_try"):
        unstable_network_request.current_try = 0
    unstable_network_request.current_try += 1
    
    if unstable_network_request.current_try < success_after:
        raise ConnectionResetError("网络连接被重置")
    return "数据抓取成功"

if __name__ == "__main__":
    result = unstable_network_request(success_after=2)
    print(f"最终响应: {result}")
Python类装饰器怎么实现?基于__call__方法的代码示例
图3:不带参与带参数类装饰器的参数传递与职责对照

四、实现类装饰器时的关键细节与注意事项

1. 函数元信息保留(保留 __name__ 与 __doc__)

当一个函数被类装饰器装饰后,其名字在底层已经变成了类实例对象。如果直接访问 func.__name__,会因为实例默认没有该属性而抛出 AttributeError。解决该问题有两种方法:

  • 对于无参类装饰器:在 __init__ 中使用 functools.update_wrapper(self, func)。
  • 对于带参类装饰器:在内层 wrapper 函数上方加上 @functools.wraps(func)。

2. 修饰类中实例方法时的“描述符陷阱”

在修饰普通独立函数时,类装饰器表现完美;但如果用基础的无参类装饰器修饰一个类内部的实例方法,运行时会出现经典报错:

TypeError: method() missing 1 required positional argument: 'self'

原因分析:当调用一个普通实例方法时,Python内部通过描述符协议(Descriptor Protocol)的 __get__ 方法自动完成方法绑定(自动将当前对象注入为首个参数 self)。而自定义的类装饰器实例如果只实现了 __call__,它并没有绑定方法的能力,导致调用时 self 无法自动传入。

解决方案:在装饰器类中同时实现 __get__ 方法,将实例方法转换为绑定方法(bound method):

import types
from functools import update_wrapper

class MethodDecorator:
    def __init__(self, func):
        self.func = func
        update_wrapper(self, func)

    def __call__(self, *args, **kwargs):
        print("[拦截] 执行方法增强逻辑")
        return self.func(*args, **kwargs)

    # 关键:实现描述符协议,支持绑定到类实例
    def __get__(self, instance, owner):
        if instance is None:
            return self
        # 将当前装饰器与调用宿主实例 instance 动态绑定
        return types.MethodType(self, instance)

class UserService:
    @MethodDecorator
    def login(self, username):
        print(f"用户 {username} 登录成功")

if __name__ == "__main__":
    service = UserService()
    service.login("admin")
提示:如果你编写的类装饰器只需修饰普通独立函数,保留 __call__ 即可;若需兼容修饰类中的实例方法,请务必实现 __get__ 描述符方法。

五、类装饰器与函数装饰器的选型对比与总结

类装饰器和传统的函数装饰器各有优势。类装饰器的最大优点在于面向对象封装性和状态管理:它能够很清晰地使用实例属性管理中间状态、缓存数据或重试记录,而无需在函数闭包中使用多层 nonlocal 变量。

对比维度 函数装饰器 (Function Decorator) 类装饰器 (Class Decorator)
实现复杂度 简单直接,多层闭包嵌套 结构清晰,依赖 __init__ 与 __call__
状态维护 依赖闭包和 nonlocal 关键字 天然支持 self.attr 实例属性维护状态
修饰类方法 无需额外处理,自动继承描述符行为 若不返回闭包,需显式实现 __get__ 协议
扩展性与继承 不具备继承与多态特性 可利用OOP特性实现基类装饰器与子类定制
Python类装饰器怎么实现?基于__call__方法的代码示例
图4:装饰器技术选型矩阵与类装饰器实施法则
相关专题:

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表