17370845950

Symbol是JavaScr

ipt中创建“私有”属性名的唯一原生方式，但仅适用于添加非干扰元数据；其键不可枚举、不被JSON.stringify序列化，却可通过Object.getOwnPropertySymbols获取；Symbol.for()实现全局复用，Symbol.iterator则强制用于自定义迭代协议。

Symbol 是 JavaScript 中唯一能创建“私有”属性名的原生方式，但它不是用来替代字符串键的通用工具——用错场景反而会引发难以调试的隐性问题。

Symbol 作为对象属性键时，for...in 和 JSON.stringify 都看不到它

这是 Symbol 最常被误用也最常被依赖的特性：它让属性“不可枚举”且“不被序列化”。但要注意，这不等于“私有”，因为 Object.getOwnPropertySymbols() 和 Reflect.ownKeys() 依然能拿到。

• 适合场景：给第三方库或原型添加非干扰型元数据，比如标记某个对象是否已被处理过
• 不适合场景：试图靠 Symbol 隐藏敏感字段（如 user[Symbol('token')]），服务端或调试时仍可能暴露
• 注意：JSON.stringify() 完全忽略 Symbol 键，for...in 和 Object.keys() 也不包含它们

const processed = Symbol('processed');
const obj = { id: 123 };
obj[processed] = true;

console.log(Object.keys(obj)); // ['id']
console.log(JSON.stringify(obj)); // {"id":123}
console.log(Object.getOwnPropertySymbols(obj)); // [Symbol(processed)]

全局 Symbol 注册表：Symbol.for() 和 Symbol.keyFor() 的协作机制

普通 Symbol('desc') 每次调用都生成新值，而 Symbol.for('desc') 会先查全局注册表，存在就复用，不存在才新建。这对跨模块/跨 iframe 的标识统一很关键。

• Symbol.for('event') 和另一个文件里的同名调用返回同一个 Symbol
• Symbol.keyFor(sym) 只对通过 Symbol.for() 创建的 Symbol 有效，普通 Symbol 返回 undefined
• 注册表是全局共享的，命名冲突风险真实存在，建议加前缀，如 Symbol.for('mylib:cache-key')

const a = Symbol.for('debug');
const b = Symbol.for('debug');
console.log(a === b); // true

const c = Symbol('debug');
console.log(Symbol.keyFor(c)); // undefined

Symbol.iterator 是实现自定义迭代行为的强制接口

只要对象有 [Symbol.iterator] 方法并返回符合迭代器协议的对象，就能用 for...of、扩展运算符、Array.from() 等语法。这是 Symbol 在语言层面真正不可替代的作用。

• 必须返回一个对象，该对象有 next() 方法，返回 { value, done } 形式的结果
• 不能用字符串代替，比如写成 '@@iterator' —— 浏览器不会识别
• 内置类型如 Array、String、Map 都实现了它；自定义类若想支持 for...of，必须手动部署

const counter = {
  [Symbol.iterator]() {
    let i = 0;
    return {
      next() {
        if (i < 3) return { value: i++, done: false };
        return { done: true };
      }
    };
  }
};

console.log([...counter]); // [0, 1, 2]

Symbol.toStringTag 影响 Object.prototype.toString.call() 的输出

这个 Symbol 控制 Object.prototype.toString.call(x) 返回的类型标识字符串，常用于让自定义类在调试或类型判断中更友好，但不影响 typeof 或 instanceof。

• 设置 obj[Symbol.toStringTag] = 'MyClass' 后，Object.prototype.toString.call(obj) 返回 [object MyClass]
• 很多内置对象已使用它，比如 JSON[Symbol.toStringTag] 是 'JSON'，Math[Symbol.toStringTag] 是 'Math'
• 注意：仅影响 toString() 调用结果，不改变实际类型系统，也不能用于 instanceof 判断

class CustomDate {
  get [Symbol.toStringTag]() {
    return 'CustomDate';
  }
}

const d = new CustomDate();
console.log(Object.prototype.toString.call(d)); // [object CustomDate]

Symbol 的真正价值不在“隐藏”，而在“语义注册”和“协议接入”——它是一套由引擎识别的、带明确契约的符号系统。滥用 Symbol() 替代字符串键，或者指望它提供访问控制，都会在协作和维护中埋下隐患。