Python 装饰器进阶：从函数包装到类装饰器，元编程的正确姿势

Python 装饰器进阶：从函数包装到类装饰器，元编程的正确姿势

一、装饰器不只是语法糖：元编程的入口

Python 装饰器用 @ 符号标注，看起来像是语法糖，但它本质上是高阶函数的应用。@decorator 等价于 func = decorator(func)，这个等式揭示了装饰器的核心机制：接收一个可调用对象，返回一个新的可调用对象。

初学者通常把装饰器用在日志记录、计时、权限校验这些场景。这些用例没问题，但只触及了装饰器的表层能力。真正让装饰器强大的，是它在元编程中的应用：动态修改函数签名、运行时注入依赖、基于配置生成方法、实现声明式 API。

生产环境里，装饰器的坑主要集中在三个方面：被装饰函数的元信息丢失（__name__、__doc__ 变成 wrapper 的）、装饰器叠加时的执行顺序混乱、带参数装饰器的嵌套括号让人头晕。这些问题不是装饰器本身的问题，而是对装饰器机制理解不深导致的误用。

二、装饰器的执行机制与闭包原理

理解装饰器的关键，是理解 Python 的闭包和函数对象模型。

graph TD
    A[@decorator 标注] --> B[Python 解释器处理]
    B --> C[将原函数传入 decorator]
    C --> D[decorator 返回新函数]
    D --> E[新函数绑定到原函数名]

    F[调用被装饰函数] --> G[实际调用 wrapper]
    G --> H[wrapper 执行增强逻辑]
    H --> I[wrapper 调用原函数]
    I --> J[返回结果]

    subgraph 闭包环境
        K[wrapper 函数体]
        L[引用的 func 变量]
        M[引用的自由变量]
    end

    K --> L
    K --> M

装饰器叠加时的执行顺序是从下到上。也就是说，离函数定义最近的装饰器最先执行包装，最远的装饰器最外层。用代码表示：

@decorator_a
@decorator_b
def func():
    pass

# 等价于
func = decorator_a(decorator_b(func))

调用时，执行顺序是从外到内：先 decorator_a 的 wrapper，再 decorator_b 的 wrapper，最后原函数。理解这个顺序对于调试多层装饰器至关重要。

三、生产级装饰器：从基础到高级模式

基础：保留元信息的通用装饰器模板

import functools
import time
from typing import Callable, TypeVar, Any

F = TypeVar("F", bound=Callable[..., Any])

def timer(func: F) -> F:
    """计时装饰器，记录函数执行耗时"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        try:
            result = func(*args, **kwargs)
            return result
        finally:
            elapsed = time.perf_counter() - start
            print(f"[{func.__name__}] 耗时 {elapsed:.4f}s")
    return wrapper  # type: ignore

functools.wraps 是必须的。它将原函数的 __name__、__doc__、__module__、__qualname__、__annotations__ 和 __dict__ 复制到 wrapper 上，同时更新 __wrapped__ 属性。没有 wraps，调试和文档生成都会出问题。

进阶：带参数的装饰器

def retry(max_attempts: int = 3, delay: float = 1.0, exceptions: tuple = (Exception,)):
    """重试装饰器工厂，支持自定义重试次数、间隔和异常类型"""
    def decorator(func: F) -> F:
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            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}s 后重试..."
                        )
                        time.sleep(delay)
            # 所有重试均失败，抛出最后一次的错误
            raise last_error  # type: ignore
        return wrapper  # type: ignore
    return decorator


# 使用示例
@retry(max_attempts=5, delay=0.5, exceptions=(ConnectionError, TimeoutError))
def fetch_data(url: str) -> dict:
    """从远程 API 获取数据"""
    import requests
    resp = requests.get(url, timeout=3)
    resp.raise_for_status()
    return resp.json()

带参数的装饰器实际上是一个"装饰器工厂"——外层函数接收参数，返回真正的装饰器。调用时有两层括号：@retry(...) 先调用工厂，返回装饰器，装饰器再作用于函数。

高级：类装饰器实现依赖注入

import functools
from typing import Any, Callable

class Inject:
    """依赖注入装饰器，通过注册表为函数参数注入依赖"""

    _registry: dict[str, Any] = {}

    @classmethod
    def register(cls, name: str, instance: Any) -> None:
        """注册依赖实例"""
        cls._registry[name] = instance

    @classmethod
    def auto(cls, func: Callable) -> Callable:
        """自动注入标记了类型的参数"""
        annotations = func.__annotations__

        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            # 遍历参数注解，查找可注入的依赖
            for param_name, param_type in annotations.items():
                if param_name == "return":
                    continue
                # 如果参数未显式传入，且注册表中有对应类型，则注入
                if param_name not in kwargs:
                    type_name = param_type.__name__ if hasattr(param_type, '__name__') else str(param_type)
                    if type_name in cls._registry:
                        kwargs[param_name] = cls._registry[type_name]
            return func(*args, **kwargs)
        return wrapper


# 使用示例
class Database:
    def query(self, sql: str) -> list:
        return [{"id": 1, "name": "test"}]

# 注册依赖
Inject.register("Database", Database())

@Inject.auto
def get_users(db: Database) -> list:
    """db 参数会被自动注入，调用时无需传入"""
    return db.query("SELECT * FROM users")

# 调用时不需要传 db 参数
users = get_users()

四、装饰器的适用边界与常见陷阱

元信息丢失的深层影响：即使使用了 functools.wraps，__wrapped__ 指向的是直接内层函数。如果装饰器叠加三层，__wrapped__ 只能回溯一层。inspect.unwrap() 可以递归解开所有层，但某些框架（如 FastAPI）依赖 __signature__ 做参数解析，多层装饰器可能导致签名不一致。

装饰器与描述符的冲突：当装饰器作用于类的方法时，第一个参数 self 的处理需要注意。如果 wrapper 没有正确接收 *args，类方法调用会报参数数量不匹配。更隐蔽的问题是：如果装饰器返回的不是函数而是描述符对象（如 property），会改变方法的访问方式。

性能开销：每次调用被装饰函数，都会多一层函数调用和闭包查找。对于高频调用的热路径（如循环内调用），这个开销可能累积到可感知的程度。解决方案是对热路径避免使用装饰器，或者用 __wrapped__ 直接调用原函数。

调试困难：装饰器改变了函数的调用栈，异常追踪中会出现 wrapper 层。functools.wraps 的 __wrapped__ 属性可以帮助定位原函数，但在复杂装饰器链中仍然不直观。建议在 wrapper 内部使用 raise ... from e 保留原始异常链。

五、总结

Python 装饰器的本质是高阶函数的应用，@ 语法只是调用语法糖。functools.wraps 是编写装饰器的必备工具，它保留了原函数的元信息。带参数的装饰器通过工厂模式实现，外层函数接收参数，内层函数才是真正的装饰器。类装饰器可以实现依赖注入等高级元编程模式。装饰器的局限在于元信息传递不完整、与描述符可能冲突、存在性能开销和调试困难。在生产代码中，装饰器适合横切关注点（日志、重试、权限），不适合核心业务逻辑的组装。