如何通过Symbol/Proxy实现ConfigNode功能与数据的分离访问？

需求说明 #

假设用户提供如下YAML配置：

configRoot:
  fluentSubSection:
     someProp: 12
     valueOf: John Doe
     toString: whatever
     toJSON:
        implementation: 'some-npm-one'
        indentation: 2

需要实现ConfigNode类，满足三个核心要求：

1. 支持任意属性名的配置数据，无命名限制；
2. 直接访问属性时返回用户配置的原始值（如config.configRoot.fluentSubSection.valueOf返回John Doe，toString返回whatever）；
3. 调用String()、JSON.stringify()等原生操作时，触发自定义逻辑，而非使用用户配置的属性值。

实现方案 #

核心思路是用Proxy拦截属性访问分离数据与功能，结合Symbol和原型方法实现原生操作的自定义逻辑，避免与用户配置的属性名冲突。

完整代码实现 #

// 定义内部使用的Symbol，避免与用户配置属性名冲突
const CUSTOM_TO_STRING = Symbol('customToString');
const CUSTOM_TO_JSON = Symbol('customToJSON');

class ConfigNode {
  constructor(data) {
    // 深层克隆并递归处理嵌套数据，对象/数组自动包装为ConfigNode
    this._data = Array.isArray(data)
      ? data.map(item => typeof item === 'object' && item !== null ? new ConfigNode(item) : item)
      : structuredClone(data);

    // 返回Proxy实例，拦截属性访问与修改
    return new Proxy(this, {
      get(target, prop, receiver) {
        // 处理原生类型转换的Symbol，优先于toString/toJSON
        if (prop === Symbol.toPrimitive) {
          return (hint) => hint === 'string' ? target[CUSTOM_TO_STRING]() : target._data;
        }

        // 返回内部自定义方法
        if (prop === CUSTOM_TO_STRING) return target[CUSTOM_TO_STRING];
        if (prop === CUSTOM_TO_JSON) return target[CUSTOM_TO_JSON];

        // 返回用户配置的属性值，嵌套对象自动包装
        if (prop in target._data) {
          const value = target._data[prop];
          return typeof value === 'object' && value !== null && !(value instanceof ConfigNode)
            ? new ConfigNode(value)
            : value;
        }

        // 其他属性（如原型方法）正常返回
        return Reflect.get(target, prop, receiver);
      },

      // 可选：禁止修改配置，实现只读
      set() {
        throw new Error('ConfigNode is read-only');
      }
    });
  }

  // 自定义字符串转换逻辑
  [CUSTOM_TO_STRING]() {
    const entries = Object.entries(this._data).map(([key, value]) => {
      const valStr = value instanceof ConfigNode ? String(value) : value;
      return `${key}: ${valStr}`;
    });
    return `[Custom ConfigNode - ${entries.join('; ')}]`;
  }

  // 自定义JSON序列化逻辑
  [CUSTOM_TO_JSON]() {
    const serialize = (data) => {
      if (data instanceof ConfigNode) return serialize(data._data);
      if (Array.isArray(data)) return data.map(serialize);
      if (typeof data === 'object' && data !== null) {
        return Object.fromEntries(Object.entries(data).map(([k, v]) => [k, serialize(v)]));
      }
      return data;
    };

    const serialized = serialize(this._data);
    const indent = this._data.toJSON?.indentation ?? 2;
    // 先序列化再解析，确保返回的是对象而非字符串
    return JSON.parse(JSON.stringify(serialized, null, indent));
  }

  // 覆盖原型toString，避免直接调用时因用户配置的toString是字符串而报错
  toString() {
    return this[CUSTOM_TO_STRING]();
  }

  // 覆盖原型toJSON，JSON.stringify会优先调用此方法（用户配置的toJSON是对象，非函数）
  toJSON() {
    return this[CUSTOM_TO_JSON]();
  }
}

// 模拟配置加载函数
function loadConfig() {
  // 实际项目中可替换为YAML解析逻辑
  return new ConfigNode({
    configRoot: {
      fluentSubSection: {
        someProp: 12,
        valueOf: 'John Doe',
        toString: 'whatever',
        toJSON: {
          implementation: 'some-npm-one',
          indentation: 2
        }
      }
    }
  });
}

测试验证 #

const config = loadConfig();

// 直接访问属性，返回用户配置值
console.log(config.configRoot.fluentSubSection.valueOf); 
// 输出: John Doe
console.log(config.configRoot.fluentSubSection.toString); 
// 输出: whatever

// String()转换触发自定义逻辑
console.log(String(config.configRoot.fluentSubSection)); 
// 输出: [Custom ConfigNode - someProp: 12; valueOf: John Doe; toString: whatever; toJSON: [Custom ConfigNode - implementation: some-npm-one; indentation: 2]]

// JSON.stringify触发自定义序列化
const jsonOutput = JSON.stringify(config.configRoot.fluentSubSection);
console.log(jsonOutput);
// 输出格式化后的JSON，使用用户配置的indentation=2

方案优势 #

1. 数据与功能完全分离：用户配置数据存储在私有属性_data中，功能逻辑通过Symbol和原型方法实现，不会与任意用户属性名冲突；
2. 自然的访问体验：Proxy拦截确保直接访问属性时返回用户配置值，符合常规JS对象的使用习惯；
3. 原生操作兼容：通过Symbol.toPrimitive处理字符串转换，原型toJSON处理序列化，既满足原生API的调用逻辑，又实现了自定义需求；
4. 嵌套自动处理：所有嵌套对象/数组都会自动包装为ConfigNode，保持一致的行为。

内容的提问来源于stack exchange，提问作者404