Proxy 与 Reflect

本文是 FANDEX JavaScript 模块的核心理论文档之一,定位为 MIT 6.S081 / Stanford CS107 / CMU 15-410 级别的工程教学材料,涵盖 Proxy 的形式语义、代理不变量、Reflect 设计哲学、Vue 3 响应式实现等。

0. 学习导览

0.1 学习路径

元编程基础 → Proxy 基础 → 13 种陷阱 → Reflect API → 代理不变量 → 实战模式 → Vue 3 响应式 → MobX → 性能调优

0.2 前置知识

• 熟悉 JavaScript 对象模型与原型链
• 理解 getter/setter 与属性描述符
• 了解 Object.defineProperty
• 了解 ES6 Symbol

0.3 阅读建议

• 第一遍:基础语法、13 种陷阱快速过一遍
• 第二遍:代理不变量章节,理解引擎约束
• 第三遍:Vue 3 与 MobX 实现分析

1. 历史动机与技术演进

1.1 元编程的三个层次

1.2 Proxy 演进史

1.3 关键人物与论文

• Mark S. Miller(Google):Secure ECMAScript (SES) 作者,Proxy 设计的安全导向者
• Tom Van Cutsem(KU Leuven):TC39 Proxy 规范作者,多项学术论文
• Evan You:Vue.js 作者,Vue 3 用 Proxy 重构响应式系统
• Michel Weststrate:MobX 作者,基于 Proxy 的可观察对象实现

1.4 Proxy 解决的问题

在 Proxy 出现前,JavaScript 的元编程能力有限:

1. Object.defineProperty 只能拦截单个属性的 get/set,无法拦截 in、delete、keys 等
2. 数组的 push/pop/splice 等方法无法被监听(Vue 2 需重写数组方法)
3. 无法拦截 Object.keys、Object.getOwnPropertyNames
4. 无法代理函数调用(apply)和构造(construct)
5. 无法在对象层面”虚拟化”一个不存在的对象

Proxy 提供了 13 种陷阱,几乎覆盖所有对象操作,实现完整的元编程介入。

2. 形式化定义

2.1 Proxy 的形式语义

定义 Proxy 对象 $P$ 为一个三元组 $\langle T, H, R \rangle$:

• $T$:目标对象(target),被代理的对象
• $H$:处理器对象(handler),包含陷阱函数
• $R$:接收者(receiver),操作的目标对象(通常为 $P$ 本身或继承链上的对象)

形式化地,代理操作 $\text{op}$ 在 $P$ 上的求值:

2.2 代理不变量(Invariants)

代理不变量是 ECMA-262 规范定义的约束,即使陷阱函数返回值”违反”语义,引擎也会强制满足不变量,抛出 TypeError。

定义不变量集合 $\mathcal{I}$,每个不变量 $I \in \mathcal{I}$ 是一个谓词:

陷阱返回值 $r$ 必须满足:

否则抛出 TypeError。

2.3 Reflect 的形式语义

Reflect 是一个对象,其每个方法 $m$ 对应一个内部操作 $\text{op}_m$:

即 Reflect 方法是”默认行为”的可调用形式,与 Proxy 陷阱对称:

2.4 13 种代理陷阱

2.5 状态模型

Proxy 对象有内部插槽 [[ProxyHandler]]、[[ProxyTarget]]、[[Revoked]]:

可撤销代理通过 Proxy.revocable 创建,revoke() 将 revoked 置为 true,后续任何陷阱调用都抛出 TypeError。

3. Proxy 基础语法

3.1 创建代理

// 基本代理:日志记录
const target = { name: 'Alice', age: 25 };
const handler = {
  get(target, prop, receiver) {
    console.log(`[GET] ${String(prop)}`);
    return Reflect.get(target, prop, receiver);
  },
  set(target, prop, value, receiver) {
    console.log(`[SET] ${String(prop)} = ${value}`);
    return Reflect.set(target, prop, value, receiver);
  },
};

const proxy = new Proxy(target, handler);

console.log(proxy.name);  // [GET] name → Alice
proxy.age = 30;            // [SET] age = 30
console.log(proxy.age);    // [GET] age → 30

3.2 空 handler(透明代理)

const target = { x: 1 };
const proxy = new Proxy(target, {});

console.log(proxy.x);   // 1(转发到 target)
proxy.y = 2;
console.log(target.y);  // 2(写入穿透到 target)

3.3 可撤销代理

const { proxy, revoke } = Proxy.revocable({ x: 1 }, {
  get(t, p) { return t[p] * 10; }
});

console.log(proxy.x); // 10
revoke();
try {
  console.log(proxy.x);
} catch (e) {
  console.log(e.name); // TypeError
}

应用场景:

• 临时暴露内部对象,使用后撤销
• 安全沙箱:不允许外部继续访问
• 模块封装:防止外部修改

4. 13 种陷阱详解

4.1 get

const proxy = new Proxy({ a: 1 }, {
  get(target, prop, receiver) {
    // prop 可能是 string 或 symbol
    console.log(`读取 ${String(prop)}`);
    // receiver 是属性访问的接收者(可能是代理本身或继承链上的对象)
    return Reflect.get(target, prop, receiver);
  }
});

proxy.a;        // 读取 a
proxy['b'];     // 读取 b
proxy[Symbol()]; // 读取 Symbol(...)

关键点:必须传 receiver,否则 target 上的 getter 会以 target 为 this 调用,而不是 proxy。

4.2 set

const proxy = new Proxy({}, {
  set(target, prop, value, receiver) {
    if (prop === 'age' && typeof value !== 'number') {
      throw new TypeError('age must be number');
    }
    return Reflect.set(target, prop, value, receiver);
  }
});

proxy.age = 25;          // OK
proxy.age = '25';        // TypeError

4.3 has

const proxy = new Proxy({ _secret: 'x', public: 'y' }, {
  has(target, prop) {
    if (prop.startsWith('_')) return false;
    return Reflect.has(target, prop);
  }
});

console.log('public' in proxy);  // true
console.log('_secret' in proxy); // false

注意:has 陷阱不影响 Object.keys,只影响 in 运算符和 with 语句。

4.4 deleteProperty

