直接在方法内写 logging.info() 导致日志逻辑分散、易遗漏、难维护；手动传类名方法名易错；统一开关、格式、耗时统计需逐个修改；切面式装饰器可解耦日志逻辑，需精准识别实例方法、保留元信息、支持异步与白名单控制。

为什么直接在方法里写 logging.info() 不够用

类方法分散在不同位置，重复加日志逻辑容易漏、难维护；手动传 self.class.name 和方法名易出错；想统一开关日志、改格式、加耗时统计时，得挨个改。切面方式把日志逻辑从业务代码里抽出来，才是可持续的。

• 日志内容至少应含：类名、方法名、入参（可选）、返回值（可选）、异常（如有）
• 装饰器必须能识别被装饰的是实例方法（带 self），不能误处理静态/类方法
• Python 3.10+ 的 inspect.signature() 比 inspect.getargspec() 更可靠，尤其对带类型注解或 functools.wraps 包裹的函数

用 @wraps + inspect 实现带上下文的类装饰器

核心是让装饰器作用于整个类，遍历其所有实例方法并重新绑定带日志逻辑的新函数。注意：不能直接装饰类本身（那会替换类对象），而是“改造类的 dict 中的方法”。

import functools
import inspect
import logging
import time
<p>def log_method_calls(logger_name="root"):
logger = logging.getLogger(logger_name)</p><pre class="brush:python;toolbar:false;">def decorator(cls):
    for attr_name, attr_value in cls.__dict__.items():
        if callable(attr_value) and not attr_name.startswith('_'):
            # 排除 __init__、私有方法、类/静态方法
            sig = inspect.signature(attr_value)
            if len(sig.parameters) > 0 and list(sig.parameters.keys())[0] == "self":
                setattr(cls, attr_name, _log_wrapper(attr_value, logger))
    return cls
return decorator

def _log_wrapper(func, logger): @functools.wraps(func) def wrapper(self, *args, **kwargs): method_name = func.name class_name = self.class.name logger.info(f"[{class_name}.{method_name}] → args={args}, kwargs={kwargs}")

    start = time.time()
    try:
        result = func(self, *args, **kwargs)
        elapsed = time.time() - start
        logger.info(f"[{class_name}.{method_name}] ← result={result} (took {elapsed:.3f}s)")
        return result
    except Exception as e:
        elapsed = time.time() - start
        logger.error(f"[{class_name}.{method_name}] ✗ raised {type(e).__name__}: {e} (took {elapsed:.3f}s)")
        raise
return wrapper

• 必须用 functools.wraps(func) 保留原函数的 name、doc 等元信息，否则调试、IDE 跳转会失效
• list(sig.parameters.keys())[0] == "self" 是粗筛，更严谨可用 inspect.isfunction(attr_value) + 检查第一个参数名，但多数场景已够用
• 不建议在装饰器里自动配置 logging.basicConfig() —— 容易和主程序冲突，由调用方控制 logger 更安全

常见踩坑：__init__ 被记录、继承方法没生效、异步方法报错

• init 默认会被匹配（它是实例方法且首参是 self），但初始化日志价值低、还可能因参数未 fully 构建导致 repr 报错。解决方案：在遍历 cls.dict 时显式跳过 if attr_name == "init": continue
• 子类未重写的方法不会出现在子类的 dict 中，所以装饰器只影响被装饰类自身定义的方法。若需覆盖继承链，得用元类或在类定义后手动扫描 inspect.getmembers(cls, predicate=inspect.isfunction)，但会增加复杂度
• 如果类里混用了 async def 方法，callable(attr_value) 仍为 True，但 _log_wrapper 返回的是同步 wrapper，调用时会报 RuntimeWarning: coroutine 'xxx' was never awaited。应对方式：先用 inspect.iscoroutinefunction(attr_value) 分流，用 async def wrapper(...) 重写异步分支

性能与粒度控制：不是所有方法都值得日志化

全量打日志会拖慢高频调用路径（比如数据结构的 getitem、len）。更实用的做法是支持白名单：

Python Pep Authoring

依据官方 python/peps仓库规则起草、审阅、编辑或准备 Python 改进提案（PEP），用于处理 PEP 文本和元数据头部。

下载

@log_method_calls(only_methods=["process", "validate", "save"])
class DataHandler:
    ...

实现上只需在装饰器闭包中加 only_methods 参数，并在遍历时判断 attr_name in only_methods。也可以反过来支持 exclude_methods。关键是把控制权交出去，而不是默认全开。

真正难的不是写这个装饰器，而是决定哪些方法该进日志、哪些参数要脱敏（比如密码字段）、错误日志要不要带完整 traceback —— 这些没法靠自动化解决，得结合业务语义人工判断。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！