Python 装饰器实战:写一个自动记录脚本运行时间的装饰器

在 Python 开发中，我们经常需要知道一段代码、一个函数的运行耗时——比如排查脚本执行慢的问题、评估接口响应效率、对比不同算法的性能。最基础的方式是在函数前后手动记录时间戳再计算差值，但这种“重复写计时代码”的方式既繁琐又不优雅。

而 Python 装饰器（Decorator）正是解决这类“通用功能复用”问题的绝佳工具：只需写一次计时逻辑，通过“装饰”的方式就能给任意函数、脚本添加上运行时间记录功能，无需重复修改业务代码。本文从实战角度出发，从零实现一个“自动记录运行时间”的装饰器，涵盖基础版、进阶版（支持参数、多场景适配），并讲解装饰器的核心原理，让你既能用得顺手，又能理解底层逻辑。

一、先搞懂：为什么用装饰器做计时？

先看一个“手动计时”的反例——假设我们有两个函数需要计时：

import time

# 业务函数1：模拟数据处理
defprocess_data():
    start = time.time()  # 手动记录开始时间
    time.sleep(1.2)      # 模拟耗时操作
    end = time.time()    # 手动记录结束时间
print(f"process_data 运行耗时：{end - start:.2f}秒")

# 业务函数2：模拟接口请求
defrequest_api():
    start = time.time()  # 重复的计时代码
    time.sleep(0.8)      # 模拟耗时操作
    end = time.time()    # 重复的计时代码
print(f"request_api 运行耗时：{end - start:.2f}秒")

if __name__ == "__main__":
    process_data()
    request_api()

这种写法的问题显而易见：

1. 代码重复
   ：每个需要计时的函数都要写 start/end/print 三行代码，违反“DRY（Don't Repeat Yourself）”原则；
2. 侵入业务逻辑
   ：计时代码和业务代码混在一起，函数职责不纯粹（比如 process_data 本应只处理数据，却还要负责计时）；
3. 维护成本高
   ：如果要修改计时格式（比如保留3位小数、输出毫秒），需要改所有函数。

而用装饰器改造后，效果是这样的（先看最终效果，再拆解实现）：

import time
# 定义计时装饰器（写一次，复用无数次）
deftimer_decorator(func):
defwrapper(*args, **kwargs):
        start = time.time()
        result = func(*args, **kwargs)  # 执行原函数
        end = time.time()
print(f"{func.__name__}运行耗时：{end - start:.2f}秒")
return result
return wrapper

# 用装饰器修饰函数（一行代码搞定计时）
@timer_decorator
defprocess_data():
    time.sleep(1.2)

@timer_decorator
defrequest_api():
    time.sleep(0.8)

if __name__ == "__main__":
    process_data()  # 输出：process_data 运行耗时：1.20 秒
    request_api()   # 输出：request_api 运行耗时：0.80 秒

可以看到：

• 业务函数回归纯粹，只关注核心逻辑；
• 计时功能通过 @timer_decorator 一行代码添加，无需修改函数内部；
• 要修改计时规则，只需改 timer_decorator 这一个地方。

这就是装饰器的核心价值：在不修改原函数代码的前提下，为函数添加额外功能。

二、从零实现：基础版计时装饰器

1. 装饰器的核心原理

装饰器本质是一个“高阶函数”——接收一个函数作为参数，返回一个新的函数（通常叫 wrapper），新函数会包裹原函数的执行逻辑，在执行前后添加额外操作（比如计时）。

用一张简单的流程图理解执行过程：

2. 基础版完整实现

import time

deftimer_decorator(func):
"""
基础版计时装饰器：记录函数运行时间并打印
参数：
        func: 被装饰的函数
返回：
        wrapper: 包裹了计时逻辑的新函数
    """
# 定义包裹函数，*args和**kwargs接收原函数的任意参数
defwrapper(*args, **kwargs):
# 步骤1：记录函数开始执行时间
        start_time = time.time()

# 步骤2：执行原函数，保留返回值（避免原函数有返回值时丢失）
        func_result = func(*args, **kwargs)

# 步骤3：记录函数结束执行时间，计算耗时
        end_time = time.time()
        elapsed_time = end_time - start_time

# 步骤4：打印计时结果（友好的格式）
print(f"✅函数{func.__name__}运行完成 | 耗时：{elapsed_time:.2f}秒")

# 步骤5：返回原函数的结果，保证被装饰函数的返回值正常使用
return func_result

# 返回包裹函数，替代原函数
return wrapper

# ===================== 测试使用 =====================
# 装饰无参数函数
@timer_decorator
defsay_hello():
    time.sleep(0.5)