const proxy = new Proxy({ a: 1, _b: 2 }, {
  deleteProperty(target, prop) {
    if (prop.startsWith('_')) {
      throw new Error(`Cannot delete ${String(prop)}`);
    }
    return Reflect.deleteProperty(target, prop);
  }
});

delete proxy.a;        // OK
delete proxy._b;       // Error

4.5 ownKeys

const proxy = new Proxy({ a: 1, b: 2, _c: 3 }, {
  ownKeys(target) {
    return Reflect.ownKeys(target).filter(k => !k.startsWith('_'));
  }
});

console.log(Object.keys(proxy));      // ['a', 'b']
console.log(Object.getOwnPropertyNames(proxy)); // ['a', 'b']
console.log(Object.entries(proxy));  // [['a', 1], ['b', 2]]

注意:ownKeys 必须返回数组,且必须包含所有不可配置属性的键,否则抛出 TypeError(不变量约束)。

4.6 getOwnPropertyDescriptor

const proxy = new Proxy({}, {
  getOwnPropertyDescriptor(target, prop) {
    console.log(`descriptor for ${String(prop)}`);
    return Reflect.getOwnPropertyDescriptor(target, prop);
  }
});

Object.getOwnPropertyDescriptor(proxy, 'a');

4.7 defineProperty

const proxy = new Proxy({}, {
  defineProperty(target, prop, descriptor) {
    if (descriptor.value === undefined && !descriptor.get) {
      throw new Error('Must provide value or getter');
    }
    return Reflect.defineProperty(target, prop, descriptor);
  }
});

Object.defineProperty(proxy, 'a', { value: 1, enumerable: true }); // OK
Object.defineProperty(proxy, 'b', { enumerable: true });             // Error

4.8 getPrototypeOf

const baseProto = { hello() { return 'hi'; } };
const proxy = new Proxy({}, {
  getPrototypeOf(target) {
    return baseProto;
  }
});

console.log(Object.getPrototypeOf(proxy) === baseProto); // true
console.log(proxy.hello()); // 'hi'

4.9 setPrototypeOf

const proxy = new Proxy({}, {
  setPrototypeOf(target, proto) {
    console.log('Setting prototype');
    return Reflect.setPrototypeOf(target, proto);
  }
});

Object.setPrototypeOf(proxy, { x: 1 });
console.log(proxy.x); // 1

4.10 isExtensible

const proxy = new Proxy({}, {
  isExtensible(target) {
    return Reflect.isExtensible(target);
  }
});

console.log(Object.isExtensible(proxy)); // true

不变量:isExtensible 必须返回与 target 实际可扩展性一致的结果。

4.11 preventExtensions

const proxy = new Proxy({}, {
  preventExtensions(target) {
    console.log('Preventing extensions');
    return Reflect.preventExtensions(target);
  }
});

Object.preventExtensions(proxy);
proxy.x = 1; // 失败(非严格模式静默失败,严格模式抛错)

4.12 apply(仅函数目标)

function sum(a, b) { return a + b; }

const proxy = new Proxy(sum, {
  apply(target, thisArg, args) {
    console.log(`Calling sum with ${args}`);
    return Reflect.apply(target, thisArg, args);
  }
});

proxy(1, 2); // Calling sum with 1,2 → 3

4.13 construct(仅函数目标)

function Person(name) { this.name = name; }

const ProxyPerson = new Proxy(Person, {
  construct(target, args, newTarget) {
    console.log(`Constructing Person with ${args}`);
    return Reflect.construct(target, args, newTarget);
  }
});

const p = new ProxyPerson('Alice'); // Constructing Person with Alice
console.log(p.name); // Alice

5. Reflect API 设计哲学

5.1 三个设计目标

1. 将内部操作暴露为 API:如 [[Get]] 暴露为 Reflect.get
2. 与 Proxy 陷阱对称:每个陷阱有同名 Reflect 方法
3. 统一返回值语义:操作成功返回 true,失败返回 false(而非抛错)

5.2 Reflect 与 Object 的对比

// Object.defineProperty 抛错版本
try {
  Object.defineProperty({}, 'a', { value: 1 });
} catch (e) { /* ... */ }

// Reflect.defineProperty 返回布尔
if (!Reflect.defineProperty({}, 'a', { value: 1 })) {
  // 处理失败
}

5.3 Reflect 的应用场景

5.3.1 在 Proxy 陷阱中转发默认行为

new Proxy(target, {
  get(t, p, r) {
    // 前置逻辑
    const result = Reflect.get(t, p, r); // 默认行为
    // 后置逻辑
    return result;
  }
});

5.3.2 替代 Function.prototype.apply

// 旧方式
Function.prototype.apply.call(Math.max, null, [1, 2, 3]);

// 新方式
Reflect.apply(Math.max, null, [1, 2, 3]);

5.3.3 安全的属性操作

// Reflect.set 返回布尔,不会因不可写而抛错
const obj = Object.freeze({ a: 1 });
console.log(Reflect.set(obj, 'a', 2)); // false
console.log(Object.keys(obj));         // ['a']

5.3.4 与 new 搭配

// Reflect.construct 允许指定 new.target
function Parent() {}
function Child() { Reflect.construct(Parent, [], new.target); }

5.4 Reflect 完整方法列表

6. 代理不变量(Invariants)

代理不变量是规范定义的约束,确保代理不会破坏 JavaScript 对象模型的基本规则。

6.1 get 陷阱的不变量

const target = Object.freeze({ a: 1 });
const proxy = new Proxy(target, {
  get() { return 999; } // 违反不变量
});

console.log(proxy.a); // TypeError: 'get' on proxy: property 'a' is a read-only and non-configurable data property on the proxy target

6.2 set 陷阱的不变量

const target = Object.freeze({ a: 1 });
const proxy = new Proxy(target, {
  set() { return true; } // 声称成功,但实际没改
});

proxy.a = 2;
console.log(proxy.a); // 1(不变量阻止修改)

6.3 has 陷阱的不变量

6.4 getPrototypeOf 不变量

6.5 ownKeys 不变量

const target = Object.freeze({ a: 1, b: 2 });
const proxy = new Proxy(target, {
  ownKeys() { return ['c']; } // 缺少不可配置的 a、b
});

