Python装饰器包裹静态方法后TypeError缺失参数的解决方法

当你用自定义装饰器包裹一个 @staticmethod 方法时，调用该方法往往会抛出 TypeError: xxx() missing 1 required positional argument。根本原因在于装饰器的执行顺序与描述符协议之间的冲突——装饰器把 staticmethod 描述符对象当成了普通函数来包装，导致最终绑定方式出错。解决思路有三种：调整装饰器的叠放顺序、在装饰器内部识别并解包描述符对象、或者改用 functools.wraps 搭配正确的包装逻辑。下面从现象开始，逐步拆解原因并给出可直接使用的修复代码。

一、问题的典型表现

先看一个最小复现。假设有一个记录日志的装饰器 log_call，把它放在 @staticmethod 上方：

import functools

def log_call(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"calling {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

class MathHelper:
    @log_call          # ← 先执行
    @staticmethod      # ← 先被解析
    def add(a, b):
        return a + b

调用时：

>>> MathHelper.add(1, 2)
TypeError: add() missing 1 required positional argument: 'b'

报错提示缺少参数 b，看起来像是 a 的位置被什么东西占据了。如果改成实例调用 MathHelper().add(1, 2)，同样报错。这说明装饰后的方法不再是静态方法，而是变成了普通的实例方法或未绑定函数。

二、原因：装饰器顺序与描述符协议

理解这个问题需要两个知识点：装饰器的执行顺序，以及 staticmethod 的本质。

2.1 装饰器从下往上执行

多个装饰器叠放时，最靠近函数定义的装饰器最先执行。上面的代码等价于：

add = log_call(staticmethod(add))

staticmethod(add) 返回的不是一个普通函数，而是一个描述符对象（staticmethod 类型）。这个对象没有 __name__、__module__ 等函数属性，也不能直接调用。当 log_call 拿到这个描述符对象之后，functools.wraps(func) 会因为缺少属性而出错（Python 3.10 之前），或者虽然不报错，但 wrapper 内调用 func(*args, **kwargs) 时传入的是描述符对象的 __call__，行为已经不对了。

2.2 staticmethod 是描述符

staticmethod 是一个描述符对象，它通过 __get__ 方法在属性访问时返回被包装的原始函数。当你通过 MathHelper.add 访问时，描述符协议触发 __get__，返回里面存储的真正函数。但如果装饰器把描述符对象替换成了普通函数，这个描述符协议就被切断了，Python 把 wrapper 当作普通函数挂在类上，访问时会自动传入 self 或 cls（在 Python 3 中，未绑定方法不再传 self，但经过实例调用时仍然会传），导致参数位移。

三、解决方法

方法一：交换装饰器顺序（推荐）

最简单也是最常用的方式：把 @staticmethod 放在最外面（最上面），让自定义装饰器先执行。这样自定义装饰器拿到的是原始函数，返回的 wrapper 再被 staticmethod 包装成描述符，一切正常。

class MathHelper:
    @staticmethod      # ← 后执行，包裹 wrapper
    @log_call          # ← 先执行，拿到原始 add 函数
    def add(a, b):
        return a + b

验证：

>>> MathHelper.add(1, 2)
calling add
3

这等价于 add = staticmethod(log_call(add))。log_call 拿到的是真正的函数对象，包装后返回 wrapper；staticmethod 再把 wrapper 变成描述符。通过类或实例访问时，描述符的 __get__ 正确返回 wrapper，不会额外传入 self。

方法二：在装饰器内部解包描述符

如果装饰器的顺序由框架或团队规范决定、不方便修改，可以让装饰器自己识别并处理 staticmethod（和 classmethod）描述符：

import functools

def log_call(func):
    # 检查是否收到了 staticmethod / classmethod 描述符
    is_static = isinstance(func, staticmethod)
    is_class = isinstance(func, classmethod)

    # 取出描述符内部存储的真实函数
    if is_static or is_class:
        inner = func.__func__
    else:
        inner = func

    @functools.wraps(inner)
    def wrapper(*args, **kwargs):
        print(f"calling {inner.__name__}")
        return inner(*args, **kwargs)

    # 重新用对应的描述符包装 wrapper
    if is_static:
        return staticmethod(wrapper)
    if is_class:
        return classmethod(wrapper)
    return wrapper

这样无论装饰器写在 @staticmethod 的上方还是下方，都能正确工作。关键点是通过 __func__ 属性取出描述符内部的原始函数。这个属性在 Python 3.x 中始终存在。

class MathHelper:
    @log_call          # 即使在上方也没问题
    @staticmethod
    def add(a, b):
        return a + b

>>> MathHelper.add(1, 2)
calling add
3

方法三：使用类实现装饰器并兼容描述符协议

如果装饰器本身用类实现（例如需要记录状态），需要手动实现 __get__ 方法，否则它会覆盖原有的描述符行为。这种情况在实际项目中比较少见，但偶尔会遇到：

import functools
import types

class LogCall:
    def __init__(self, func):
        # 处理描述符
        if isinstance(func, staticmethod):
            self._static = True
            func = func.__func__
        else:
            self._static = False
        functools.update_wrapper(self, func)
        self._func = func

    def __call__(self, *args, **kwargs):
        print(f"calling {self._func.__name__}")
        return self._func(*args, **kwargs)

    def __get__(self, obj, objtype=None):
        if self._static:
            return self
        if obj is None:
            return self
        return types.MethodType(self, obj)

这种方式更复杂，仅在确实需要类装饰器时才考虑。大多数场景下，方法一或方法二完全够用。

四、深入理解：描述符协议的调用过程

为了避免以后在类似场景中踩坑，有必要理解 Python 访问类属性时描述符协议的完整过程。当你写 MathHelper.add 时，Python 做了这些事：

1. 在 MathHelper.__dict__ 中找到 'add' 对应的值。
2. 检查这个值有没有 __get__ 方法（即是否是描述符）。
3. 如果是描述符，调用 type(add).__get__(add, None, MathHelper)，返回值就是你实际拿到的对象。
4. 对于 staticmethod 描述符，__get__ 返回内部存储的原始函数，不做任何绑定。
5. 对于普通函数，__get__ 在通过实例访问时返回绑定方法（自动传入 self）。

问题出在第2步：如果 add 的值是一个普通函数（因为装饰器把描述符替换掉了），Python 会按普通函数的描述符逻辑处理，通过实例调用时自动传入 self，导致参数错位。

五、验证修复是否成功

无论使用哪种方法修复，都可以通过以下方式确认问题已解决：

# 1. 通过类调用
assert MathHelper.add(3, 4) == 7

# 2. 通过实例调用
obj = MathHelper()
assert obj.add(3, 4) == 7

# 3. 确认属性类型（可选）
import inspect
# 检查 add 在类字典中是否仍然是 staticmethod
raw = MathHelper.__dict__['add']
print(type(raw))  # 应该输出 <class 'staticmethod'>

# 4. 检查不会传入 self
import dis
# 或者简单地用参数检查
sig = inspect.signature(MathHelper.add)
print(sig)  # 应该显示 (a, b)，没有 self

如果通过类和实例调用都返回正确结果，且 MathHelper.__dict__['add'] 的类型是 staticmethod，说明修复成功。

六、常见的关联问题

classmethod 是否有同样的问题？ 是的。classmethod 也是描述符，装饰器放在它上方同样会导致描述符被替换。解决方法完全一样：要么调整顺序把 @classmethod 放最外面，要么在装饰器内部用 isinstance(func, classmethod) 检测并取 func.__func__。方法二的代码已经包含了对 classmethod 的处理。

Python 3.10+ 的变化。 从 Python 3.10 开始，staticmethod 和 classmethod 对象实现了 __call__，可以直接调用。这意味着即使装饰器顺序"不对"，func(*args, **kwargs) 在装饰器内部不会报错。但返回给类的仍然是普通函数而不是描述符，通过实例调用时行为依旧可能异常。所以 Python 3.10+ 并没有彻底消除这个问题，只是让报错不那么直接，反而更容易被忽略。