Proxy 与 Reflect

是什么，为什么存在

Proxy 创建一个包装对象，让你能够观察或改写目标对象的基本操作。属性读取、赋值、in、delete、键枚举、函数调用和构造等操作，都有对应的 代理陷阱（proxy trap） 。调用方仍使用普通 JavaScript 语法，不需要改成 get("name") 一类专用接口。

Reflect 是一组静态方法，不是构造函数。它把 Reflect.get()、Reflect.set() 和 Reflect.ownKeys() 等基本操作暴露为函数，并且 13 个可拦截操作都与同名 trap 对应。handler 只改写少量行为时，调用 Reflect 可以清楚地表达“其余部分保持语言默认语义”。

这对 API 适合观察访问、校验写入、提供虚拟属性、构建可撤销视图，以及实现响应式系统或对象膜（membrane）的底层机制。它解决的是“保持普通对象语法，同时介入语言操作”这个问题，不是普通业务对象都应该使用的默认抽象。

代理不是目标的副本。对代理的成功写入通常会改变目标，目标的其他别名也能绕开 handler；代理与目标的对象标识又不相等。因此，隐藏下划线属性或拒绝某次读取只能形成接口约束，不能把仍然可达的目标变成安全保险库。

工作原理

new Proxy(target, handler) 要求 target 和 handler 都是对象。JavaScript 对代理执行内部对象操作时，会查找相应 trap；trap 不存在时，操作转发给目标。trap 存在但不可调用，或者返回结果违反语言不变量时，操作会抛出 TypeError。

一次带默认转发的属性读取可以按下面的顺序理解：

1. 表达式 proxy[key] 对代理发起内部 [[Get]] 操作。
2. 代理查找 handler 的 get trap。
3. get(target, key, receiver) 接收目标、属性键和最初的接收者。
4. trap 调用 Reflect.get(target, key, receiver) 执行普通读取语义。
5. 引擎核对 trap 结果必须满足的不变量，再把结果交给调用方。

trap 的参数由被拦截的语言操作决定，不是任意的回调签名。下面是完整映射； 属性描述符（property descriptor） 相关操作尤其容易与赋值混淆。

receiver 是最初收到操作的对象，可能就是代理，也可能是继承自代理的对象。Reflect.get(target, key, receiver) 会让访问器中的 this 指向这个接收者；直接写 target[key] 则把访问器的 this 固定为目标。Reflect.set() 的 receiver 对继承 setter 和最终把属性定义到哪个对象上同样重要。

Reflect 不会让操作自动变得安全，也不会绕过其他代理。目标本身若是代理，Reflect.get() 仍可能触发它的 trap；目标属性若是 getter，读取仍会执行 getter。handler 中应对 target 调用对应方法，而不是对 receiver 再做同一反射操作，否则很容易递归回当前 trap。

策略通常跨越多个 trap。只在 set 中校验不能拦住 Object.defineProperty(proxy, key, descriptor)，只在 get 中隐藏名称也不会自动影响 in、键枚举或描述符查询。先列出调用方能执行的全部操作，再决定哪些转发、拒绝或需要保持一致。

示例

下面四个示例依次展示默认转发、receiver、一致的虚拟属性和撤销。输出都由本地 Node 24 实际执行对应文件得到。

校验写入并保留默认读取

第一个 handler 只给读取添加日志，并对已声明规则的字段校验写入。属性键可以是 Symbol，因此日志先调用 String(key)，而不是直接把键插入模板字符串。

Reflect.set() 返回布尔值，正好符合 set trap 的返回约定。它返回 false 时，严格模式下的普通赋值会抛出 TypeError；handler 不应无条件返回 true 来掩盖失败。这个例子只承诺校验普通赋值，尚未覆盖属性定义路径。

规则对象本身也有原型，因此通用库不应直接相信任意键能安全索引它。可以使用 Object.hasOwn(rules, key)、无原型字典或 Map 明确规则集合。这里的数据和规则都由同一段可信代码创建，示例只聚焦 trap 转发。

保留访问器的接收者

两个代理只在转发 receiver 时不同。子对象从代理继承 getter，因此这个差异会改变 getter 中 this 所见的属性。

const account = {
  owner: "base",
  currency: "USD",
  get label() {
    return `${this.owner}:${this.currency}`;
  },
};

const badProxy = new Proxy(account, {
  get(target, key) {
    return Reflect.get(target, key, target);
  },
});

const goodProxy = new Proxy(account, {
  get(target, key, receiver) {
    return Reflect.get(target, key, receiver);
  },
});

const badChild = Object.create(badProxy);
badChild.owner = "Mina";
badChild.currency = "EUR";

const goodChild = Object.create(goodProxy);
goodChild.owner = "Mina";
goodChild.currency = "EUR";

console.log(badChild.label);
console.log(goodChild.label);

base:USD
Mina:EUR

badProxy 明确把 target 当作接收者，所以 getter 读取基础对象的字段。goodProxy 保留最初的 goodChild，getter 因而读取子对象自己的字段。这类错误在只测试 proxy.label 时不会暴露，必须加入继承或访问器用例。