Object.keys(proxy); // TypeError

6.6 不变量的设计动机

不变量保证代理对象”语义透明”:

• 即使代理完全自定义陷阱,外部代码仍能依赖对象模型的基本假设
• 防止恶意代理”伪装”成普通对象却行为异常
• 是 Secure ECMAScript (SES) 的基础

7. 实战模式

7.1 响应式数据(简化版 Vue 3)

/**
 * 响应式数据:简化版 Vue 3 reactive
 * @param {Object} obj - 原始对象
 * @param {Function} onChange - 属性变化回调
 * @returns {Proxy} 响应式代理
 */
function reactive(obj, onChange) {
  const deps = new Map(); // 属性 → 依赖集合(简化版)

  function track(prop) {
    if (!deps.has(prop)) deps.set(prop, new Set());
    // 实际场景:此处收集当前正在执行的 effect
  }

  function trigger(prop) {
    onChange(prop);
  }

  return new Proxy(obj, {
    get(target, prop, receiver) {
      track(prop);
      const value = Reflect.get(target, prop, receiver);
      // 深层代理:对对象属性递归包装
      if (value && typeof value === 'object') {
        return reactive(value, onChange);
      }
      return value;
    },
    set(target, prop, value, receiver) {
      const oldValue = target[prop];
      const result = Reflect.set(target, prop, value, receiver);
      if (oldValue !== value) trigger(prop);
      return result;
    },
    deleteProperty(target, prop) {
      const result = Reflect.deleteProperty(target, prop);
      trigger(prop);
      return result;
    }
  });
}

const state = reactive({ count: 0, user: { name: 'Alice' } }, (prop) => {
  console.log(`Property ${String(prop)} changed`);
});

state.count++;       // Property count changed
state.user.name = 'Bob'; // Property name changed(深层)

7.2 私有属性保护

/**
 * 私有化代理:以 _ 开头的属性对外不可见
 */
function privatize(obj) {
  return new Proxy(obj, {
    get(target, prop) {
      if (typeof prop === 'string' && prop.startsWith('_')) {
        throw new Error(`Cannot access private property ${prop}`);
      }
      return Reflect.get(target, prop);
    },
    set(target, prop, value) {
      if (typeof prop === 'string' && prop.startsWith('_')) {
        throw new Error(`Cannot set private property ${prop}`);
      }
      return Reflect.set(target, prop, value);
    },
    has(target, prop) {
      if (typeof prop === 'string' && prop.startsWith('_')) return false;
      return Reflect.has(target, prop);
    },
    ownKeys(target) {
      return Reflect.ownKeys(target).filter(
        k => !(typeof k === 'string' && k.startsWith('_'))
      );
    },
    getOwnPropertyDescriptor(target, prop) {
      if (typeof prop === 'string' && prop.startsWith('_')) return undefined;
      return Reflect.getOwnPropertyDescriptor(target, prop);
    }
  });
}

const obj = privatize({ public: 1, _private: 2 });
console.log(obj.public);       // 1
console.log(obj._private);     // Error
console.log('_private' in obj); // false
console.log(Object.keys(obj)); // ['public']

7.3 对象验证

/**
 * 类型验证代理
 */
function validated(schema) {
  const obj = {};
  return new Proxy(obj, {
    set(target, prop, value) {
      const rule = schema[prop];
      if (!rule) throw new Error(`Unknown property ${String(prop)}`);
      if (!rule.validate(value)) {
        throw new TypeError(`${String(prop)}: ${rule.message}`);
      }
      return Reflect.set(target, prop, value);
    },
    get(target, prop) {
      if (!(prop in target)) throw new Error(`Property ${String(prop)} not set`);
      return Reflect.get(target, prop);
    }
  });
}

const user = validated({
  name: {
    validate: v => typeof v === 'string' && v.length > 0,
    message: 'must be non-empty string'
  },
  age: {
    validate: v => Number.isInteger(v) && v >= 0 && v < 150,
    message: 'must be integer 0-149'
  }
});

user.name = 'Alice'; // OK
user.age = 25;       // OK
user.age = -1;       // TypeError
user.age = 'old';    // TypeError
user.x = 1;          // Error: Unknown property x

7.4 虚拟对象(动态属性)

/**
 * 虚拟对象:属性不存在于 target 上,由陷阱动态计算
 */
const virtualArray = new Proxy({}, {
  get(target, prop) {
    if (prop === 'length') return 100;
    if (/^\d+$/.test(prop)) return parseInt(prop, 10) * 2;
    return Reflect.get(target, prop);
  },
  has(target, prop) {
    return /^\d+$/.test(prop) || prop === 'length';
  },
  ownKeys() {
    return ['length', ...Array.from({ length: 100 }, (_, i) => String(i))];
  },
  getOwnPropertyDescriptor(target, prop) {
    if (/^\d+$/.test(prop) || prop === 'length') {
      return { configurable: true, enumerable: true, value: this.get(target, prop) };
    }
    return undefined;
  }
});

console.log(virtualArray[5]);   // 10
console.log(virtualArray.length); // 100
console.log(Object.keys(virtualArray).length); // 101

7.5 函数包装(缓存、防抖)

/**
 * 函数缓存代理
 */
function memoize(fn) {
  const cache = new Map();
  return new Proxy(fn, {
    apply(target, thisArg, args) {
      const key = JSON.stringify(args);
      if (cache.has(key)) {
        console.log('cache hit');
        return cache.get(key);
      }
      const result = Reflect.apply(target, thisArg, args);
      cache.set(key, result);
      return result;
    }
  });
}

const slowFib = memoize(function fib(n) {
  return n < 2 ? n : fib(n - 1) + fib(n - 2);
});

console.log(slowFib(40)); // 102334155(首次计算)
console.log(slowFib(40)); // 102334155(缓存命中)

7.6 单例代理

function singleton(Class) {
  let instance = null;
  return new Proxy(Class, {
    construct(target, args, newTarget) {
      if (!instance) {
        instance = Reflect.construct(target, args, newTarget);
      }
      return instance;
    }
  });
}

const Singleton = singleton(class {
  constructor() { this.id = Math.random(); }
});

