python装饰器怎么定义函数

落日邮差
落日邮差
发布时间:2026-11-20| 3人浏览过
原创

本文详细讲解在Python中如何定义装饰器函数。从高阶函数与闭包基本结构出发,拆解定义通用装饰器的四个关键步骤,涵盖参数支持、返回值传递、元数据保留以及带参数装饰器的三层函数嵌套实现。

在 Python 中,定义一个装饰器本质上是定义一个高阶函数:该函数接收被装饰的目标函数作为参数,在其内部定义一个用于扩展增强行为的包装函数(wrapper),最后将这个包装函数对象直接作为结果返回。本文将系统讲解定义基础装饰器函数的标准结构、处理任意参数与返回值的方法、保留原函数元信息的关键技巧,以及如何定义支持接收自身配置参数的进阶装饰器。
python装饰器怎么定义函数
图 1:Python 装饰器函数定义概览与核心模式

一、装饰器的本质与基本定义结构

在 Python 中,函数是一等公民(First-class Object)。这意味着函数可以像普通变量一样被传递、作为其他函数的返回值,或者在另一个函数体内动态定义。理解这一特性是掌握装饰器定义的关键。

从实现层面看,装饰器是一个接收函数对象作为输入参数,并返回一个替换函数的闭包结构。当我们在某个目标函数上方使用 @my_decorator 语法糖时,Python 解释器在加载该函数时,会自动将其转化为赋值语句:func = my_decorator(func)。因此,定义装饰器就是编写一个能够完成这套“接收原函数、包裹额外操作、返回新函数”逻辑的高阶函数。

python装饰器怎么定义函数
图 2:Python 装饰器闭包与语法糖转换原理图

下面是一个最基础的装饰器定义示例,演示如何定义一个在函数执行前后打印提示日志的装饰器函数:

# 定义装饰器函数:外层接收原函数对象 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 内部。

二、定义通用装饰器函数的四个核心步骤

实际开发中,被装饰的函数往往具有不同的参数签名(例如无参、多参、包含默认值或关键字参数),并且通常有明确的返回值。为了让定义的装饰器具备良好的通用性,必须遵循标准的四个定义步骤。

python装饰器怎么定义函数
图 3:定义 Python 装饰器函数的标准四步流程
  1. 步骤一:定义外层接收函数
    编写外层函数 def decorator_name(func):,入参明确声明为 func,用于接收被装饰函数的引用。
  2. 步骤二:定义内层通用包装函数
    在函数体内部定义 def wrapper(*args, **kwargs):。使用可变位置参数 *args 和可变关键字参数 **kwargs,使其能够透明接收原函数的任意入参。
  3. 步骤三:编写增强逻辑并捕获返回值
    在 wrapper 内部编写前置或后置扩展逻辑,并通过 result = func(*args, **kwargs) 执行原函数。这一步非常关键:必须保存原函数的返回值,并在 wrapper 结束时 return result。
  4. 步骤四:返回包装函数对象
    在外层函数的最后一行,使用 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}")
示例运行输出
[耗时统计] 函数 'calculate_sum' 执行用时: 0.012431 秒
最终计算结果: 125000250000

三、函数调用拦截链路与执行机制

为了加深对装饰器内部工作过程的理解,我们可以对比函数在被装饰前后的调用链路差异。在未经装饰时,调用方发起的请求直接直达函数执行体并返回;而在经过装饰器包装后,调用链路被 wrapper 完整拦截。

python装饰器怎么定义函数
图 4:Python 函数被装饰前后的调用链路对比图

从图中可以看出,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__}")
示例运行输出
函数名: export_report
函数文档: 根据报表 ID 导出财务报表数据

如果去掉 @functools.wraps(func),输出的函数名将变为 wrapper,函数文档将显示为空(或 wrapper 自身的文档)。因此,将 @wraps 作为定义装饰器的标配,是编写高质量 Python 代码的重要习惯。

五、进阶场景:定义接收参数的装饰器函数

很多时候,我们需要让装饰器自身也能接收配置参数。例如:@retry(max_attempts=3) 或 @rate_limit(seconds=60)。很多初学者在此时容易陷入困惑,因为常规的双层函数结构只能接收目标函数 func,无法再容纳额外的配置项。

要定义接收参数的装饰器,需要采用三层函数嵌套模式(也称为“装饰器工厂”):

python装饰器怎么定义函数
图 5:带参数装饰器的三层嵌套函数结构图

三层函数的职责划分如下:

  • 最外层(工厂函数):接收装饰器所需的自定义参数(如重试次数、超时限制等),并返回中层的标准装饰器。
  • 中间层(标准装饰器):接收被装饰的目标函数对象 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}")
示例运行输出
[执行轮次 1/3] 调用 send_ping
正在向主机 192.168.1.1 发送心跳包...
[执行轮次 2/3] 调用 send_ping
正在向主机 192.168.1.1 发送心跳包...
[执行轮次 3/3] 调用 send_ping
正在向主机 192.168.1.1 发送心跳包...
最终心跳响应: PONG

六、常见定义错误排查与最佳实践总结

在编写装饰器函数时,如果对闭包引用和执行时机理解不透彻,很容易写出不易察觉的逻辑缺陷。以下总结了定义装饰器时的核心避坑检查清单。

python装饰器怎么定义函数
图 6:Python 装饰器定义要点与避坑排查总结图

常见典型错误排查

  1. 错误一:外层函数错误地写成 return wrapper()
    外层函数的目的是返回包装函数对象本身,供后续调用。如果多加了小括号,Python 会在加载代码定义函数时立刻执行一次 wrapper,并将其实际返回值(通常是 None)赋给目标函数,导致后续调用时报 TypeError: 'NoneType' object is not callable 错误。
  2. 错误二:内层 wrapper 遗漏了 return result
    如果在包装函数内执行了 func(*args, **kwargs),但没有将结果 return 出来,原函数的调用方将永远只能拿到 None。无论原函数计算出了什么,都会被包装器静默吞没。
  3. 错误三:没有使用 *args, **kwargs 导致参数签名受限
    如果包装函数定义为 def wrapper(a, b):,那么该装饰器就只能用于修饰恰好接收两个位置参数的函数。换成其他参数形式就会报错。始终使用 *args, **kwargs 能够确保装饰器通用健壮。
  4. 错误四:带参装饰器少写了一层函数
    当需要使用 @my_dec(arg=1) 这种形式时,如果依然只写两层函数,Python 会把参数误当作目标函数传给第一层,从而导致原函数根本没有被接收。带参装饰器必须有三层嵌套。

掌握了上述定义规范、通用参数写法、元数据保护以及三层嵌套结构,读者就能够根据项目需要,清晰、规范地定义出各种功能稳定、代码干净的 Python 装饰器函数。

相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。