一、什么是类装饰器？

在 Python 中，装饰器（Decorator）是一种高阶函数，它接受另一个对象（通常是函数或类），并返回一个经“增强”处理后的新对象。我们常见的是对函数进行装饰：

@my_decorator
def foo(...):
...

同样的机制也可以应用于类定义，只需将装饰器放置在类定义前即可：

@my_class_decorator
class MyClass:
...

当 Python 解释器读取这段代码时，首先会执行 my_class_decorator(MyClass)，然后用其返回值（通常是一个修改过的新类对象）替代原类定义。这个机制让开发者可以在类创建阶段插入自定义行为，提升代码复用性和元编程能力。

二、类装饰器的典型应用场景

类装饰器的主要应用场景包括但不限于：

• 自动添加属性或方法
• 统一初始化逻辑（如日志、性能监控、计数）
• 实现动态元编程（例如自动混入 Mixin、序列化支持）

下面通过三个实用示例详细讲解类装饰器的设计与使用。

三、实用示例解析

示例 1：为每个实例自动记录创建时间

我们可以利用类装饰器来为所有实例统一加上时间戳功能，使其在每次实例化时自动记录创建时间。

装饰器实现

import datetime
def timestamp_decorator(cls):
"""
给类添加一个 `created_at` 属性，在 __init__ 中记录对象创建时间。
"""
original_init = cls.__init__
def new_init(self, *args, **kwargs):
# 先调用原始 __init__ 方法完成原本的初始化过程
original_init(self, *args, **kwargs)
# 然后添加当前时间戳
self.created_at = datetime.datetime.now()
# 替换类中的 __init__
cls.__init__ = new_init
return cls

使用方式

@timestamp_decorator
class User:
def __init__(self, name):
self.name = name
u = User('Alice')
print(u.created_at) # 输出类似：2025-04-05 10:30:45.123456

解释说明

该装饰器会保存原有 __init__ 方法，并在其基础上新增设置时间戳的功能。这种做法无需侵入原有类结构，便于功能扩展和后期维护。

示例 2：给类的所有公开方法添加日志打印

有时我们希望在每次调用某个类的方法时自动输出日志信息，便于调试或审计。

装饰器实现

import functools
def log_method_decorator(cls):
"""
为类中所有公开方法（非下划线开头）包装一层日志输出。
"""
for name, method in cls.__dict__.items():
if callable(method) and not name.startswith('_'):
@functools.wraps(method)
def wrapper(self, *args, **kwargs):
print(f"[LOG] 调用 {cls.__name__}.{name}，参数: {args}，关键字参数: {kwargs}")
return method(self, *args, **kwargs)
setattr(cls, name, wrapper)
return cls

使用方式

@log_method_decorator
class Calculator:
def add(self, a, b):
return a + b
def mul(self, a, b):
return a * b
calc = Calculator()
calc.add(3, 4) # 输出日志并返回 7
calc.mul(2, 5) # 输出日志并返回 10

解释说明

通过 setattr 动态地替换了每个公开方法，同时使用 functools.wraps 确保封装后的函数保留了原有签名和文档说明。这一技巧特别适合构建通用的日志系统或者拦截调用链。

示例 3：动态为类添加 JSON 序列化能力（Mixin 实现）

有时候我们要给多个类批量添加相同的功能，比如使类支持以 JSON 格式输出数据。

装饰器实现

import json
def serializable_decorator(cls):
"""
为类动态添加 to_json() 方法，用于将属性转为 JSON 字符串。
"""
def to_json(self):
# 只导出不含下划线前缀的属性
public_attrs = {k: v for k, v in self.__dict__.items() if not k.startswith('_')}
return json.dumps(public_attrs, ensure_ascii=False)
# 将方法绑定到类上
cls.to_json = to_json
return cls

使用方式

@serializable_decorator
class Person:
def __init__(self, name, age):
self.name = name
self.age = age
p = Person("Bob", 30)
print(p.to_json()) # 输出 {"name": "Bob", "age": 30}

解释说明

此方式模拟了一种常见的 Mixin 模式：通过类装饰器动态注入通用功能。相比于继承多重 Mixin，类装饰器可以更灵活、优雅地控制附加功能的应用范围。

四、类装饰器的总结

类装饰器允许开发者在类创建期间就施加一些变更，是 Python 面向切面编程（AOP）的一种优雅实践方式。

五、拓展建议

若希望进一步了解装饰器机制，可研究以下高级主题：

1. 带参数的类装饰器（Decorator Factory）：

• @add_attributes(version='1.0', author='dev')
  class MyService:
  ...

1. 使用类作为装饰器（Callable 类）：

• class MyDecorator:
  def __call__(self, cls):
  ...

1. 组合多种装饰器：

• @log_call
  @auto_timestamp
  @serialize_support
  class Service:
  ...

通过这些进阶方式，你可以构建出强大的、高度可配置的类增强逻辑。