print("Hello, Python装饰器！")

# 装饰有参数函数
@timer_decorator
defcalculate_sum(a, b):
    time.sleep(0.3)
return a + b

if __name__ == "__main__":
    say_hello()
# 输出：
# Hello, Python装饰器！
# ✅函数 say_hello 运行完成 | 耗时：0.50 秒

    result = calculate_sum(10, 20)
print(f"计算结果：{result}")
# 输出：
# ✅函数 calculate_sum 运行完成 | 耗时：0.30 秒
# 计算结果：30

3. 关键细节解释

• *args
   和 **kwargs：接收原函数的任意位置参数和关键字参数，保证装饰器能适配所有函数（不管原函数有没有参数、有多少参数）；
• func_result = func(*args, **kwargs)
  ：必须执行原函数并保留返回值，否则如果原函数有返回值（比如 calculate_sum 返回求和结果），被装饰后会丢失；
• func.__name__
  ：获取原函数的名称，让打印的计时信息更清晰（比如区分是 say_hello 还是 calculate_sum）；
• 保留两位小数：:.2f 让耗时输出更整洁，避免出现 0.5000000001 这种冗余格式。

三、进阶优化：更实用的计时装饰器

基础版能满足基本需求，但在实际开发中，我们还需要更灵活的功能——比如输出毫秒级耗时、将计时日志写入文件、自定义计时提示语、禁用计时功能等。下面实现一个“增强版”计时装饰器，适配更多实战场景。

1. 进阶版完整实现

import time
import logging
from functools import wraps

# 初始化日志配置（可选：将计时信息写入日志文件）
logging.basicConfig(
    level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s",
    handlers=[
        logging.FileHandler("timer_logs.log", encoding="utf-8"),  # 写入文件
        logging.StreamHandler()  # 输出到终端
    ]
)

defadvanced_timer(units="seconds", log_to_file=False, desc=""):
"""
进阶版计时装饰器：支持自定义单位、日志记录、描述信息
参数：
        units: 耗时单位，可选 "seconds"（秒）/ "milliseconds"（毫秒）
        log_to_file: 是否将计时信息写入日志文件（True/False）
        desc: 函数的自定义描述（方便区分不同函数的计时）
返回：
        decorator: 装饰器函数
    """
# 外层函数接收装饰器的参数
defdecorator(func):
# 使用functools.wraps保留原函数的元信息（比如__name__）
        @wraps(func)
defwrapper(*args, **kwargs):
            start_time = time.perf_counter()  # 更高精度的时间函数
try:
# 执行原函数
                result = func(*args, **kwargs)
return result
finally:
# 无论原函数是否报错，都执行计时（避免异常时丢失计时）
                end_time = time.perf_counter()
                elapsed = end_time - start_time

# 转换单位
if units == "milliseconds":
                    elapsed = elapsed * 1000
                    unit_str = "毫秒"
else:
                    unit_str = "秒"

# 构造提示信息
                func_name = func.__name__
                desc_info = f"【{desc}】"if desc else""
                message = f"⏱️{desc_info}函数{func_name}运行耗时：{elapsed:.2f}{unit_str}"

# 输出方式：终端打印或日志文件
if log_to_file:
                    logging.info(message)
else:
print(message)

return wrapper
return decorator

# ===================== 测试进阶版装饰器 =====================
# 示例1：默认配置（秒级、终端打印）
@advanced_timer()
deftest_1():
    time.sleep(0.6)

# 示例2：毫秒级、写入日志、自定义描述
@advanced_timer(units="milliseconds", log_to_file=True, desc="数据清洗函数")
deftest_2():
    time.sleep(0.45)

# 示例3：原函数抛出异常，仍能记录计时
@advanced_timer(desc="带异常的函数")
deftest_3():
    time.sleep(0.2)
raise ValueError("模拟函数执行出错")

if __name__ == "__main__":
    test_1()
# 输出：⏱️函数 test_1 运行耗时：0.60 秒

    test_2()
# 终端+日志文件同时输出：⏱️【数据清洗函数】函数 test_2 运行耗时：450.00 毫秒

try:
        test_3()
except ValueError:
pass
# 输出：⏱️【带异常的函数】函数 test_3 运行耗时：0.20 秒

2. 进阶版核心优化点

3. 关键知识点：带参数的装饰器

进阶版装饰器 advanced_timer 支持传入 units/log_to_file/desc 参数，这是“带参数的装饰器”，其核心逻辑是：

1. 外层函数 advanced_timer 接收装饰器的参数；
2. 中间层函数 decorator 接收被装饰的函数 func；
3. 内层函数 wrapper 实现具体的计时逻辑。