const a = new Singleton();
const b = new Singleton();
console.log(a === b);     // true
console.log(a.id === b.id); // true

7.7 链式调用代理

/**
 * 自动链式调用:任何方法调用都返回包装对象
 */
function chainable(obj) {
  return new Proxy(obj, {
    get(target, prop) {
      const value = Reflect.get(target, prop);
      if (typeof value === 'function') {
        return (...args) => {
          const result = value.apply(target, args);
          // 返回 chainable 包装,允许继续链式调用
          return result === undefined ? chainable(target) : chainable(result);
        };
      }
      return chainable(value);
    }
  });
}

const list = chainable([1, 2, 3, 4]);
list
  .push(5)
  .map(x => x * 2)
  .filter(x => x > 4)
  .forEach(x => console.log(x));

8. Vue 3 响应式系统深度解析

8.1 Vue 2 的痛点

Vue 2 使用 Object.defineProperty 实现响应式,存在以下问题:

1. 无法监听新增属性:Vue.set() 是必需的
2. 无法监听删除属性:Vue.delete() 是必需的
3. 数组方法不触发响应式:需重写 push/pop/splice 等
4. 无法监听索引和 length 修改
5. 深层对象需递归遍历:初始化开销大
6. 无法监听 Map/Set

8.2 Vue 3 用 Proxy 重构

// Vue 3 reactive 简化实现
const reactiveMap = new WeakMap();

function reactive(target) {
  if (typeof target !== 'object' || target === null) return target;
  if (target.__v_isReactive) return target;
  if (reactiveMap.has(target)) return reactiveMap.get(target);

  const proxy = new Proxy(target, {
    get(target, key, receiver) {
      if (key === '__v_isReactive') return true;
      track(target, key);
      const result = Reflect.get(target, key, receiver);
      if (result && typeof result === 'object') {
        return reactive(result); // 惰性深层代理
      }
      return result;
    },
    set(target, key, value, receiver) {
      const oldValue = target[key];
      const result = Reflect.set(target, key, value, receiver);
      if (oldValue !== value) {
        trigger(target, key);
      }
      return result;
    },
    deleteProperty(target, key) {
      const result = Reflect.deleteProperty(target, key);
      trigger(target, key);
      return result;
    }
  });

  reactiveMap.set(target, proxy);
  return proxy;
}

// 依赖收集(简化)
let activeEffect = null;
const targetMap = new WeakMap();

function track(target, key) {
  if (!activeEffect) return;
  let depsMap = targetMap.get(target);
  if (!depsMap) targetMap.set(target, (depsMap = new Map()));
  let dep = depsMap.get(key);
  if (!dep) depsMap.set(key, (dep = new Set()));
  dep.add(activeEffect);
}

function trigger(target, key) {
  const depsMap = targetMap.get(target);
  if (!depsMap) return;
  const dep = depsMap.get(key);
  if (dep) dep.forEach(effect => effect());
}

function effect(fn) {
  activeEffect = fn;
  fn();
  activeEffect = null;
}

8.3 Vue 3 的优势

8.4 readonly 实现

function readonly(target) {
  return new Proxy(target, {
    get(target, key, receiver) {
      const result = Reflect.get(target, key, receiver);
      if (result && typeof result === 'object') {
        return readonly(result);
      }
      return result;
    },
    set() {
      console.warn(`Set operation on readonly failed`);
      return true;
    },
    deleteProperty() {
      console.warn(`Delete operation on readonly failed`);
      return true;
    }
  });
}

8.5 ref 实现

function ref(value) {
  return new Proxy({ value }, {
    get(target, key) {
      if (key === 'value') {
        track(target, 'value');
        const v = target.value;
        return v && typeof v === 'object' ? reactive(v) : v;
      }
      return Reflect.get(target, key);
    },
    set(target, key, newValue) {
      if (key === 'value') {
        target.value = newValue;
        trigger(target, 'value');
        return true;
      }
      return false;
    }
  });
}

8.6 computed 实现

function computed(getter) {
  let cachedValue;
  let dirty = true;

  const runner = effect(() => {
    // 当依赖变化时,标记为 dirty
    dirty = true;
    cachedValue = getter();
  });

  // 覆盖 effect 自动运行:首次不执行
  dirty = true;

  return {
    get value() {
      if (dirty) {
        cachedValue = getter();
        dirty = false;
      }
      return cachedValue;
    }
  };
}

9. MobX 代理模式分析

9.1 MobX 的 observable

MobX 5+ 使用 Proxy 实现 observable:

import { observable, action } from 'mobx';

const store = observable({
  count: 0,
  increment: action(function() {
    this.count++;
  })
});

// 自动追踪依赖
autorun(() => {
  console.log('count is:', store.count);
});

store.increment(); // 输出 "count is: 1"

9.2 MobX 的代理实现思路

function observable(target) {
  const observers = new Map();

  function observe(key, observer) {
    if (!observers.has(key)) observers.set(key, new Set());
    observers.get(key).add(observer);
  }

  function notify(key) {
    if (observers.has(key)) {
      observers.get(key).forEach(o => o());
    }
  }

  return new Proxy(target, {
    get(t, key, receiver) {
      // 收集当前 observer
      if (currentObserver) observe(key, currentObserver);
      return Reflect.get(t, key, receiver);
    },
    set(t, key, value, receiver) {
      const result = Reflect.set(t, key, value, receiver);
      notify(key);
      return result;
    }
  });
}

9.3 Vue 3 与 MobX 对比

10. 生产级代码示例

10.1 完整响应式系统

/**
 * 生产级响应式系统:支持 effect、track、trigger、cleanup
 */

// 全局状态
let activeEffect = null;
const targetMap = new WeakMap(); // target → Map<key, Set<effect>>
const effectStack = [];
const ITERATE_KEY = Symbol('iterate');

/**
 * 创建响应式对象
 */
