reflect-metadata 库真正负责元数据存储与读取，通过扩展 reflect 对象提供 definemetadata、getmetadata 等方法；需严格区分作用域（类/原型/属性）、优先使用装饰器、避免 proxy 干扰、并主动清理元数据。

Reflect 本身不直接管理元数据，真正负责元数据存储与读取的是 reflect-metadata 库——它扩展了全局 Reflect 对象，注入了 defineMetadata、getMetadata 等方法。高效管理动态元数据，关键在于用对 API、规避陷阱、并配合 TypeScript 装饰器机制。

明确目标对象和作用域：类、原型、实例、属性要分清

元数据不是挂在任意对象上都“自动可见”的。Reflect 的元数据操作严格区分作用域：

• Reflect.defineMetadata(key, value, target) —— 写入到 target 自身（如类构造函数）
• Reflect.defineMetadata(key, value, target.prototype, 'propName') —— 写入到类原型上的某个属性（最常见于字段装饰器）
• Reflect.getMetadata(key, target) 或 Reflect.getMetadata(key, target.prototype, 'propName') —— 必须与写入时的层级完全匹配，否则返回 undefined
• 避免误用 getMetadata 查实例对象：元数据默认不继承到实例，除非你显式定义在实例上（一般不推荐）

优先使用装饰器语法，而非手动调用 Reflect 方法

TypeScript 装饰器 + emitDecoratorMetadata: true 是最自然、最不易出错的元数据声明方式：

• 编译器会自动生成 design:type、design:paramtypes 等基础类型元数据
• 自定义装饰器可封装 Reflect.defineMetadata，隐藏底层细节，提升复用性
• 示例：@Validate({ required: true }) name: string; 内部即调用 Reflect.defineMetadata('validate', { required: true }, target, propertyKey)
• 手动调用易遗漏 propertyKey 参数，或混淆 target 是构造函数还是原型

避免 Proxy 干扰元数据访问

Proxy 包装对象后，Reflect.getMetadata 默认无法穿透到原始目标：

• 因为元数据是绑定在原始对象（如 target）上的，而 Proxy 的 get trap 返回的是代理结果，不触发元数据查找逻辑
• 解决方案：不在 Proxy 上直接查元数据；改查原始目标（需保留引用），或在 Proxy 的 get trap 中显式委托元数据操作
• 更稳妥的做法是——元数据只用于设计期/初始化阶段（如框架启动时扫描类），运行时尽量不依赖对 Proxy 实例做反射

清理与检查：用 hasMetadata 和 deleteMetadata 控制生命周期

动态元数据不是一次写入就一劳永逸，尤其在热更新、模块卸载或测试隔离场景下：

• 用 Reflect.hasMetadata(key, target) 避免重复定义，防止覆盖关键配置
• 用 Reflect.deleteMetadata(key, target) 主动清理测试用例间的污染
• 批量操作可用 Reflect.getMetadataKeys(target) 获取当前所有键，再逐个处理
• 注意：元数据不随对象 GC 自动清除，长期运行项目中需有意识管理