装饰器与元数据反射

可视化演示

展示Transformer自注意力计算流程：Q/K/V矩阵映射、注意力分数矩阵、Softmax归一化与加权求和。支持单头注意力与多头并行模式切换。

装饰器概述：给代码贴「快递标签」

快递分拣中心建成的第一天，你发现分拣员们总是在争吵：「这个包裹要不要轻拿轻放？」你决定引入标准标签制度：每个包裹进入分拣台，先经过一台「标签机」，它根据包裹的特点贴上一张标准标签。标签机不拆开包裹，不改变包裹里的东西，只是在外层贴一张纸。这就是装饰器的本质——一种不改变代码内部实现、只附加额外信息的「贴标签」机制。

在 TypeScript 中，装饰器是一种特殊的声明，以 @ 符号开头，紧跟一个表达式。这个表达式求值后必须是一个函数，函数会在运行时接收被装饰的目标，并可以返回一个新目标来替换它。装饰器可以作用于类、方法、属性、参数四类目标，分别对应「整箱」「箱内物品」「物品属性」「搬运口令」四种标签。

从编程范式看，装饰器是「声明式元编程」的典型代表。命令式编程要自己写代码告诉程序每一步怎么做；而声明式编程只需要声明「这个方法是只读的」，剩下的由框架完成。这就像你告诉分拣员「这个包裹易碎」，而不必手把手教他怎么轻拿轻放。

装饰器是编程中「曲线救国」的智慧：我们无法直接修改语言底层，但可以给代码贴上标签，让框架替我们完成那些重复、机械的工作。标签制度在分拣中心推广开后，每个分拣员都开始依赖这些标签——接下来，我们看看不同类型的包裹适合什么标签。

类装饰器：给整箱包裹贴总标签

分拣中心开始处理整箱货物。你发现，有些箱子需要整体标注「整车加急」，而不是给箱子里每一件商品单独贴标签。类装饰器就是这个思路——它作用在整个「箱子」（类）上，而不是箱子里的单个物件。

类装饰器是作用于类声明上的装饰器。当 TypeScript 编译时，类装饰器接收的唯一参数是类的构造函数。它可以在类的层面做手脚：给类添加静态属性、修改原型、甚至用一个新的类完全替换旧的类。注意类装饰器不接收「属性名」——因为类这个层级还没有到具体成员。

在 NestJS 中，@Controller('/users') 和 @Injectable() 都是类装饰器。@Controller 在类的构造函数上记录一个路由前缀，@Injectable 标记该类可以被依赖注入容器管理。这些装饰器都不需要修改类内部的任何代码——它们只是「绕着类转了一圈」，在标签登记簿上写了几笔。

为什么类装饰器能「换掉」一个类？因为在 JavaScript 里，类本质上就是构造函数加原型，「替换构造函数」在运行时完全可行。不过在真实工程中，大部分类装饰器并不会真的换类，而是像 @Injectable 那样默默登记「这个类可以用」。真正「换类」的场景，通常出现在高阶组件或依赖注入容器的框架代码里。

方法装饰器：给易碎品贴特殊标签

箱子里总有一些特别脆弱的物品需要单独标识。比如一个玻璃花瓶，整箱标签只能写「轻放」，但它需要的是「绝对防震」。这时候分拣员会在花瓶上单独贴一张红色「易碎」标签。方法装饰器就像这张红色标签——它贴在类中的某个具体方法上，告诉框架「这个方法需要特殊处理」。

方法装饰器在方法声明之前定义。它接收三个参数：第一个是类的原型对象（如果是静态方法则是构造函数），第二个是方法名，第三个是方法的属性描述符（Property Descriptor）。属性描述符是 JavaScript 底层的「方法配置单」，包含 value（函数本身）、writable（能否重新赋值）、enumerable（能否被遍历）、configurable（能否删除）四个字段。

方法装饰器最实用的能力是「拦截」：通过改写描述符中的 value，可以在原方法执行前后插入自己的逻辑。日志记录、权限校验、缓存、事务管理，这些横切关注点都能用一个方法装饰器干净利落地解决。这正是 AOP（面向切面编程）的思想——把日志、权限这些「横切关注点」从业务逻辑中剥离，用装饰器优雅织入。

借助 d.value 的改写，方法装饰器可以给方法「裹上一层保护壳」。这层壳在每次方法调用时先执行额外逻辑，再调用原始方法。你的业务方法依然专心做自己的事，「警戒线」由装饰器来拉。这也是 @Get('/list') 这类路由装饰器的底层原理——它把路径信息挂在方法上，让框架在扫描时发现它。

属性装饰器：只登记不改动的标签

分拣中心还有一种更细的标签：贴在单个物品上的「重量」「产地」标签。这些标签不改变物品本身的功能，只是登记信息。属性装饰器就是这样——它作用于类的属性，但不能修改属性的值，只能登记属性相关的元信息。

为什么不能修改值？因为属性装饰器在类定义阶段就被调用了，这时候实例还没创建，根本没有「值」可以改。它接收的参数只有两个：目标原型和属性名（对比方法装饰器的三个参数）。它的主要用途是：把属性的设计时类型信息记录到元数据里，供依赖注入、序列化等框架功能使用。