function reactive(target) {
  if (typeof target !== 'object' || target === null) return target;
  if (target.__isReactive) return target;

  const handler = {
    get(target, key, receiver) {
      if (key === '__isReactive') return true;
      if (key === '__raw') return target;

      track(target, key);
      const result = Reflect.get(target, key, receiver);

      if (result && typeof result === 'object') {
        return reactive(result);
      }
      return result;
    },
    set(target, key, value, receiver) {
      const oldValue = target[key];
      const raw = value && value.__raw ? value.__raw : value;
      const hadKey = Array.isArray(target)
        ? Number(key) < target.length
        : Object.prototype.hasOwnProperty.call(target, key);
      const result = Reflect.set(target, key, raw, receiver);

      if (!hadKey) {
        trigger(target, key, 'add');
      } else if (oldValue !== raw && (oldValue === oldValue || raw === raw)) {
        trigger(target, key, 'set');
      }
      return result;
    },
    deleteProperty(target, key) {
      const hadKey = Object.prototype.hasOwnProperty.call(target, key);
      const result = Reflect.deleteProperty(target, key);
      if (hadKey && result) {
        trigger(target, key, 'delete');
      }
      return result;
    },
    ownKeys(target) {
      track(target, ITERATE_KEY);
      return Reflect.ownKeys(target);
    }
  };

  return new Proxy(target, handler);
}

/**
 * 依赖收集
 */
function track(target, key) {
  if (!activeEffect) return;
  let depsMap = targetMap.get(target);
  if (!depsMap) targetMap.set(target, (depsMap = new Map()));
  let dep = depsMap.get(key);
  if (!dep) depsMap.set(key, (dep = new Set()));
  if (!dep.has(activeEffect)) {
    dep.add(activeEffect);
    activeEffect.deps.push(dep);
  }
}

/**
 * 触发更新
 */
function trigger(target, key, type) {
  const depsMap = targetMap.get(target);
  if (!depsMap) return;

  const effects = new Set();
  const add = dep => dep && dep.forEach(e => effects.add(e));

  if (key !== undefined) add(depsMap.get(key));
  if (type === 'add' || type === 'delete') {
    add(depsMap.get(ITERATE_KEY));
  }

  effects.forEach(effect => {
    if (effect !== activeEffect) effect.run();
  });
}

/**
 * 副作用注册
 */
function effect(fn, options = {}) {
  const _effect = function(...args) {
    if (effectStack.includes(_effect)) return;
    try {
      effectStack.push(_effect);
      activeEffect = _effect;
      return fn(...args);
    } finally {
      effectStack.pop();
      activeEffect = effectStack[effectStack.length - 1] || null;
    }
  };
  _effect.deps = [];
  _effect.run = () => {
    // 清理旧依赖
    for (const dep of _effect.deps) dep.delete(_effect);
    _effect.deps = [];
    _effect();
  };
  if (options.lazy !== true) _effect();
  return _effect;
}

// 使用
const state = reactive({ count: 0, list: [] });

effect(() => {
  console.log('count:', state.count);
});

effect(() => {
  console.log('list length:', state.list.length);
});

state.count++;        // 触发第一个 effect
state.list.push(1);   // 触发第二个 effect

10.2 智能缓存代理

/**
 * TTL 缓存代理
 */
function ttlCache(target, ttl = 60000) {
  const cache = new Map();

  return new Proxy(target, {
    get(t, prop) {
      if (typeof t[prop] !== 'function') return Reflect.get(t, prop);

      return new Proxy(t[prop], {
        apply(target, thisArg, args) {
          const key = JSON.stringify(args);
          const now = Date.now();

          if (cache.has(key)) {
            const entry = cache.get(key);
            if (now - entry.time < ttl) {
              return entry.value;
            }
          }

          const value = Reflect.apply(target, thisArg, args);
          cache.set(key, { value, time: now });
          return value;
        }
      });
    }
  });
}

const api = ttlCache({
  async getUser(id) {
    const r = await fetch(`/api/users/${id}`);
    return r.json();
  }
}, 5000);

10.3 不可变数据结构(Immer 风格)

/**
 * Immer 风格的不可变更新
 */
function produce(state, recipe) {
  const copies = new Map();
  const proxies = new Map();

  function makeProxy(target) {
    if (proxies.has(target)) return proxies.get(target);

    const proxy = new Proxy(target, {
      get(t, prop) {
        if (prop === '__isDraft') return true;
        const value = Reflect.get(t, prop);
        if (value && typeof value === 'object') {
          return makeProxy(value);
        }
        return value;
      },
      set(t, prop, value) {
        // 写入时复制(copy-on-write)
        if (!copies.has(t)) {
          copies.set(t, Array.isArray(t) ? [...t] : { ...t });
        }
        const copy = copies.get(t);
        Reflect.set(copy, prop, value);
        return true;
      }
    });

    proxies.set(target, proxy);
    return proxy;
  }

  const draft = makeProxy(state);
  recipe(draft);

  function finalize(target) {
    if (!copies.has(target)) return target;
    const copy = copies.get(target);
    for (const key of Reflect.ownKeys(copy)) {
      if (copy[key] && typeof copy[key] === 'object') {
        copy[key] = finalize(copy[key]);
      }
    }
    return copy;
  }

  return finalize(state);
}

// 使用
const state = { user: { name: 'Alice', age: 25 }, list: [1, 2] };
const newState = produce(state, draft => {
  draft.user.name = 'Bob';
  draft.list.push(3);
});

console.log(state === newState);             // false
console.log(state.user === newState.user);   // false(被修改)
console.log(state.list === newState.list);   // false(被修改)
console.log(state.user.age);                 // 25(原状态不变)

11. 复杂度分析与正确性

11.1 性能开销

Proxy 相对于直接属性访问的开销:

实测数据(V8 8.x):

• 普通属性读取:~1ns
• Proxy get 陷阱:~30ns(30 倍慢)
• 普通属性赋值:~2ns
• Proxy set 陷阱:~50ns(25 倍慢)

11.2 内存开销

每个 Proxy 对象分配:

• Proxy 内部对象(约 32 字节)
• handler 对象(若复用则摊薄)
• WeakMap 缓存(可选)

11.3 正确性证明

定理 1:Proxy 满足 Liskov 替换原则(LSP):若 $P$ 是 $T$ 的代理,则 $P$ 可在 $T$ 的位置使用。

证明:由不变量约束:

1. get 陷阱返回值受 target 属性约束(类型一致)
2. set 陷阱的成功返回与 target 实际状态一致
3. instanceof 检查通过 [[Prototype]] 内部插槽

