JavaScript Proxy 的 defineProperty ：精准控制属性定义

在 JavaScript 的 Proxy 体系中，handler.defineProperty() 是一个容易被忽视却很有实用价值的方法。它直接对应 Object.defineProperty() 操作，允许我们在属性被定义或修改时插入自定义逻辑。

理解这个方法，意味着你能在对象层面实现更精细的属性访问控制、属性定义校验，甚至跨浏览器的兼容性处理。

方法定义速览

handler.defineProperty() 是 Proxy 的 13 个方法之一，专门拦截对 Object.defineProperty() 的调用。

语法格式：

const proxy = new Proxy(target, {
  defineProperty: function(target, property, descriptor) {
    // 自定义逻辑
    return true; // 或 false
  }
});

返回值：必须返回一个布尔值。返回 true 表示操作成功，返回 false 表示操作失败（在严格模式下会抛出 TypeError）。

两个核心使用场景

官方资料提到这个方法主要用于两个场景，结合我自己的开发经验，再补充一个常见场景：

场景一：确保 getter/setter 的跨浏览器兼容性

早期浏览器对 Object.defineProperty 的支持参差不齐，尤其是对 get 和 set 的支持。通过 defineProperty ，我们可以统一处理属性访问器的定义逻辑，确保代码在不同环境下行为一致。

场景二：自定义属性访问器行为

比如你想在属性被定义时自动添加前缀、校验属性值类型、或者记录定义操作的日志，都可以通过这个实现。

场景三（补充）：实现只读属性的动态控制

当某个属性被定义时，根据业务规则动态决定它是否可写、是否可枚举。这在权限管理系统中很常见。

示例1：基础用法 —— 拦截属性定义并输出日志

这个示例展示如何用 defineProperty 捕获属性定义操作，并打印日志。

<script>
// 代码号：学习编程，从基础拦截开始
const target = {};

const proxy = new Proxy(target, {
  defineProperty: function(target, prop, descriptor) {
    console.log(`正在定义属性: ${prop}`);
    // 调用原始方法完成实际的定义
    return Reflect.defineProperty(target, prop, descriptor);
  }
});

// 触发
Object.defineProperty(proxy, "version", {
  value: "1.0.0",
  writable: true
});

console.log(target.version); // 1.0.0
// 控制台输出: 正在定义属性: version
</script>

示例2：属性定义时的数据校验

在项目中，我们可能需要对属性值做约束，比如限制数字范围、字符串长度等。

<script>
// 代码号：学习编程，用 defineProperty 实现属性值校验
const user = {};

const userProxy = new Proxy(user, {
  defineProperty: function(target, prop, descriptor) {
    // 针对 age 属性做校验
    if (prop === "age" && descriptor.value !== undefined) {
      if (typeof descriptor.value !== "number" || descriptor.value < 0 || descriptor.value > 150) {
        console.error(`年龄 ${descriptor.value} 无效，必须在 0-150 之间`);
        return false; // 定义失败
      }
    }
    // 针对 name 属性做校验
    if (prop === "name" && descriptor.value !== undefined) {
      if (typeof descriptor.value !== "string" || descriptor.value.length < 2) {
        console.error("姓名至少需要2个字符");
        return false;
      }
    }
    return Reflect.defineProperty(target, prop, descriptor);
  }
});

// 正常定义
Object.defineProperty(userProxy, "name", { value: "张三", writable: true });
Object.defineProperty(userProxy, "age", { value: 28, writable: true });

// 触发校验失败的场景
Object.defineProperty(userProxy, "age", { value: 200, writable: true });
// 输出: 年龄 200 无效，必须在 0-150 之间

console.log(user.age); // 28，未被修改
</script>

示例3：动态修改属性描述符

有时候我们需要在定义属性时，根据业务规则动态调整属性描述符。

<script>
// 代码号：学习编程，动态修改属性描述符
const config = {};

const configProxy = new Proxy(config, {
  defineProperty: function(target, prop, descriptor) {
    // 自动为非数字类型的属性添加不可枚举特性
    if (prop !== "id" && descriptor.value !== undefined && typeof descriptor.value !== "number") {
      descriptor.enumerable = false;
      console.log(`属性 ${prop} 被设置为不可枚举`);
    }
    return Reflect.defineProperty(target, prop, descriptor);
  }
});

Object.defineProperty(configProxy, "id", { value: 1, enumerable: true });
Object.defineProperty(configProxy, "secretKey", { value: "abc123", enumerable: true });
Object.defineProperty(configProxy, "apiUrl", { value: "https://api.example.com", enumerable: true });

console.log(Object.keys(configProxy)); // 输出: ['id']
// secretKey 和 apiUrl 被自动设置为不可枚举，不会出现在 keys 中
console.log(configProxy.secretKey); // abc123，依然可以访问
</script>

示例4：多代理场景

如你提供的原始示例所示，可以为不同的目标对象分别设置 defineProperty ，实现独立的拦截逻辑。

<script>
// 代码号：学习编程，多代理分别拦截
const objA = {};
const objB = {};

const proxyA = new Proxy(objA, {
  defineProperty: function(target, prop, descriptor) {
    console.log("代理A拦截到属性定义: " + prop);
    return Reflect.defineProperty(target, prop, descriptor);
  }
});

const proxyB = new Proxy(objB, {
  defineProperty: function(target, prop, descriptor) {
    console.log("代理B拦截到属性定义: " + prop);
    return Reflect.defineProperty(target, prop, descriptor);
  }
});

Object.defineProperty(proxyA, "foo", { value: "bar" });
Object.defineProperty(proxyB, "baz", { value: "qux" });

// 控制台输出:
// 代理A拦截到属性定义: foo
// 代理B拦截到属性定义: baz
</script>

与 set 的区别（个人经验分享）

很多初学者会混淆 defineProperty 和 set 。简单来说：

• set：拦截直接属性赋值，如 proxy.name = "张三"。

• defineProperty：拦截通过 Object.defineProperty() 进行的属性定义或修改。

我遇到过这样一个场景：某第三方库内部大量使用 Object.defineProperty 来定义属性，而我们想在这些属性定义时统一添加日志。如果用 set 拦截不到，必须用 defineProperty。所以理解这两个方法的区别，在调试和扩展第三方代码时很有帮助。

本节课程知识要点

1. 返回值必须正确：defineProperty 必须返回一个布尔值。返回 true 表示操作成功，返回 false 表示失败。如果返回 false 且代码运行在严格模式下，会抛出 TypeError。

2. 使用 Reflect.defineProperty 保留默认行为：在内部，推荐通过 Reflect.defineProperty(target, property, descriptor) 来执行原始的定义操作，避免重复实现底层逻辑。

3. 描述符的完整性：传入的 descriptor 对象可能只包含部分属性（如只有 value 没有 writable）。在自定义逻辑中，需要知道 writable、enumerable、configurable 的默认值都是 false，这与直接赋值的行为不同。

4. 不能拦截直接属性赋值：defineProperty 只拦截 Object.defineProperty() 调用，不拦截 obj.prop = value 这种赋值操作。如需同时拦截两者，需要同时实现 set 和 defineProperty。

handler.defineProperty() 是 Proxy 体系中较为底层的一个方法，但它能让你在属性定义层面获得精细的控制力。无论是做权限校验、数据规范、还是兼容性处理，它都是一个值得掌握的工具。在代码号学习编程的过程中，建议结合实际项目场景练习，才能真正体会到它的价值。