函数的“外套“与“内芯“：Python 装饰器从调用栈到生产级模式

最新推荐文章于 2026-06-22 22:35:00 发布

原创最新推荐文章于 2026-06-22 22:35:00 发布 · 228 阅读

3 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#rust #github #python

函数的"外套"与"内芯"：Python 装饰器从调用栈到生产级模式

cover

一、重复代码的隐形税——装饰器要解决的工程痛点

写过 Python 的人大概都见过 @staticmethod、@property 这些内置装饰器，但真正理解装饰器机制的人并不多。我之前也是"会用但不敢写"的状态，直到在一个项目里需要给十几个接口统一加日志、计时和权限校验，才意识到装饰器不是语法糖，而是一种控制流抽象工具。

没有装饰器时，每个函数都要手动写 start_time = time.time()、logger.info(...)、check_permission(...) 这些重复逻辑。这些横切关注点（Cross-cutting Concerns）散落在业务代码里，修改时要逐个函数改，遗漏一个就是 Bug。装饰器的核心价值在于：把这些与业务逻辑无关但必须执行的逻辑，从函数内部抽离出来，形成可复用的控制层。

二、装饰器的执行机制——从函数对象到闭包链

2.1 装饰器本质：高阶函数 + 闭包

装饰器在 Python 中没有任何魔法，它就是接受一个函数作为参数、返回一个新函数的高阶函数。@decorator 语法只是 func = decorator(func) 的简写。

sequenceDiagram
    participant Caller as 调用方
    participant Wrapper as wrapper 闭包
    participant Decorator as decorator 函数
    participant Original as 原始函数 func

    Note over Decorator,Original: 定义阶段：@decorator 触发
    Decorator->>Original: 接收 func 作为参数
    Decorator->>Wrapper: 创建并返回 wrapper 闭包
    Note over Wrapper: wrapper 闭包捕获 func 引用

    Note over Caller,Original: 调用阶段
    Caller->>Wrapper: 调用 wrapper(*args, **kwargs)
    Wrapper->>Wrapper: 执行前置逻辑（日志/计时/校验）
    Wrapper->>Original: 调用 func(*args, **kwargs)
    Original-->>Wrapper: 返回结果
    Wrapper->>Wrapper: 执行后置逻辑（日志/异常处理）
    Wrapper-->>Caller: 返回最终结果

2.2 闭包捕获与变量绑定

理解装饰器的关键在于理解闭包。wrapper 函数在 decorator 内部定义时，捕获了 func 这个变量的引用。这意味着即使 decorator 执行完毕返回后，wrapper 仍然可以访问 func——因为闭包延长了 func 的生命周期。

def decorator(func):
    # wrapper 是闭包，捕获了 func 的引用
    # 即使 decorator 返回后，func 仍然存活在闭包的 __closure__ 中
    def wrapper(*args, **kwargs):
        print(f"调用: {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

@decorator
def greet(name):
    return f"你好, {name}"

# 等价于: greet = decorator(greet)
# greet 现在指向 wrapper，而非原始函数
print(greet("世界"))  # 调用: greet\n你好, 世界

# 验证闭包捕获
print(greet.__closure__)  # (<cell at ...: function object at ...>,)
print(greet.__closure__[0].cell_contents)  # <function greet at ...>

2.3 多层装饰器的执行顺序

多个装饰器叠加时，执行顺序是"从下到上装饰，从上到下执行"。这和函数调用栈的入栈顺序一致：

@decorator_a  # 最外层，最后包装
@decorator_b  # 中间层
@decorator_c  # 最内层，最先包装
def func():
    pass

# 等价于: func = decorator_a(decorator_b(decorator_c(func)))
# 调用时: a_wrapper -> b_wrapper -> c_wrapper -> 原始 func

2.4 functools.wraps 的必要性

装饰器替换了原始函数，导致 __name__、__doc__ 等元信息丢失。functools.wraps 通过更新 wrapper 的属性来修复这个问题：

from functools import wraps

def timed(func):
    @wraps(func)  # 将 func 的元信息复制到 wrapper
    # 不加 @wraps，wrapper.__name__ 会是 "wrapper"
    # 加了之后，wrapper.__name__ 是原始函数名
    def wrapper(*args, **kwargs):
        import time
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__} 耗时: {elapsed:.4f}s")
        return result
    return wrapper