简单理解：带参数的装饰器 = 「装饰器工厂」 + 「基础装饰器」——先根据参数生成一个定制化的装饰器，再用这个装饰器修饰函数。

四、实战场景：装饰器的灵活用法

1. 装饰类中的方法

装饰器不仅能修饰普通函数，也能修饰类的实例方法/类方法：

classDataProcessor:
    @advanced_timer(desc="处理用户数据")
defprocess_user_data(self, user_id):
        time.sleep(0.7)
print(f"处理用户{user_id}的数据完成")

processor = DataProcessor()
processor.process_user_data(1001)
# 输出：⏱️【处理用户数据】函数 process_user_data 运行耗时：0.70 秒

2. 装饰整个脚本的主函数

在运维/自动化脚本中，常需要记录整个脚本的运行时间，只需装饰 main 函数：

@advanced_timer(units="seconds", log_to_file=True, desc="数据同步脚本主函数")
defmain():
# 脚本核心逻辑
print("开始同步数据...")
    time.sleep(3.5)
print("数据同步完成！")

if __name__ == "__main__":
    main()
# 日志文件中会记录：2026-01-22 15:30:00 - INFO - ⏱️【数据同步脚本主函数】函数 main 运行耗时：3.50 秒

3. 临时禁用装饰器

如果某段时间不需要计时（比如调试阶段），无需删除装饰器，只需注释掉 @ 符号，或给装饰器加开关：

# 临时禁用：注释掉装饰器
# @advanced_timer()
deftest_4():
    time.sleep(0.1)

# 或添加开关参数
defconditional_timer(enable=True):
defdecorator(func):
ifnot enable:
return func  # 禁用时直接返回原函数，不做任何包装
        @wraps(func)
defwrapper(*args, **kwargs):
# 计时逻辑...
pass
return wrapper
return decorator

# 禁用计时
@conditional_timer(enable=False)
deftest_5():
    time.sleep(0.2)

五、避坑指南：使用装饰器的常见问题

1. 原函数的元信息丢失

问题：基础版装饰器中，func.__name__ 会变成 wrapper，导致日志/打印的函数名错误。
解决：使用 from functools import wraps，并在 wrapper 函数上添加 @wraps(func)。

2. 原函数的返回值丢失

问题：装饰器中忘记返回 func_result，导致被装饰函数调用后无返回值。
解决：必须执行 result = func(*args, **kwargs) 并 return result。

3. 装饰器参数传递错误

问题：带参数的装饰器忘记加括号，比如 @advanced_timer 而非 @advanced_timer()。
解决：带参数的装饰器必须加括号（即使不传参数，也要写 @advanced_timer()）。

4. 异常导致计时中断

问题：原函数抛出异常时，计时逻辑没执行，无法记录耗时。
解决：用 try...finally 包裹原函数执行逻辑，确保无论是否异常都计算耗时。

六、总结：装饰器的核心价值与扩展方向

1. 核心知识点回顾

• 装饰器是“高阶函数”，核心是“无侵入式添加功能”；
• 基础装饰器结构：装饰器函数 → wrapper函数 → 执行原函数 + 额外逻辑；
• 带参数的装饰器需要三层嵌套：参数接收层 → 装饰器层 → wrapper层；
• 关键技巧：*args/**kwargs 适配任意参数、@wraps 保留元信息、try...finally 兼容异常。

2. 扩展方向（基于计时装饰器）

学会了计时装饰器，你可以轻松扩展出更多实用装饰器：

• 性能统计装饰器：记录函数的平均耗时、最大/最小耗时、调用次数；
• 缓存装饰器：缓存函数的执行结果，避免重复计算（比如 functools.lru_cache）；
• 重试装饰器：函数执行失败时自动重试（比如接口请求超时重试）；
• 权限校验装饰器：执行函数前校验用户权限。

3. 最终建议

装饰器是 Python 中极具“优雅感”的特性，但其本质是“语法糖”——核心逻辑还是函数的嵌套调用。在实战中，建议：

1. 先实现基础版，满足核心需求；
2. 再根据场景逐步优化（比如加日志、加参数）；
3. 优先使用 functools.wraps 保留原函数信息，避免踩坑；
4. 复杂场景下，可使用第三方库（如 decorator 库）简化开发。

一个简单的计时装饰器，不仅能帮你高效记录脚本运行时间，更能让你理解“面向切面编程”的思想——将通用功能（计时、日志、权限）与业务逻辑分离，让代码更简洁、更易维护。这正是 Python 装饰器的魅力所在。