17370845950

装饰器元数据是通过 reflect-metadata 为类等元素附加结构化信息的机制，不改变行为但提供可读上下文；装饰器存元数据，运行时取用，支持任意类型值和精细作用域，典型用于依赖注入、API 文档生成与参数校验。

装饰器元数据是 JavaScript 中用于在运行时为类、方法、属性或参数附加结构化描述信息的机制，它本身不是 ECMAScript 标准的一部分，而是通过 reflect-metadata 这一事实标准（由 TypeScript 和许多现代框架采用）实现的。它不改变被装饰对象的行为，而是为装饰器提供可读、可查、可共享的上下文信息。

元数据如何与装饰器协同工作

装饰器函数本身只接收目标对象、成员名、属性描述符等有限参数。元数据则允许你在装饰时“存”一些额外数据，在后续任意时机（比如初始化、依赖注入、序列化前）“取”出来使用。

• 装饰器调用时，用 Reflect.defineMetadata(key, value, target, propertyKey?) 存储信息
• 运行时其他逻辑（如框架启动、实例创建）用 Reflect.getMetadata(key, target, propertyKey?) 读取该信息
• 元数据以键值对形式存在，支持任意类型值（字符串、对象、函数等），作用域可精确到类、静态成员、实例方法、访问器、参数索引等

典型使用场景举例

例如在 NestJS 或 Angular 中：

• @Injectable() 会在类上存入 design:paramtypes（构造函数参数类型），供 DI 容器自动解析依赖
• @ApiProperty() 在属性上存入字段描述（如类型、是否必需、示例值），用于自动生成 OpenAPI 文档
• @Validate() 在方法参数上存入校验规则元数据，中间件在执行前统一提取并校验

关键细节注意点

元数据不是自动继承的，需显式设置 Reflect.metadata('key', value) 装饰器或手动调用 defineMetadata；TypeScript 编译器默认仅生成 design:type、design:paramtypes、design:returntype 这三类类型元数据（需开启 emitDecoratorMetadata: true）；自定义元数据键建议使用 Symbol 避免冲突，或采用命名空间前缀（如 'mylib:route'）。

它让装饰器从“单纯标记”升级为“携带意图的声明”，是构建可扩展框架和类型感知工具链的重要基础设施。