三、生产级装饰器模式与代码实现

3.1 带参数的装饰器：三层嵌套

带参数的装饰器需要三层函数：最外层接收装饰器参数，中间层接收被装饰函数，最内层是实际 wrapper。这是装饰器最让人困惑的模式，但理解了闭包就很简单：

from functools import wraps

def retry(max_attempts=3, delay=1.0, exceptions=(Exception,)):
    """可配置的重试装饰器
    max_attempts: 最大重试次数
    delay: 重试间隔（秒）
    exceptions: 需要重试的异常类型元组
    """
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            import time
            last_error = None
            for attempt in range(1, max_attempts + 1):
                try:
                    return func(*args, **kwargs)
                except exceptions as e:
                    last_error = e
                    if attempt < max_attempts:
                        print(
                            f"{func.__name__} 第{attempt}次失败: {e}，"
                            f"{delay}秒后重试"
                        )
                        time.sleep(delay)
            # 所有重试都失败，抛出最后一个异常
            raise last_error
        return wrapper
    return decorator

# 使用：先调用 retry(max_attempts=3) 返回 decorator
# 再用 decorator 装饰 fetch_data
@retry(max_attempts=3, delay=2.0, exceptions=(ConnectionError, TimeoutError))
def fetch_data(url):
    """从远程 API 获取数据，网络不稳定时自动重试"""
    import urllib.request
    return urllib.request.urlopen(url, timeout=5).read()

3.2 类装饰器：有状态的装饰器

当装饰器需要维护状态（如调用计数、缓存、速率限制）时，类装饰器比闭包更清晰：

from functools import wraps

class RateLimiter:
    """滑动窗口速率限制器装饰器
    限制函数在指定时间窗口内的最大调用次数
    """
    def __init__(self, max_calls=10, period=60):
        self.max_calls = max_calls
        self.period = period
        self.calls = []  # 记录每次调用的时间戳

    def __call__(self, func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            import time
            now = time.time()
            # 清理过期记录
            self.calls = [
                t for t in self.calls if now - t < self.period
            ]
            if len(self.calls) >= self.max_calls:
                raise RuntimeError(
                    f"速率限制: {func.__name__} 在{self.period}秒内"
                    f"最多调用{self.max_calls}次"
                )
            self.calls.append(now)
            return func(*args, **kwargs)
        return wrapper

@RateLimiter(max_calls=5, period=60)
def call_api(endpoint):
    """调用外部 API，每分钟最多5次"""
    return f"调用 {endpoint} 成功"

3.3 装饰器实现依赖注入

在大型项目中，装饰器可以用来实现轻量级的依赖注入，解耦组件间的硬编码依赖：

from functools import wraps

# 简单的依赖容器
_registry = {}

def register(name):
    """注册依赖到容器"""
    def decorator(cls):
        _registry[name] = cls
        return cls
    return decorator

def inject(**dependencies):
    """依赖注入装饰器
    将容器中的依赖注入到函数参数中
    """
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            # 从容器中解析依赖，注入到 kwargs
            for param_name, dep_name in dependencies.items():
                if param_name not in kwargs:
                    if dep_name not in _registry:
                        raise KeyError(
                            f"依赖 '{dep_name}' 未注册"
                        )
                    kwargs[param_name] = _registry[dep_name]()
            return func(*args, **kwargs)
        return wrapper
    return decorator

# 注册依赖
@register("database")
class Database:
    def query(self, sql):
        return f"执行: {sql}"

# 注入依赖
@inject(db="database")
def get_user(user_id, db=None):
    return db.query(f"SELECT * FROM users WHERE id={user_id}")