Python类装饰器怎么实现?基于__call__方法的代码示例
本文详细讲解如何使用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__ 方法。
二、基础无参类装饰器的实现步骤与代码示例
编写一个基础类装饰器通常遵循以下三个步骤:
- 定义类并在
__init__中接收原函数:构造函数接收被修饰的函数对象,并将其赋值给实例属性(例如self.func)。 - 在
__call__中实现拦截与调用:定义可变参数*args, **kwargs接收外部调用实参,在执行原函数前后编写拦截增强逻辑,并最终返回原函数的计算结果。 - 使用
@类名修饰目标函数:完成装饰器应用。
下面是一个完整的可运行代码示例。该示例实现了一个统计函数执行耗时并记录调用次数的类装饰器:
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
三、进阶实现:接收配置参数的类装饰器
很多实际场景需要装饰器支持传参,例如指定重试次数、超时阈值或环境前缀:@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}")
四、实现类装饰器时的关键细节与注意事项
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特性实现基类装饰器与子类定制 |
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









