just-safe-set 深度指南:用 JavaScript 安全地为深层对象属性赋值
just-safe-set 深度指南:用 JavaScript 安全地为深层对象属性赋值
导读
本文围绕 just 库中的 just-safe-set 模块展开,讲解如何通过点号字符串、数组或 Symbol 路径,安全地为对象(或数组)的深层属性赋值:路径上的中间属性如果不存在会被自动创建,路径被"非对象值"中断时不会抛异常而是返回 false,并且内置了对 __proto__、constructor、prototype 等原型键的防护。读完本文,你将掌握该工具的完整 API、源码级实现原理、边界行为与测试验证方式,可直接在项目中安全地使用它替代手写的深层次赋值逻辑。
一、模块定位:零依赖、只做一件事
just-safe-set 是 just 这一"零依赖 npm 工具模块库"中的一员,库的整体定位是:每个模块只做一件事(do just one thing)、零依赖、体积可控,是替代臃肿工具库的"无罪恶感"选择。just-safe-set 在模块清单中属于 Objects 分类,与 just-safe-get 组成"安全读写"搭档——safe-get 负责在父级缺失时不抛错地取值,safe-set 负责在父级缺失时自动创建路径并赋值。
二、安装与引入
模块发布名称为 just-safe-set,当前仓库内版本为 4.2.1(见 package.json),采用 MIT 许可。安装方式支持 npm 与 yarn:
npm install just-safe-set
yarn add just-safe-set
引入方式与模块的打包格式有关。该包的 package.json 声明了 "type": "module",并通过 exports 字段同时提供 CommonJS(index.cjs,require 入口)与 ES Module(index.mjs,import 入口)两种产物,还附带 TypeScript 类型声明 index.d.ts:
// ES Module
import set from 'just-safe-set';
// CommonJS
const set = require('just-safe-set');
三、API 签名与返回值
根据 index.d.ts 的类型定义,函数的完整签名是:
declare function set(
item: any[] | {},
target: string | symbol | Array<string | symbol>,
value: any
): boolean;
三个参数的含义与取值规则如下:
| 参数 | 类型 | 说明 |
|---|---|---|
item |
any[] | {} |
要写入属性的目标对象(或数组) |
target |
string | symbol | Array<string | symbol> |
属性路径,支持点号字符串、Symbol、字符串/Symbol 数组三种形态 |
value |
any |
要赋给目标属性的值,可以是任意类型 |
函数始终返回布尔值:
true:赋值成功(包括自动创建中间属性后成功写入,以及覆盖已存在的属性);false:路径在到达终点前被非对象值"中断",无法继续深入。
注意该函数的返回值不代表"是否发生了覆盖"。事实上只要路径畅通,即使目标属性已存在,它也会直接覆盖写入并返回 true——这点在 CHANGELOG.md 的 4.2.1 版本记录中专门做了说明:"修复了 README 中暗示它不会覆盖(clobber)的表述"。
四、路径(target)的三种形态
set 最核心的设计是它接受三种路径表达方式,这在 README 的示例中一一呈现:
1. 点号字符串
import set from 'just-safe-set';
const obj1 = {};
set(obj1, 'a.aa.aaa', 4); // true
obj1; // {a: {aa: {aaa: 4}}}
字符串路径按 . 分隔成属性链,等价于依次写入 obj1.a → obj1.a.aa → obj1.a.aa.aaa。中间属性 a、aa 原本不存在,会被自动创建为 {}。
2. 数组路径
const obj2 = {};
set(obj2, ['a', 'aa', 'aaa'], 4); // true
obj2; // {a: {aa: {aaa: 4}}}
数组路径与字符串路径完全等价,适合路径本身包含 . 字符、或需要程序化动态构造路径的场景。值得注意的是,源码内部会对传入数组做 slice(0) 浅拷贝(见下文源码剖析),不会修改调用方的原数组。
3. Symbol 路径
const obj5 = {a: {}};
const sym = Symbol();
set(obj5.a, sym, 7); // true
obj5; // {a: {Symbol(): 7}}
Symbol 作为路径时表示"单层直接赋值",适用于以 Symbol 作为对象键名的场景(如元数据键、私有约定键)。README 原文档明确展示了这一用法。
五、覆盖已存在的属性
当路径上的最终属性已经存在时,set 会直接对其覆盖赋值并返回 true:
const obj3 = {a: {aa: {aaa: 2}}};
set(obj3, 'a.aa.aaa', 3); // true
obj3; // {a: {aa: {aaa: 3}}}
这也是"clobber(覆盖)"语义所在:just-safe-set 并不保证"不覆盖已有值",它保证的是安全地抵达目标位置。同仓库的测试 test/object-safe-set/index.cjs 中明确注释了 "ok to clobber last property"(覆盖最后一个属性是允许的)。
六、源码实现剖析:逐步拆解 set 的执行过程
核心实现位于 index.cjs(CommonJS 版)与同构的 index.mjs(ESM 版,由 rollup 从 cjs 转换生成)。完整逻辑可分为四个阶段:
阶段一:路径解析
var props, lastProp;
if (Array.isArray(propsArg)) {
props = propsArg.slice(0); // 数组:浅拷贝,避免修改调用方
}
if (typeof propsArg == 'string') {
props = propsArg.split('.'); // 字符串:按点号分割
}
if (typeof propsArg == 'symbol') {
props = [propsArg]; // Symbol:包装成单元素数组
}
if (!Array.isArray(props)) {
throw new Error('props arg must be an array, a string or a symbol');
}
三条分支覆盖了 README 中展示的三种路径形态;若传入的是其他类型(数字、布尔值、对象等),会抛出明确的错误信息 props arg must be an array, a string or a symbol。这一行为也被 TypeScript 测试 index.tests.ts 通过 @ts-expect-error 标注所印证(如 set(obj, 3)、set(obj, [3])、set(null) 等均不允许)。
阶段二:取出末段属性并做原型键校验
lastProp = props.pop();
if (!lastProp) {
return false; // 空路径:直接返回 false
}
prototypeCheck(lastProp);
props.pop() 取出路径的最后一段作为真正的赋值目标,剩余段作为中间路径。若路径为空(如空字符串 '' 或空数组),函数返回 false。末尾段与中间段都会经过 prototypeCheck 校验。
阶段三:逐级穿透中间路径,缺失即创建
var thisProp;
while ((thisProp = props.shift())) {
prototypeCheck(thisProp);
if (typeof obj[thisProp] == 'undefined') {
obj[thisProp] = {};
}
obj = obj[thisProp];
if (!obj || typeof obj != 'object') {
return false; // 中间段不是对象:中断并返回 false
}
}
这是整个函数的灵魂循环:
- 每一级先校验原型键;
- 若当前级属性不存在(
typeof obj[thisProp] == 'undefined'),则创建{}占位; - 随后把引用下移到下一层;
- 关键边界:如果下移后得到的是
null或非对象值(比如{a: 5}上继续写'a.aa.aaa'),立即返回false,绝不抛错——这正是"安全"二字的含义,也是它不中断已有属性链(doesn't interrupt property chain)的保证。
阶段四:写入最终值
obj[lastProp] = value;
return true;
循环结束后,把 value 赋给最后一个属性并返回 true。
七、安全机制:原型污染防护(Prototype Pollution Defense)
just-safe-set 内置了对原型链攻击的显式防护。独立的 prototypeCheck 辅助函数如下:
function prototypeCheck(prop) {
// coercion is intentional to catch prop values like `['__proto__']`
if (prop == '__proto__' || prop == 'constructor' || prop == 'prototype') {
throw new Error('setting of prototype values not supported');
}
}
只要路径中任意一段(包括最后一段)命中 __proto__、constructor、prototype 三者之一,就抛出 setting of prototype values not supported。源码注释特别强调这里的 == 是有意为之的宽松比较:当传入数组路径且其中某段是 ['__proto__'] 这类"数组包裹的字符串"时,宽松比较会触发类型强制转换(coercion),从而同样被拦截。
配套测试 test/object-safe-set/index.cjs 用五个用例系统验证了这一防护,包括:
- 点号路径
'__proto__.x'被拒; - 数组路径中的
'__proto__'段被拒; 'constructor'赋值被拒(防止伪造构造器);'prototype.y'赋值被拒;- 隐藏用例:
['a', 'b', ['__proto__']]这种嵌套数组包裹的路径,会在赋值阶段强制转成字符串__proto__,同样被拦截。
从安全工程角度看,这正是"safe"命名中除"不抛错"之外的第二个维度——不污染原型链。
八、边界行为与测试验证
just-safe-set 的边界行为全部有测试背书(测试框架为 tape,测试入口统一走 test/util/test.js),主要场景汇总如下:
| 场景 | 行为 | 依据 |
|---|---|---|
| 写入已存在属性(点号/数组) | 返回 true 并覆盖 |
test/object-safe-set/index.cjs |
| 写入不存在属性(点号/数组) | 自动创建中间属性,返回 true |
test/object-safe-set/index.cjs |
中间路径被非对象中断(如 {a: 5} 上写 'a.aa.aaa') |
返回 false,不抛错、不改变已创建部分 |
test/object-safe-set/index.cjs |
| 传入数组路径 | 函数内部浅拷贝,不修改原数组 | test/object-safe-set/index.cjs |
| 路径包含原型键(含嵌套数组包裹形式) | 抛出 setting of prototype values not supported |
test/object-safe-set/index.cjs |
| Symbol 作为路径 | 返回 true,键以 Symbol 形式写入 |
test/object-safe-set/index.cjs |
特别值得留意的是"不修改原数组"这一条:测试用例创建 var path = ['a', 'aa', 'aaa'] 后两次复用,断言函数执行前后 path 内容完全一致,印证了源码中 propsArg.slice(0) 浅拷贝的必要性——调用方的路径数组不会被消费掉,可以安全复用。
此外,"路径中断"测试还揭示了一个细节:中断发生在中间段时返回 false,但如果中断点就是最后一段(如 {a: {aa: 9}} 上写 'a.aa'),则属于"允许覆盖最后一层",照样成功返回 true。这与 README 及 CHANGELOG 中"允许覆盖(clobber)最终属性"的语义完全一致。
九、类型定义与模块构建
TypeScript 支持
just-safe-set 自带类型声明 index.d.ts,全库(据 README.md)也统一为每个工具提供 TypeScript 定义与测试。在 TS 项目中可直接获得参数与返回值的完整类型检查;非法调用(如缺参、错误参数类型)会在编译期被 @ts-expect-error 测试所覆盖(见 index.tests.ts)。
双模块产物如何产生
该包没有独立的 TS 源码文件,而是以 index.cjs 为手写源,通过 rollup.config.js 调用仓库统一的 config/createRollupConfig.js(使用 @rollup/plugin-commonjs 插件,将 index.cjs 转为 index.mjs ESM 产物)。因此两处实现逻辑完全一致,Node 的 require 与原生 ESM import 均可直接使用,无需构建转译。
十、典型使用场景
综合 README 文档与源码行为,just-safe-set 适合以下场景:
- 初始化深层配置对象:如
set(config, 'server.proxy.port', 8080),无需手写层层判空与嵌套初始化; - 动态路径写入:路径由运行时变量(数组)决定,且希望路径数组可复用;
- 不可中断的容错写入:希望在中间路径不是对象时静默失败(返回
false)而非抛异常,配合返回值做降级处理; - Symbol 键写入:以 Symbol 为键的对象属性赋值;
- 数据安全敏感场景:任何需要对用户可控键名做写入的场景,利用内置原型键防护规避原型污染风险。
需要说明的是:该函数的"安全"并非不覆盖已有值——它允许覆盖目标属性;同时它只负责"写",若你需要"读"时父级缺失不抛错,可配合同库的 just-safe-get(同样支持字符串、数组、Symbol 路径)组合使用,构成完整的安全读写方案。