但需注意:

• proxy instanceof T 检查原型链,返回 true
• Object.getPrototypeOf(proxy) 返回 target 的原型

定理 2:Reflect 方法是 Proxy 陷阱的右恒等元:

证明:由规范定义,每个 Reflect 方法的实现就是对应内部操作的默认行为,与陷阱未定义时的回退行为一致。

12. 对比分析

12.1 Proxy vs Object.defineProperty

12.2 Proxy vs Object.observe(废弃)

ES7 草案曾提出 Object.observe,允许监听对象变化,但 2015 年被废弃,原因:

• 性能开销大
• 用例有限,Proxy 已覆盖
• 与 Proxy 重复

12.3 Proxy vs AOP(面向切面)

AOP(Aspect-Oriented Programming)在 Java 等语言中通过字节码增强实现横切关注点。JS 中 Proxy 提供了类似的”方法拦截”能力,但更轻量:

// AOP 风格:日志切面
function logAspect(fn) {
  return new Proxy(fn, {
    apply(target, thisArg, args) {
      console.log(`[LOG] Calling ${target.name} with`, args);
      const start = Date.now();
      try {
        const result = Reflect.apply(target, thisArg, args);
        console.log(`[LOG] Returned`, result, `in ${Date.now() - start}ms`);
        return result;
      } catch (e) {
        console.error(`[LOG] Threw`, e);
        throw e;
      }
    }
  });
}

13. 常见陷阱与 Bug

13.1 陷阱:receiver 丢失导致 getter this 错误

const obj = {
  _value: 1,
  get value() { return this._value; }
};

const proxy = new Proxy(obj, {
  get(target, prop) {
    // 错误:不传 receiver,getter 中的 this 是 target,不是 proxy
    return Reflect.get(target, prop);
    // 正确:return Reflect.get(target, prop, receiver);
  }
});

const child = Object.create(proxy);
child._value = 2;
console.log(child.value); // 1(错误!应该是 2)

13.2 陷阱:深层代理每次创建新对象

function reactive(obj) {
  return new Proxy(obj, {
    get(target, prop) {
      const v = target[prop];
      if (v && typeof v === 'object') {
        return reactive(v); // 每次访问都创建新 Proxy!性能问题
      }
      return v;
    }
  });
}

const state = reactive({ user: { name: 'Alice' } });
state.user === state.user; // false!两个不同的 Proxy

修复:用 WeakMap 缓存:

const proxyMap = new WeakMap();
function reactive(obj) {
  if (proxyMap.has(obj)) return proxyMap.get(obj);
  const proxy = new Proxy(obj, { /* ... */ });
  proxyMap.set(obj, proxy);
  return proxy;
}

13.3 陷阱:has 不影响 Object.keys

const proxy = new Proxy({ a: 1, _b: 2 }, {
  has(t, p) { return !p.startsWith('_'); }
});

'_b' in proxy;            // false
Object.keys(proxy);       // ['a', '_b']!_b 仍然出现

需要同时拦截 ownKeys:

const proxy = new Proxy({ a: 1, _b: 2 }, {
  has(t, p) { return !p.startsWith('_') && Reflect.has(t, p); },
  ownKeys(t) {
    return Reflect.ownKeys(t).filter(k => !k.startsWith('_'));
  }
});

13.4 陷阱:Proxy 包装原始值

const proxy = new Proxy(42, {}); // TypeError: Cannot create proxy with a non-object as target

Proxy 只能代理对象,不能代理原始值。Vue 3 的 ref 用于包装原始值。

13.5 陷阱:JSON.stringify 不触发代理

const target = { a: 1 };
const proxy = new Proxy(target, {
  ownKeys() { return ['a', 'b']; } // 声称有 b,但 target 没有
});

JSON.stringify(proxy); // {"a":1}(JSON 只序列化实际存在的属性)

13.6 陷阱:Symbol 元数据泄漏

const proxy = new Proxy({}, {
  get(t, p) {
    console.log('accessed:', p);
    return Reflect.get(t, p);
  }
});

// 一些库会探测内部 Symbol
proxy[Symbol.toStringTag]; // 触发陷阱

修复:白名单过滤:

const allowed = new Set(['a', 'b', 'c']);
new Proxy({}, {
  get(t, p) {
    if (typeof p === 'string' && !allowed.has(p)) return undefined;
    return Reflect.get(t, p);
  }
});

13.7 Bug 案例:Vue 2 数组响应式

// Vue 2 的数组问题
const vm = new Vue({
  data: { list: [1, 2, 3] }
});

vm.list[0] = 99;       // 不触发响应式!
vm.list.length = 0;    // 不触发响应式!
vm.list.push(4);       // 触发(重写了 push)

Vue 3 用 Proxy 解决:

const { reactive } = Vue;
const state = reactive({ list: [1, 2, 3] });

state.list[0] = 99;    // 触发响应式
state.list.length = 0; // 触发响应式

13.8 Bug 案例:循环引用

const obj = { a: 1 };
obj.self = obj;

const proxy = new Proxy(obj, {
  get(t, p) {
    console.log('accessed:', p);
    return Reflect.get(t, p);
  }
});

// 任何深度遍历(如 JSON.stringify)都会无限递归

修复:WeakSet 记录已访问对象:

const seen = new WeakSet();
function safeStringify(obj) {
  return JSON.stringify(obj, (key, value) => {
    if (typeof value === 'object' && value !== null) {
      if (seen.has(value)) return '[Circular]';
      seen.add(value);
    }
    return value;
  });
}

14. 性能调优

14.1 何时使用 Proxy

推荐:

• 框架级响应式系统
• API 拦截/日志/监控
• 不可变数据(Immer)
• 验证层
• 虚拟对象

避免:

• 性能敏感的紧密循环
• 简单属性访问
• 兼容 IE 的项目

14.2 优化技巧

1. 复用 handler:多个代理共享同一 handler

const handler = {
  get(t, p, r) { /* ... */ return Reflect.get(t, p, r); }
};

const proxy1 = new Proxy(obj1, handler);
const proxy2 = new Proxy(obj2, handler); // 共享

2. WeakMap 缓存:避免重复代理同一对象

