深入理解 Python 装饰器：从原理到实战应用
折
折腾侠
2026/03/24 发布
13约 8 分钟1445 字 / 846 词00
深入理解 Python 装饰器：从原理到实战应用
引言
Python 装饰器（Decorator）是 Python 语言中最具特色和最强大的功能之一。它允许程序员在不修改原有代码的前提下，动态地给函数或类添加新的功能。这种设计模式不仅体现了 Python「优雅、明确、简单」的哲学，更是实际开发中解决横切关注点（Cross-Cutting Concerns）问题的利器。
本文将带你从装饰器的基本原理出发，逐步深入理解其工作机制，并通过多个实际应用场景，展示装饰器在真实项目中的强大能力。无论你是 Python 初学者还是有一定经验的开发者，相信都能从中获得新的启发。
一、装饰器的本质：函数即对象
要理解装饰器，首先需要理解 Python 中「函数是一等公民」这一核心概念。在 Python 中，函数可以：
- 被赋值给变量
- 作为参数传递给其他函数
- 作为另一个函数的返回值
- 被定义在其他函数内部（闭包）
让我们通过一个简单示例来理解这个概念：
Python
# 函数可以赋值给变量
def greet(name):
return f"Hello, {name}!"
say_hello = greet
print(say_hello("Alice")) # 输出：Hello, Alice!
# 函数可以作为参数传递
def execute(func, value):
return func(value)
result = execute(greet, "Bob")
print(result) # 输出：Hello, Bob!
# 函数可以作为返回值
def create_multiplier(factor):
def multiply(x):
return x * factor
return multiply
double = create_multiplier(2)
print(double(5)) # 输出：10
理解了这些基础概念后，我们就可以正式进入装饰器的世界了。
二、装饰器的基本语法与工作原理
2.1 最简单的装饰器
装饰器本质上是一个接受函数作为参数并返回新函数的可调用对象。让我们从零开始构建一个装饰器：
Python
import functools
def timer_decorator(func):
"""计算函数执行时间的装饰器"""
@functools.wraps(func) # 保留原函数的元信息
def wrapper(*args, **kwargs):
import time
start = time.time()
result = func(*args, **kwargs)
end = time.time()
print(f"{func.__name__} 执行耗时：{end - start:.4f} 秒")
return result
return wrapper
# 使用装饰器
@timer_decorator
def slow_function():
import time
time.sleep(1)
return "完成"
# 等价于：slow_function = timer_decorator(slow_function)
result = slow_function()
print(result)
2.2 @functools.wraps 的重要性
很多初学者会忽略 INLINE_CODE_0 的作用，但这实际上非常重要。如果不使用它，装饰后的函数会丢失原有的元信息：
Python
def without_wraps(func):
def wrapper(*args, **kwargs):
return func(*args, **kwargs)
return wrapper
def with_wraps(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
return func(*args, **kwargs)
return wrapper
@without_wraps
def test1():
"""这是 test1 的文档字符串"""
pass
@with_wraps
def test2():
"""这是 test2 的文档字符串"""
pass
print(test1.__name__) # 输出：wrapper（错误！）
print(test1.__doc__) # 输出：None（错误！）
print(test2.__name__) # 输出：test2（正确！）
print(test2.__doc__) # 输出：这是 test2 的文档字符串（正确！）
三、带参数的装饰器
实际开发中，我们经常需要给装饰器本身传递参数。这需要三层嵌套函数：
Python
def repeat(times):
"""重复执行函数指定次数的装饰器"""
def decorator(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
results = []
for _ in range(times):
result = func(*args, **kwargs)
results.append(result)
return results
return wrapper
return decorator
# 使用带参数的装饰器
@repeat(3)
def get_random_number():
import random
return random.randint(1, 100)
print(get_random_number()) # 输出：[42, 17, 89]（示例）
四、类装饰器
装饰器不仅可以是函数，也可以是类。类装饰器通过实现 INLINE_CODE_1 方法来工作：
Python
class CountCalls:
"""统计函数调用次数的类装饰器"""
def __init__(self, func):
functools.update_wrapper(self, func)
self.func = func
self.count = 0
def __call__(self, *args, **kwargs):
self.count += 1
print(f"第 {self.count} 次调用 {self.func.__name__}")
return self.func(*args, **kwargs)
@CountCalls
def say_hello(name):
print(f"Hello, {name}!")
say_hello("Alice") # 第 1 次调用 say_hello
say_hello("Bob") # 第 2 次调用 say_hello
print(f"总调用次数：{say_hello.count}") # 总调用次数：2
五、实际应用场景
5.1 日志记录
日志记录是装饰器最常见的应用场景之一：
Python
import logging
from datetime import datetime
def log_calls(logger_name="app"):
"""记录函数调用的装饰器"""
logger = logging.getLogger(logger_name)
def decorator(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
logger.info(f"调用 {func.__name__}, 参数：args={args}, kwargs={kwargs}")
try:
result = func(*args, **kwargs)
logger.info(f"{func.__name__} 返回：{result}")
return result
except Exception as e:
logger.error(f"{func.__name__} 抛出异常：{e}")
raise
return wrapper
return decorator
# 配置日志
logging.basicConfig(level=logging.INFO)
@log_calls()
def divide(a, b):
return a / b
divide(10, 2) # 会自动记录调用日志
5.2 权限验证
在 Web 应用中，装饰器常用于权限控制：
Python
from functools import wraps
def require_permission(permission):
"""权限验证装饰器"""
def decorator(func):
@wraps(func)
def wrapper(user, *args, **kwargs):
if permission not in user.permissions:
raise PermissionError(
f"用户 {user.name} 缺少 {permission} 权限"
)
return func(user, *args, **kwargs)
return wrapper
return decorator
class User:
def __init__(self, name, permissions):
self.name = name
self.permissions = permissions
@require_permission("admin")
def delete_user(admin_user, target_user):
print(f"管理员 {admin_user.name} 删除了用户 {target_user}")
# 测试
admin = User("Alice", ["read", "write", "admin"])
regular = User("Bob", ["read"])
delete_user(admin, "Charlie") # 成功
delete_user(regular, "Charlie") # 抛出 PermissionError
5.3 缓存装饰器（Memoization）
对于计算密集型函数，缓存可以显著提升性能：
Python
def memoize(func):
"""简单缓存装饰器"""
cache = {}
@functools.wraps(func)
def wrapper(*args):
if args in cache:
print(f"缓存命中：{args}")
return cache[args]
print(f"缓存未命中，计算：{args}")
result = func(*args)
cache[args] = result
return result
return wrapper
@memoize
def fibonacci(n):
if n < 2:
return n
return fibonacci(n-1) + fibonacci(n-2)
print(fibonacci(10)) # 只会计算一次
print(fibonacci(10)) # 直接从缓存返回
5.4 重试机制
网络请求等不稳定操作常需要重试机制：
Python
import time
import random
def retry(max_attempts=3, delay=1, backoff=2, exceptions=(Exception,)):
"""重试装饰器"""
def decorator(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
current_delay = delay
last_exception = None
for attempt in range(max_attempts):
try:
return func(*args, **kwargs)
except exceptions as e:
last_exception = e
print(f"尝试 {attempt + 1}/{max_attempts} 失败：{e}")
if attempt < max_attempts - 1:
print(f"等待 {current_delay} 秒后重试...")
time.sleep(current_delay)
current_delay *= backoff
raise last_exception
return wrapper
return decorator
@retry(max_attempts=3, delay=0.5)
def unstable_api():
if random.random() < 0.7:
raise ConnectionError("网络不稳定")
return "API 调用成功"
try:
result = unstable_api()
print(result)
except Exception as e:
print(f"最终失败：{e}")
5.5 类型检查装饰器
Python 是动态类型语言，但有时我们需要运行时类型检查：
Python
def type_check(*expected_types):
"""参数类型检查装饰器"""
def decorator(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
for arg, expected_type in zip(args, expected_types):
if not isinstance(arg, expected_type):
raise TypeError(
f"参数类型错误：期望 {expected_type.__name__}, "
f"得到 {type(arg).__name__}"
)
return func(*args, **kwargs)
return wrapper
return decorator
@type_check(int, int)
def add(a, b):
return a + b
print(add(1, 2)) # 正常：3
print(add("1", "2")) # 抛出 TypeError
六、装饰器栈：多个装饰器的组合
Python 允许对同一个函数应用多个装饰器，它们会按照从下到上的顺序执行：
Python
def decorator_a(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
print("[A] 进入")
result = func(*args, **kwargs)
print("[A] 退出")
return result
return wrapper
def decorator_b(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
print("[B] 进入")
result = func(*args, **kwargs)
print("[B] 退出")
return result
return wrapper
@decorator_a
@decorator_b
def test():
print(" 函数执行")
test()
# 输出顺序：
# [A] 进入
# [B] 进入
# 函数执行
# [B] 退出
# [A] 退出
七、最佳实践与常见陷阱
7.1 最佳实践
- 始终使用 INLINE_CODE_2：保留原函数的元信息
- 保持装饰器单一职责：一个装饰器只做一件事
- 文档化装饰器：说明装饰器的作用、参数和使用方式
- 考虑性能影响：避免在装饰器中做耗时操作
- 处理异常：确保装饰器不会吞掉原函数的异常
7.2 常见陷阱
Python
# 陷阱 1：忘记返回原函数的结果
def bad_decorator(func):
def wrapper(*args, **kwargs):
print("执行前")
func(*args, **kwargs) # 忘记 return!
print("执行后")
return wrapper
# 陷阱 2：装饰器参数可变默认值
def bad_memoize(func, cache={}): # 可变默认值！
def wrapper(*args):
if args in cache:
return cache[args]
result = func(*args)
cache[args] = result
return result
return wrapper
# 正确做法
def good_memoize(func):
cache = {} # 在装饰器内部创建
@functools.wraps(func)
def wrapper(*args):
if args in cache:
return cache[args]
result = func(*args)
cache[args] = result
return result
return wrapper
八、总结
装饰器是 Python 中最优雅和强大的特性之一。通过本文的学习，你应该已经掌握了：
- 装饰器的基本原理：函数作为一等公民
- 装饰器的语法和工作机制
- 带参数的装饰器和类装饰器
- 实际应用场景：日志、权限、缓存、重试、类型检查
- 装饰器栈的组合使用
- 最佳实践和常见陷阱
装饰器的真正威力在于它能够将横切关注点与业务逻辑分离，使代码更加模块化、可维护和可测试。当你下次发现自己在多个函数中重复相同的代码模式时，不妨考虑用装饰器来优雅地解决这个问题。
记住：优秀的代码不是写出来的，而是重构出来的。装饰器就是你重构路上的得力助手。
关于作者：本文旨在帮助开发者深入理解 Python 装饰器的原理与应用。欢迎在实际项目中尝试这些技巧，并根据具体需求进行调整和扩展。