这里没有 set trap，但对子对象赋值仍会通过代理原型的默认 [[Set]] 转发，并最终在子对象上创建自有属性。若 handler 添加 set trap，传给 Reflect.set() 的 receiver 仍应是原始接收者。

让虚拟属性参与反射

仅实现 get 会让 invoice.total 可读，却让 "total" in invoice 和 Object.keys(invoice) 否认它存在。下面的 handler 同时定义读取、存在性、键列表和属性描述符，让常用观察方式得到一致结果。

function withTotal(invoice) {
  const totalKey = "total";
  if (Reflect.has(invoice, totalKey)) {
    throw new TypeError("total already exists");
  }

  return new Proxy(invoice, {
    get(target, key, receiver) {
      if (key === totalKey) {
        return receiver.quantity * receiver.unitPrice;
      }
      return Reflect.get(target, key, receiver);
    },
    has(target, key) {
      return key === totalKey || Reflect.has(target, key);
    },
    ownKeys(target) {
      return [...Reflect.ownKeys(target), totalKey];
    },
    getOwnPropertyDescriptor(target, key) {
      if (key === totalKey) {
        return { configurable: true, enumerable: true };
      }
      return Reflect.getOwnPropertyDescriptor(target, key);
    },
  });
}

const invoice = withTotal({ quantity: 3, unitPrice: 25 });
console.log(invoice.total);
console.log("total" in invoice);
console.log(Object.keys(invoice).join(", "));
console.log(JSON.stringify(invoice));

75
true
quantity, unitPrice, total
{"quantity":3,"unitPrice":25,"total":75}

Object.keys() 先取得 ownKeys，再只保留描述符为可枚举的字符串键。JSON.stringify() 也会通过这些观察路径读取值，所以它包含 total。不同消费者采用不同反射操作，这正是虚拟对象必须定义一致表面的原因。

虚拟描述符声明 configurable: true，因为目标上没有不可配置的 total 属性可支撑更强声明。若之后调用 Object.preventExtensions() 禁止目标扩展，继续报告额外键会违反不变量；生产实现需要规定并测试这个状态转换。

撤销一个临时视图

Proxy.revocable() 返回代理和撤销函数。撤销后，代理上的基本操作都会失败，但目标对象及其其他别名仍然有效。

function openReadOnlySession(record) {
  const { proxy, revoke } = Proxy.revocable(record, {
    set() {
      throw new TypeError("read-only session");
    },
  });
  return { view: proxy, close: revoke };
}

const record = { id: "job-7", status: "open" };
const { view, close } = openReadOnlySession(record);

console.log(view.status);
try {
  view.status = "closed";
} catch (error) {
  console.log(error.message);
}

close();
try {
  console.log(view.id);
} catch (error) {
  console.log(error.name);
}

record.status = "closed";
console.log(record.status);

open
read-only session
TypeError
closed

撤销是代理能力的生命周期控制，不是资源清理协议。它不会关闭文件、取消计时器、擦除目标数据，也不会让已有的目标别名失效。资源所有者仍需提供并调用明确的清理操作。

只实现 set 也不等于完整只读。调用方仍可能通过 defineProperty、deleteProperty、原型 setter，或者目标别名修改状态。真实的只读契约必须列出允许的操作，覆盖相关 trap，并控制目标如何暴露。

陷阱

丢失 receiver

修复方法： 转发时保留 trap 收到的 receiver，并用继承自代理的对象测试访问器。只有契约明确要求把方法或访问器固定到目标时才改变接收者，同时记录对象标识和封装边界的变化。

把一个 trap 当作完整策略

修复方法： 根据威胁模型和调用方 API 建立操作矩阵。对赋值、Object.defineProperty()、删除、in、Object.keys()、Reflect.ownKeys() 与描述符查询分别测试，不能把代理当作真正安全边界时就不要这样宣传。

违反不变量

修复方法： 尽量从相应 Reflect 结果开始做最小变换。用不可写且不可配置的数据属性、无 setter 的访问器和 Object.preventExtensions() 目标运行测试，并把抛错视为 handler 缺陷，而不是调用方随机失败。

无条件报告写入成功

修复方法： 拒绝写入时抛出领域明确的错误，允许写入时返回 Reflect.set() 的真实布尔结果。测试不可写属性与不可扩展目标，并断言最终描述符或值，而不只断言“没有抛错”。

代理带品牌检查的对象

修复方法： 不要假定空 handler 对所有对象都透明。为必须支持的具体类型写显式适配器；若把方法绑定到目标，要测试方法标识、回调传递、链式返回和目标是否因此越过代理边界。

把撤销当作销毁

修复方法： 把访问撤销和资源生命周期设计成两个明确协议。清理函数负责关闭或取消资源，撤销函数负责拒绝后续代理操作；测试两条路径的调用顺序与重复调用行为。

延伸阅读

• ECMAScript 语言规范：Proxy Objects
• ECMAScript 语言规范：The Reflect Object
• MDN：Proxy
• MDN：Reflect
• MDN：handler.get()