const cache = new WeakMap();
function getProxy(obj) {
  if (!cache.has(obj)) cache.set(obj, new Proxy(obj, handler));
  return cache.get(obj);
}

3. 避免深层代理:用 shallowRef / shallowReactive

function shallowReactive(obj) {
  return new Proxy(obj, {
    get(t, p, r) { return Reflect.get(t, p, r); }, // 不递归
    set(t, p, v, r) {
      const result = Reflect.set(t, p, v, r);
      trigger();
      return result;
    }
  });
}

4. 预计算:对静态属性,在 get 陷阱外预先读取

14.3 性能基准

function bench(obj, iterations = 1e6) {
  let sum = 0;
  for (let i = 0; i < iterations; i++) {
    sum += obj.x;
  }
  return sum;
}

const plain = { x: 1 };
const proxied = new Proxy(plain, {
  get(t, p, r) { return Reflect.get(t, p, r); }
});

// V8 8.x 典型结果
console.time('plain');
bench(plain);
console.timeEnd('plain');   // ~3ms

console.time('proxy');
bench(proxied);
console.timeEnd('proxy');   // ~30ms(约 10 倍慢)

15. 案例研究

15.1 案例:Vue 3 reactive

(已在第 8 章详述)

15.2 案例:MobX 5

MobX 5 用 Proxy 替代了 MobX 4 的 defineProperty:

import { observable } from 'mobx';

const store = observable.object({
  count: 0,
  get double() { return this.count * 2; },
  increment() { this.count++; }
});

// 自动追踪
mobx.autorun(() => {
  console.log('double:', store.double);
});

store.increment(); // 输出 double: 2

15.3 案例:Immer

Immer 用 Proxy 实现 copy-on-write 不可变更新:

import produce from 'immer';

const state = { user: { name: 'Alice' } };
const next = produce(state, draft => {
  draft.user.name = 'Bob';
});

console.log(state !== next);          // true
console.log(state.user !== next.user); // true
console.log(state.user.name);         // 'Alice'(原状态不变)

15.4 案例:Solid.js

Solid.js 用 Proxy 实现细粒度响应式:

import { createSignal, createEffect } from 'solid-js';

const [count, setCount] = createSignal(0);
createEffect(() => {
  console.log('count:', count());
});

setCount(1); // 输出 "count: 1"

注意:Solid.js 不用 Proxy 包装对象,而是用 Proxy 包装函数(signal)。

15.5 案例:ESLint

ESLint 用 Proxy 拦截 scope 对象:

const scope = new Proxy({}, {
  get(t, p) {
    if (p in t) return t[p];
    throw new ReferenceError(`${p} is not defined`);
  }
});

15.6 案例:Secure ECMAScript (SES)

SES 用 Proxy 创建安全沙箱:

import { lockdown } from 'ses';

lockdown();

const sandbox = new Proxy({}, {
  get(t, p) {
    if (p === 'eval') return eval; // 仅暴露白名单
    return undefined;
  }
});

16. 高级主题

16.1 代理函数

// 函数 + 状态
function makeCounter() {
  let count = 0;
  return new Proxy(() => ++count, {
    apply(target, thisArg, args) {
      return Reflect.apply(target, thisArg, args);
    },
    get(target, prop) {
      if (prop === 'count') return count;
      return Reflect.get(target, prop);
    }
  });
}

const counter = makeCounter();
counter();        // 1
counter();        // 2
console.log(counter.count); // 2

16.2 代理类

class Logged {
  constructor() { this.x = 0; }
  inc() { this.x++; }
}

const LoggedProxy = new Proxy(Logged, {
  construct(target, args, newTarget) {
    const instance = Reflect.construct(target, args, newTarget);
    return new Proxy(instance, {
      get(t, p, r) {
        const v = Reflect.get(t, p, r);
        if (typeof v === 'function') {
          return (...args) => {
            console.log(`Calling ${String(p)}`);
            return v.apply(t, args);
          };
        }
        return v;
      }
    });
  }
});

const obj = new LoggedProxy();
obj.inc(); // Calling inc

16.3 多重代理

const target = { x: 1 };

const logged = new Proxy(target, {
  get(t, p, r) {
    console.log('log:', p);
    return Reflect.get(t, p, r);
  }
});

const validated = new Proxy(logged, {
  get(t, p, r) {
    if (p === 'secret') throw new Error('forbidden');
    return Reflect.get(t, p, r);
  }
});

validated.x; // log: x → 1
validated.secret; // Error

注意:多重代理的性能开销线性叠加。

16.4 异步代理(实验性)

Proxy 是同步的,无法直接代理 Promise。但可以代理 thenable:

function asyncProxy(promise) {
  return new Proxy(promise, {
    get(target, prop) {
      if (prop === 'then' || prop === 'catch') {
        return target[prop].bind(target);
      }
      // 返回一个新的 asyncProxy,链式访问
      return asyncProxy(target.then(v => v && v[prop]));
    }
  });
}

const data = asyncProxy(fetch('/api/data').then(r => r.json()));
data.user.name.then(console.log); // 链式访问

16.5 Proxy 与 WeakMap

WeakMap 是 Proxy 的天然搭档,因为:

• WeakMap 的键必须是对象
• Proxy 通常是对象
• WeakMap 不阻止 GC,适合缓存

const metadata = new WeakMap();

function addMetadata(obj, data) {
  metadata.set(obj, data);
}

const proxy = new Proxy(obj, {
  get(t, p) {
    const data = metadata.get(t);
    if (data && p === '__meta') return data;
    return Reflect.get(t, p);
  }
});

17. 测试策略

17.1 单元测试陷阱

const assert = require('assert');

const proxy = new Proxy({ a: 1 }, {
  get(t, p) { return Reflect.get(t, p); }
});

// 深度相等
assert.deepStrictEqual(proxy, { a: 1 }); // 通过

// 引用相等
assert.strictEqual(proxy, proxy); // 通过

// 但是
assert.strictEqual(proxy, { a: 1 }); // 失败(不同对象)

17.2 测试响应式系统