TypeScript 在编译开启了 emitDecoratorMetadata 的代码时，会自动调用 Reflect.metadata 装饰器，把属性的类型（design:type）等信息写入元数据。这也是类型信息在「编译后即抹除」的 JavaScript 世界里的重要保留手段。没有这步登记，NestJS 就无法在运行时知道构造函数要注入什么类型的依赖。

「不能改值」不是缺陷，而是安全边界。分拣员只需记录「这个箱子高 30 厘米、重 5 公斤」，没必要推倒箱子去量。属性装饰器只做登记，这让框架可以安全地扫描并收集类的结构信息，无需担心副作用。少了这份克制，依赖注入就会变成一场不可控的「拆箱游戏」。

执行机制：先贴里层，再贴外层

分拣中心墙上贴着一张《标签作业顺序规范》：如果要给同一个箱子贴两张标签，必须先贴里面的，再贴外面的。装饰器的执行机制与此惊人一致——它遵循一条看似反直觉的规则：求值从上到下，调用从下到上。

对于 @A @B class C，执行分两步：第一步，从上到下求值 @A 和 @B 两个表达式，得到装饰器函数的引用；第二步，从下到上进行函数调用——先执行 B(C)，再把结果传给 A。多个装饰器组合时，最下方的装饰器最贴近目标，最上方的装饰器在最外层。这就像穿衣服：先穿内衣，再穿外套。

如果装饰器带参数，比如 @Controller('/users')，还会多一层「工厂函数」：先调用 Controller 工厂拿到真正的装饰器函数，再用它去装饰类。理解这个执行顺序是写复杂装饰器的前提——如果把依赖顺序弄反，装饰器拿到的可能是尚未被初始化的对象，程序会在运行时悄悄出错。

这个「洋葱模型」不仅决定装饰器的包裹层次，也决定了嵌套顺序所带来的视觉效果。在 NestJS 中，你可能会看到 @Controller 与 @UseGuards 同时出现——守卫包在控制器外层，请求先经过守卫再进入控制器。理解执行顺序，你就理解了框架的「标签读取」流程：机器沿着标签从外往里读，直到最核心的业务逻辑。

元数据反射：标签登记簿

分拣中心越做越大，你发现光贴标签还不够，需要一本「标签登记簿」：每次贴标签时顺手记一笔，后续查询「这个箱子贴过什么标签」时，不用翻箱倒柜，直接查登记簿。Reflect Metadata 就是 TypeScript 世界里的这本登记簿。

Reflect Metadata 是 ECMAScript 的一个提案（当时处于 Stage 2，现已被装饰器 Stage 3 提案吸收），它为 Reflect 全局对象扩展了一套元数据读写 API。核心方法有四组：defineMetadata 写入、getMetadata 读取（包含原型链）、getOwnMetadata 读取（不包含原型链）、hasMetadata 判断是否存在。在 TypeScript 中开启 emitDecoratorMetadata 后，编译器会自动生成 design:type、design:paramtypes、design:returntype 三类设计时类型元数据。

这套机制的价值在于：JavaScript 是一门「运行时不保留类型信息」的语言，但通过装饰器 + 元数据，我们可以在运行时重建一套类型系统。这正是 NestJS 依赖注入的前提——容器需要知道构造函数期望的参数类型，才能把正确的依赖实例注入进去。

很多初学者混淆「装饰器」与「元数据」：装饰器是「贴标签」的动作，元数据是「标签上的内容」。两者配合，才构成「声明式编程」的完整拼图——你声明意图（写元数据），框架负责执行（读元数据）。可以说，没有 Reflect Metadata，NestJS 的依赖注入就只能靠「魔法字符串」硬编码，而优雅的自动装配也无从谈起。

框架应用：NestJS 的智能分拣系统

分拣中心迎来了智能分拣系统。货物贴上标签后，传送带自动识别标签：「加急」送快速通道，「冷链」推进冷库，「偏远」流向物流车——没有任何人指挥，全靠标签驱动。NestJS 之于 JavaScript 生态，就是这套智能分拣系统。

NestJS 的架构核心是「装饰器驱动」：@Module 声明模块，@Controller 声明路由控制器，@Injectable 声明可注入的服务，@Inject 声明依赖注入的 token。这些装饰器执行时，会把各种元数据写入 Reflect Metadata。NestJS 启动时，框架扫描所有类，读取元数据，构建依赖关系图、注册路由表。

依赖注入的流程是：容器维护一个「注册表」，把每个服务和 token 对应起来。当一个类需要依赖时，容器查看这个类构造函数的设计时参数类型元数据（design:paramtypes），到注册表里找到对应的服务实例，自动注入进去。路由注册同理：@Controller('users') 写下前缀，@Get('list') 写下路径，框架读取元数据后，自动把方法挂在对应的 HTTP 路径上。

