Python元编程：装饰器参数传递与包装

理解装饰器与参数传递的三层调用结构

在Python中，普通装饰器本质是一个接收函数并返回新函数的可调用对象。但当装饰器需要接收配置参数时，就必须引入“三层调用结构”：最外层是装饰器工厂函数，负责接收装饰器自身的参数并返回真正的装饰器；中间层是装饰器函数，负责接收被装饰的目标函数；最内层是包装函数，负责在实际调用时拦截请求、执行额外逻辑，并最终将参数透传给原函数。参数流转的核心在于闭包与*args、**kwargs的解包机制。当调用被装饰函数时，实际执行的是wrapper，它通过*args捕获所有位置参数，通过**kwargs捕获所有关键字参数，随后在内部调用func(*args, **kwargs)将参数原封不动地传递给原始函数。这种设计既保证了装饰器配置的灵活性，又维持了目标函数调用接口的透明性。理解这三层嵌套的闭包作用域与参数传递路径，是编写健壮装饰器的基石。

实现带参数装饰器与灵活的函数包装

实现带参数装饰器的关键在于明确区分“装饰器配置参数”与“目标函数业务参数”。以重试装饰器为例，@retry(max_attempts=3)中的max_attempts属于装饰器参数，在工厂函数层被捕获并保存在闭包中；而目标函数自身的参数则在wrapper层通过*args和**kwargs动态接收。代码实现时，外层工厂返回一个接收func的装饰器，该装饰器内部定义wrapper，在wrapper中编写重试逻辑：通过循环控制调用次数，捕获异常后决定是否继续，最终必须显式返回func(*args, **kwargs)的执行结果，否则调用方将得到None。同理，日志装饰器@log(level="INFO")可在调用前后打印格式化日志，并利用kwargs获取函数名与参数快照。无论装饰器参数如何变化，wrapper都必须保持对原函数签名的完全兼容，确保位置参数与关键字参数能正确映射，且返回值不被意外丢弃。

用functools.wraps保留被装饰函数元数据

默认情况下，装饰器返回的wrapper函数会完全覆盖原函数的元数据属性，包括__name__、__doc__、__module__以及函数签名。这会导致依赖反射的工具（如文档生成器、依赖注入框架或调试器）无法正确识别原函数。解决该问题的标准做法是引入functools.wraps。它是一个装饰器，内部通过update_wrapper将原函数的__name__、__doc__、__dict__等属性同步到wrapper上。在实际编码中，只需在wrapper定义上方添加@wraps(func)即可。验证时，可结合inspect模块进行对比：装饰前调用inspect.signature(target_func)能准确获取参数列表与注解；若未使用wraps，签名将变为(*args, **kwargs)，且__doc__显示为包装器说明；使用wraps后，元数据与签名将完全恢复至原始状态，确保代码在自动化测试、API路由注册等场景下的行为符合预期。

组合装饰器并排查参数与包装常见陷阱

多个装饰器叠加时，Python遵循“自下而上装饰、自上而下执行”的规则。例如@A与@B同时作用于函数，等价于A(B(func))，调用时先执行A的wrapper，再进入B的wrapper。在实际开发中，常见陷阱包括：第一，装饰器内部忘记return wrapper，导致原函数被替换为None，调用时直接抛出TypeError；第二，wrapper定义遗漏*args或**kwargs，使得带默认值或关键字参数的目标函数调用失败；第三，误将带参数装饰器写成普通形式，如直接写@retry而非@retry(3)，引发参数数量不匹配错误；第四，忽略元数据保留导致路由注册或Mock测试失效。排查时，可通过打印装饰器各层入口日志、使用pdb单步跟踪闭包变量，或借助inspect.unwrap()逐层剥离包装，快速定位参数截断或执行顺序异常的根本原因。