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()