describe('reactive', () => {
  it('应在属性变化时触发 effect', () => {
    const state = reactive({ count: 0 });
    const calls = [];
    effect(() => calls.push(state.count));

    state.count = 1;
    assert.deepStrictEqual(calls, [0, 1]);
  });

  it('应支持深层代理', () => {
    const state = reactive({ user: { name: 'A' } });
    let lastName;
    effect(() => { lastName = state.user.name; });

    state.user.name = 'B';
    assert.strictEqual(lastName, 'B');
  });

  it('应支持数组', () => {
    const state = reactive({ list: [] });
    let length;
    effect(() => { length = state.list.length; });

    state.list.push(1);
    assert.strictEqual(length, 1);
  });
});

17.3 测试不变量

describe('proxy invariants', () => {
  it('不可配置属性 get 陷阱受约束', () => {
    const target = Object.freeze({ a: 1 });
    const proxy = new Proxy(target, {
      get() { return 999; }
    });

    assert.throws(() => proxy.a, TypeError);
  });

  it('ownKeys 必须包含不可配置属性', () => {
    const target = Object.freeze({ a: 1 });
    const proxy = new Proxy(target, {
      ownKeys() { return ['b']; }
    });

    assert.throws(() => Object.keys(proxy), TypeError);
  });
});

18. 调试技巧

18.1 检测代理

function isProxy(obj) {
  // 通过自定义 Symbol 检测
  // 注意:Proxy 没有标准 API 检测
  return obj && typeof obj === 'object' && obj.__isProxy === true;
}

// 在 handler 中标记
new Proxy(target, {
  get(t, p) {
    if (p === '__isProxy') return true;
    return Reflect.get(t, p);
  }
});

18.2 获取原始对象

const raw = Symbol('raw');
function reactive(obj) {
  return new Proxy(obj, {
    get(t, p) {
      if (p === raw) return t;
      return Reflect.get(t, p);
    }
  });
}

const state = reactive({ a: 1 });
console.log(state[raw]); // 原始对象

18.3 调试 handler

function debugHandler(label) {
  return {
    get(t, p, r) {
      const v = Reflect.get(t, p, r);
      console.log(`[${label}] get ${String(p)} →`, v);
      return v;
    },
    set(t, p, v, r) {
      console.log(`[${label}] set ${String(p)} =`, v);
      return Reflect.set(t, p, v, r);
    },
    has(t, p) {
      console.log(`[${label}] has ${String(p)}`);
      return Reflect.has(t, p);
    },
    deleteProperty(t, p) {
      console.log(`[${label}] delete ${String(p)}`);
      return Reflect.deleteProperty(t, p);
    }
  };
}

18.4 Chrome DevTools

DevTools 中 Proxy 对象显示为 Proxy { ... },展开可看到 target 和 handler。在断点处可检查 receiver。

19. 与其他语言的对比

19.1 Python 的元类与 getattr

class Logging:
    def __getattr__(self, name):
        print(f'accessing {name}')
        return super().__getattr__(name)

Python 通过 __getattr__ / __setattr__ 实现类似代理,但粒度较粗。

19.2 Ruby 的 method_missing

class Logging
  def method_missing(name, *args)
    puts "calling #{name}"
    super
  end
end

Ruby 通过 method_missing 拦截未定义方法,但只针对方法。

19.3 Smalltalk 的 doesNotUnderstand

Smalltalk 的 doesNotUnderstand: 类似 Ruby 的 method_missing。

19.4 CLOS 的元对象协议

Common Lisp Object System 的 MOP 是元编程的鼻祖,提供完整的类级别元编程能力。

19.5 Java 的动态代理

Proxy.newProxyInstance(loader, interfaces, handler);

Java 的动态代理只能代理接口,需实现 InvocationHandler。

19.6 对比表

20. 与 ECMA 规范的映射

20.1 关键规范章节

20.2 规范伪代码解读

[[Get]] 内部方法在 Proxy 上的实现(简化):

1. 若 handler.get 是 undefined,调用 target.[[Get]](P, Receiver)
2. 否则:
   a. 调用 handler.get(target, P, Receiver)
   b. 检查返回值是否满足不变量
   c. 返回结果

20.3 TC39 提案历程

• ES6 (2015):Proxy、Reflect
• ES2018:Promise.prototype.finally(使用内部 Proxy)
• ES2022:可访问 Object.hasOwn
• 提案中:Symbols as WeakMap keys(扩展 Proxy 缓存)

21. 安全考虑

21.1 信息泄漏

const target = { _secret: 'xxx' };
const proxy = new Proxy(target, {
  get(t, p) {
    if (p.startsWith('_')) return undefined;
    return Reflect.get(t, p);
  }
});

// 但还是可能通过原型链泄漏
Object.getPrototypeOf(proxy);
proxy.constructor;

21.2 安全沙箱

function createSandbox() {
  const whitelist = new Set(['Math', 'JSON', 'console']);
  return new Proxy(globalThis, {
    get(t, p) {
      if (!whitelist.has(p)) return undefined;
      return Reflect.get(t, p);
    },
    has() { return true; } // 让 with 语句认为一切都在沙箱中
  });
}

// with (createSandbox()) { /* 代码只能访问白名单全局 */ }

21.3 防御性拷贝

function defensiveCopy(obj) {
  // 用 Proxy 防止意外修改
  return new Proxy(structuredClone(obj), {
    set() { throw new Error('Immutable'); },
    deleteProperty() { throw new Error('Immutable'); }
  });
}

22. 学习路径与练习建议

22.1 渐进式学习

1. 第一周:基础语法、13 种陷阱、Reflect API
2. 第二周:代理不变量、实战模式
3. 第三周:Vue 3 响应式源码分析
4. 第四周:Immer 源码、MobX 实现
5. 第五周:自定义响应式系统

22.2 推荐练习

1. 实现一个简化的 reactive / effect / computed
2. 实现只读代理、可撤销代理
3. 实现 TTL 缓存代理
4. 实现方法装饰器(apply 陷阱)
5. 实现 Immer 风格的 produce
6. 实现私有属性保护

22.3 阅读顺序建议

1. MDN:Proxy、Reflect
2. Axel Rauschmayer《Exploring ES6》第 28 章
3. ECMA-262 §27.1-27.2
4. Vue 3 reactivity 源码
5. Immer 源码
6. Tom Van Cutsem 论文