python装饰器怎么定义函数
本文详细讲解在Python中如何定义装饰器函数。从高阶函数与闭包基本结构出发,拆解定义通用装饰器的四个关键步骤,涵盖参数支持、返回值传递、元数据保留以及带参数装饰器的三层函数嵌套实现。
一、装饰器的本质与基本定义结构
在 Python 中,函数是一等公民(First-class Object)。这意味着函数可以像普通变量一样被传递、作为其他函数的返回值,或者在另一个函数体内动态定义。理解这一特性是掌握装饰器定义的关键。
从实现层面看,装饰器是一个接收函数对象作为输入参数,并返回一个替换函数的闭包结构。当我们在某个目标函数上方使用 @my_decorator 语法糖时,Python 解释器在加载该函数时,会自动将其转化为赋值语句:func = my_decorator(func)。因此,定义装饰器就是编写一个能够完成这套“接收原函数、包裹额外操作、返回新函数”逻辑的高阶函数。
下面是一个最基础的装饰器定义示例,演示如何定义一个在函数执行前后打印提示日志的装饰器函数:
# 定义装饰器函数:外层接收原函数对象 func
def log_decorator(func):
# 内层定义包装函数 wrapper
def wrapper():
print("[执行前] 准备启动目标函数")
func() # 调用原函数
print("[执行后] 目标函数执行完毕")
# 将内层函数对象返回(注意不能加括号)
return wrapper
# 使用 @ 语法糖修饰目标函数
@log_decorator
def greet():
print("你好,Python!")
# 调用被装饰后的函数
greet()
你好,Python!
[执行后] 目标函数执行完毕
当执行 greet() 时,实际运行的并不是原本定义的 greet 函数体,而是 log_decorator 内部返回的 wrapper 函数。原有的 greet 逻辑被无缝嵌入在了 wrapper 内部。
二、定义通用装饰器函数的四个核心步骤
实际开发中,被装饰的函数往往具有不同的参数签名(例如无参、多参、包含默认值或关键字参数),并且通常有明确的返回值。为了让定义的装饰器具备良好的通用性,必须遵循标准的四个定义步骤。
-
步骤一:定义外层接收函数
编写外层函数def decorator_name(func):,入参明确声明为func,用于接收被装饰函数的引用。 -
步骤二:定义内层通用包装函数
在函数体内部定义def wrapper(*args, **kwargs):。使用可变位置参数*args和可变关键字参数**kwargs,使其能够透明接收原函数的任意入参。 -
步骤三:编写增强逻辑并捕获返回值
在wrapper内部编写前置或后置扩展逻辑,并通过result = func(*args, **kwargs)执行原函数。这一步非常关键:必须保存原函数的返回值,并在wrapper结束时return result。 -
步骤四:返回包装函数对象
在外层函数的最后一行,使用return wrapper返回包装函数的引用。注意不能写成return wrapper(),否则会在代码加载阶段立刻触发执行,而不是在后续调用时执行。
结合上述四步,下面定义一个能够测量执行耗时、支持任意参数与返回值的标准装饰器函数:
import time
def timer(func):
"""标准通用耗时统计装饰器"""
def wrapper(*args, **kwargs):
start_time = time.perf_counter()
# 调用原函数并保留返回值
result = func(*args, **kwargs)
elapsed = time.perf_counter() - start_time
print(f"[耗时统计] 函数 '{func.__name__}' 执行用时: {elapsed:.6f} 秒")
# 将原函数的真实计算结果返回给调用方
return result
return wrapper
# 修饰带有参数和返回值的计算函数
@timer
def calculate_sum(n):
total = sum(i for i in range(1, n + 1))
return total
# 执行函数并获取结果
res = calculate_sum(500000)
print(f"最终计算结果: {res}")
最终计算结果: 125000250000
三、函数调用拦截链路与执行机制
为了加深对装饰器内部工作过程的理解,我们可以对比函数在被装饰前后的调用链路差异。在未经装饰时,调用方发起的请求直接直达函数执行体并返回;而在经过装饰器包装后,调用链路被 wrapper 完整拦截。
从图中可以看出,wrapper 作为中间代理层,拥有完全的控制权:
- 前置控制:可以在调用原函数前校验参数、验证用户权限或读取缓存。如果条件不满足,甚至可以提前抛出异常或直接返回,阻断原函数的执行。
- 原函数桥接:原函数在
wrapper内部被正确传参调用,确保核心业务不受外部侵入。 - 后置加工:原函数的计算结果先返回给
wrapper,包装器可以对结果进行格式转换、加密或者写入日志,然后再交付给最外层的真实调用方。
四、关键细节:使用 functools.wraps 保留函数元信息
在默认情况下,经过装饰器修饰后的函数,其本质已经被替换成了 wrapper。这会导致一个严重的副作用:原函数的名称(__name__)、文档注释(__doc__)以及签名(__annotations__)会被内层 wrapper 的信息覆盖。
这不仅会给调试带来困扰,还可能破坏反射机制或依赖函数签名的第三方框架(如 FastAPI、Sphinx 文档生成器)。Python 提供了标准库模块 functools.wraps 来解决这个问题。
def wrapper 上方添加 @functools.wraps(func)。它会将原函数的属性自动复制到包装函数上。
import functools
def auth_check(func):
@functools.wraps(func) # 复制并保留原函数元信息
def wrapper(*args, **kwargs):
# 权限校验逻辑
return func(*args, **kwargs)
return wrapper
@auth_check
def export_report(report_id):
"""根据报表 ID 导出财务报表数据"""
return f"报表 {report_id} 导出成功"
# 验证函数元信息是否完好保留
print(f"函数名: {export_report.__name__}")
print(f"函数文档: {export_report.__doc__}")
函数文档: 根据报表 ID 导出财务报表数据
如果去掉 @functools.wraps(func),输出的函数名将变为 wrapper,函数文档将显示为空(或 wrapper 自身的文档)。因此,将 @wraps 作为定义装饰器的标配,是编写高质量 Python 代码的重要习惯。
五、进阶场景:定义接收参数的装饰器函数
很多时候,我们需要让装饰器自身也能接收配置参数。例如:@retry(max_attempts=3) 或 @rate_limit(seconds=60)。很多初学者在此时容易陷入困惑,因为常规的双层函数结构只能接收目标函数 func,无法再容纳额外的配置项。
要定义接收参数的装饰器,需要采用三层函数嵌套模式(也称为“装饰器工厂”):
三层函数的职责划分如下:
- 最外层(工厂函数):接收装饰器所需的自定义参数(如重试次数、超时限制等),并返回中层的标准装饰器。
- 中间层(标准装饰器):接收被装饰的目标函数对象
func,并返回最内层的包装函数。 - 最内层(包装函数):通过闭包同时访问最外层的配置参数与中间层的原函数,执行增强逻辑并调用原函数。
以下是定义一个支持指定重复执行次数的带参装饰器实现代码:
import functools
# 第 1 层:装饰器工厂,接收自定义配置参数
def repeat(num_times=2):
# 第 2 层:标准装饰器,接收目标函数
def decorator(func):
# 第 3 层:包装函数,接收目标函数调用时的实参
@functools.wraps(func)
def wrapper(*args, **kwargs):
last_result = None
for i in range(1, num_times + 1):
print(f"[执行轮次 {i}/{num_times}] 调用 {func.__name__}")
last_result = func(*args, **kwargs)
return last_result
return wrapper
return decorator
# 使用带参数的装饰器
@repeat(num_times=3)
def send_ping(host):
print(f"正在向主机 {host} 发送心跳包...")
return "PONG"
status = send_ping("192.168.1.1")
print(f"最终心跳响应: {status}")
正在向主机 192.168.1.1 发送心跳包...
[执行轮次 2/3] 调用 send_ping
正在向主机 192.168.1.1 发送心跳包...
[执行轮次 3/3] 调用 send_ping
正在向主机 192.168.1.1 发送心跳包...
最终心跳响应: PONG
六、常见定义错误排查与最佳实践总结
在编写装饰器函数时,如果对闭包引用和执行时机理解不透彻,很容易写出不易察觉的逻辑缺陷。以下总结了定义装饰器时的核心避坑检查清单。
常见典型错误排查
-
错误一:外层函数错误地写成
return wrapper()
外层函数的目的是返回包装函数对象本身,供后续调用。如果多加了小括号,Python 会在加载代码定义函数时立刻执行一次wrapper,并将其实际返回值(通常是 None)赋给目标函数,导致后续调用时报TypeError: 'NoneType' object is not callable错误。 -
错误二:内层
wrapper遗漏了return result
如果在包装函数内执行了func(*args, **kwargs),但没有将结果 return 出来,原函数的调用方将永远只能拿到None。无论原函数计算出了什么,都会被包装器静默吞没。 -
错误三:没有使用
*args, **kwargs导致参数签名受限
如果包装函数定义为def wrapper(a, b):,那么该装饰器就只能用于修饰恰好接收两个位置参数的函数。换成其他参数形式就会报错。始终使用*args, **kwargs能够确保装饰器通用健壮。 -
错误四:带参装饰器少写了一层函数
当需要使用@my_dec(arg=1)这种形式时,如果依然只写两层函数,Python 会把参数误当作目标函数传给第一层,从而导致原函数根本没有被接收。带参装饰器必须有三层嵌套。
掌握了上述定义规范、通用参数写法、元数据保护以及三层嵌套结构,读者就能够根据项目需要,清晰、规范地定义出各种功能稳定、代码干净的 Python 装饰器函数。
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









