带参数装饰器必须三层嵌套：工厂函数（接收参数）→装饰器函数（接收func）→包装器（接收args/kwargs），漏掉任一层或未用functools.wraps都会报错或丢失元信息。
为什么直接套用无参装饰器写法会报错
因为 @decorator 语法糖在解析时，Python 会把紧跟着的函数对象直接传给装饰器。如果你写了 @log(level="DEBUG")，解释器实际调用的是 log(level="DEBUG")(func) —— 也就是先执行外层函数拿到一个「真正能接收函数的装饰器」，再用它去包装目标函数。漏掉这一层嵌套，level 就会误当成被装饰函数传入，立刻抛出 TypeError: log() missing 1 required positional argument: 'func'。
常见错误写法：
def log(level): # ❌ 这不是装饰器，这是个工厂函数
print(f"Setting level to {level}")
def wrapper(func):
def inner(*args, **kwargs):
print(f"[{level}] Calling {func.__name__}")
return func(*args, **kwargs)
return inner
return wrapper # ✅ 忘记返回 wrapper，或返回错对象，都会导致后续调用失败
标准三层结构：工厂 → 装饰器 → 包装器
带参数装饰器必须是三层嵌套函数，每层职责清晰：
- 最外层（工厂函数）：接收装饰器参数（如
level、timeout），只运行一次，返回第二层函数 - 中间层（装饰器函数）：接收被装饰的
func，返回第三层函数 - 最内层（包装器）：接收实际调用时的
*args和**kwargs，执行逻辑并调用原函数
示例（带日志级别和开关控制的装饰器）：
def log(level="INFO", enabled=True):
def decorator(func):
def wrapper(*args, **kwargs):
if enabled:
print(f"[{level}] {func.__name__} called")
return func(*args, **kwargs)
return wrapper
return decorator
<p>@log(level="WARNING", enabled=False) # ✅ 正确调用方式
def risky_operation():
return "done"
</p>
使用 functools.wraps 保留原函数元信息
不加 functools.wraps 会导致被装饰函数的 __name__、__doc__、__annotations__ 全部变成 wrapper 的，这对调试、IDE 提示、类型检查（如 mypy）、甚至某些框架（Flask 路由注册）都会出问题。
必须在包装器上显式调用：
from functools import wraps
<p>def log(level="INFO"):
def decorator(func):
@wraps(func) # ✅ 关键一行，位置不能错（必须紧贴 wrapper 定义）
def wrapper(*args, *<em>kwargs):
print(f"[{level}] {func.<strong>name</strong>}")
return func(</em>args, **kwargs)
return wrapper
return decorator
</p>
验证效果：
@log("DEBUG")
def add(a, b):
"""Return sum of a and b."""
return a + b
<p>print(add.<strong>name</strong>) # ✅ 输出 "add"，不是 "wrapper"
print(add.<strong>doc</strong>) # ✅ 输出 "Return sum of a and b."
</p>
参数校验和默认值容易被忽略的细节
装饰器参数在模块加载时就执行了（即 @log(level=...) 那行代码导入时就运行最外层），所以任何参数错误（比如传了 None 给要求非空的 timeout）会在 import 阶段就崩溃，而不是函数调用时。这点和普通函数完全不同。
建议做法：
- 在外层函数里做参数检查，抛出明确的
ValueError，比如if not isinstance(level, str): raise ValueError("level must be str") - 避免在工厂函数里做耗时操作（如读文件、连数据库），否则会影响模块加载速度
- 如果需要动态参数（如从环境变量读取），应推迟到包装器中判断，而非工厂函数中硬编码
比如这个反例会悄悄失效：
import os
def cache(ttl=os.getenv("CACHE_TTL", "300")): # ❌ os.getenv 在装饰器定义时就执行，之后改环境变量无效
...
正确做法是把读取逻辑放到 wrapper 内部，或用延迟求值（如 lambda: os.getenv(...)）。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