理解了这套机制，你就读懂了 NestJS 的「底层魔法」。那些看似神奇的 @Injectable() 并不是框架的晦涩黑科技，而是装饰器 + 元数据反射在工程中的经典应用。更进一步地，当你自己设计一套「标签系统」时——例如给 AI Agent 的工具函数贴上「何时可用」的标签，让调度器自动选择工具——你正在复刻 NestJS 的分拣中心架构。

标准演进：从方言到国家标准

分拣中心的标签制度推行一段时间后，你发现各家快递公司都有自己的体系：A 家红色代表易碎，B 家蓝色代表易碎，外来的分拣员经常搞混。你决定推动「标签国家标准」——统一颜色、统一位置、统一含义。装饰器的标准演进，正是这样一条从「各家方言」走向「国际标准」的路。

装饰器最初是 TypeScript 的实验特性，需要在 tsconfig.json 里开启 experimentalDecorators 和 emitDecoratorMetadata 才能使用。这套「旧语法」（legacy decorators）基于 ES2016 装饰器草案，功能强大但存在问题：编译器要生成大量辅助代码（如 __decorate 函数）；对装饰器返回值类型校验宽松；元数据发射依赖私有 API，不利于标准化。

2022 年，ECMAScript 装饰器提案进入 Stage 3，带来全新语法。新签名统一为 (value, context)：value 是被装饰的值（类、方法、属性等），context 是包含 kind、name、access、addInitializer 等信息的上下文对象。新语法还移除了旧版的参数装饰器，不再自动发射 design:type 元数据——这导致 reflect-metadata 这类库在新语法下存在兼容性问题。

标准演进对开发者意味着什么？新语法更统一、更安全，浏览器原生支持也在路上（Chrome 已默认开启）。但 NestJS 等大型框架的生态目前仍深度依赖旧语法和反射元数据，所以 TypeScript 官方短期内会继续支持旧语法，只是不再推动它走向标准。作为开发者，「新旧语法都要看得懂」是很有用的能力——就像分拣员既要会解读老标签，也要会用新国标。

AI 应用场景

Python 演示

"""用 Python 模拟 TypeScript 装饰器与 Reflect Metadata演示依赖注入 + 路由注册的底层机制"""import functools # 模拟 Reflect Metadata 的存储层_META = {} def define_metadata(key, value, target):    # 写入元数据: 相当于 Reflect.defineMetadata    _META.setdefault(id(target), {})[key] = value def get_metadata(key, target, default=None):    # 读取元数据: 相当于 Reflect.getMetadata    return _META.get(id(target), {}).get(key, default) class Injectable:    # 类装饰器: 标记可注入依赖    def __call__(self, cls):        define_metadata('injectable', True, cls)        return cls class Controller:    # 类装饰器: 注册路由前缀    def __init__(self, prefix):        self.prefix = prefix     def __call__(self, cls):        define_metadata('prefix', self.prefix, cls)        routes = []        for name, method in cls.__dict__.items():            path = getattr(method, '_path', None)            if path is not None:                full = self.prefix + path                routes.append((name, full, method))        define_metadata('routes', routes, cls)        return cls class Get:    # 方法装饰器: 标记 HTTP GET 路径    def __init__(self, path):        self.path = path     def __call__(self, method):        method._path = self.path        @functools.wraps(method)        def wrapper(*args, **kwargs):            print(f"[路由] GET {self.path} -> {method.__name__}")            return method(*args, **kwargs)        wrapper._path = self.path        return wrapper class Log:    # 方法装饰器: 记录调用日志    def __call__(self, method):        @functools.wraps(method)        def wrapper(*args, **kwargs):            print(f"[日志] 调用 {method.__name__}")            result = method(*args, **kwargs)            print(f"[日志] 完成 {method.__name__}")            return result        return wrapper # 模拟框架启动: 扫描 + 注册@Injectable@Controller('/api/users')class UserService:    def __init__(self, db="内存库"):        self.db = db     @Get('/list')    @Log()    def list_users(self):        return f"[{self.db}] 用户列表: Alice, Bob" if __name__ == '__main__':    print("=== 启动时扫描元数据 ===")    print("injectable:", get_metadata('injectable', UserService))    print("路由前缀:", get_metadata('prefix', UserService))    print("路由表:")    for name, path, fn in get_metadata('routes', UserService):        print(f"  GET {path} -> {name}")     print("\n=== 调用业务方法 ===")    svc = UserService()    print(svc.list_users())

1. _META.setdefault(id(target), {})[key] = value用目标对象的 id 作为键，把元数据存入全局「标签登记簿」。
2. class Injectable:模拟 @Injectable() 类装饰器：只在元数据中标记 injectable=True，不改变类行为。
3. class Controller:模拟 @Controller(prefix)：扫描类方法，把带 _path 标签的方法收集成路由表。
4. method._path = self.path给原方法打上「路由路径」标签，供外层装饰器和 Controller 扫描读取。
5. @functools.wraps(method)保留原函数的 __name__ 和 __dict__，确保路由标签不因包装而丢失。
6. wrapper._path = self.path包装函数也要接力传递路由标签，否则 Controller 会找不到它。
7. if __name__ == '__main__':入口：像 NestJS 一样在启动时扫描元数据并打印路由表，然后调用业务方法。

常见误区

面试题