just-safe-get 源码解析:零依赖对象安全取值工具从 API 到实现的完整指南
just-safe-get 源码解析:零依赖对象安全取值工具从 API 到实现的完整指南
本篇技术指南以 just 仓库中的 just-safe-get(源码目录 packages/object-safe-get)为主线,完整讲解这个「只做一件事」的零依赖 npm 模块:如何用点号字符串、路径数组甚至 Symbol 安全地读取深层对象属性,且中间任意父级为 undefined 也不会抛错。读完你不仅能立即上手使用,还能从 get 实现 看懂其取值原理与边界行为,并通过 CHANGELOG 了解模块格式与导出结构的演进脉络。
认识 just-safe-get:只做一件事的零依赖工具
just-safe-get 是 just 这一「零依赖 npm 模块集合」中的一员。正如根目录 README.md 所述,整个库的定位是 A library of zero-dependency npm modules that do just one thing(只做一件事的零依赖模块库),而 just-safe-get 的职责在它的包描述里写得非常直白:
Get value at property, don't throw if parent is undefined (在属性路径上取值,父级为
undefined时也不抛错)
这一描述同时记录在 packages/object-safe-get/package.json 的 description 字段与 packages/object-safe-get/README.md 中。与 lodash 这类「大而全」的库不同,它不依赖任何第三方包,模块体积与心智负担都保持在最小,非常适合对包体积敏感的场景(如 PWA 开发)。
安装同样轻量,任选其一:
npm install just-safe-get
yarn add just-safe-get
当前仓库内该包的版本为 4.2.0(见 package.json),并同时提供 ESM(index.mjs)与 CJS(index.cjs)两种入口,另有 TypeScript 类型声明 index.d.ts,无需转译即可在 Node 与各类打包器中直接使用。
快速上手:三种路径参数与默认值
get 的用法非常简洁,核心签名只有三个参数:目标对象、路径、可选默认值。路径既可以写成 'a.aa.aaa' 这样的点号字符串,也可以写成 ['a', 'aa', 'aaa'] 数组。下面的示例完整摘自 packages/object-safe-get/README.md:
import get from 'just-safe-get';
const obj = {a: {aa: {aaa: 2}}, b: 4};
// 点号字符串路径
get(obj, 'a.aa.aaa'); // 2
// 数组路径
get(obj, ['a', 'aa', 'aaa']); // 2
// 路径中断,返回 undefined(不会抛错)
get(obj, 'b.bb.bbb'); // undefined
get(obj, ['b', 'bb', 'bbb']); // undefined
// 也可以从对象的任意子节点开始取值
get(obj.a, 'aa.aaa'); // 2
get(obj.a, ['aa', 'aaa']); // 2
// 从子节点开始且路径中断
get(obj.b, 'bb.bbb'); // undefined
get(obj.b, ['bb', 'bbb']); // undefined
// 第三个参数作为默认值
get(obj.b, 'bb.bbb', 5); // 5
get(obj.b, ['bb', 'bbb'], true); // true
// 目标本身为 null / undefined 时同样安全
get(null, 'a'); // undefined
get(undefined, ['a']); // undefined
// 此时默认值同样生效
get(null, 'a', 42); // 42
get(undefined, ['a'], 42); // 42
// 支持 Symbol 作为属性键
const obj = {a: {}};
const sym = Symbol();
obj.a[sym] = 4;
get(obj.a, sym); // 4
可以看到,无论路径在哪个层级中断、无论目标对象是否为 null,调用都不会抛出异常,这正是「安全取值」的含义。
源码实现剖析:get 到底做了什么
just-safe-get 的实现非常精简,核心逻辑只有约 30 行。我们先看两个入口文件:CommonJS 版 packages/object-safe-get/index.cjs 与由 Rollup 生成的 ESM 版 packages/object-safe-get/index.mjs,两者内部的 get 函数完全一致,仅导出语法不同(module.exports = get 与 export default)。构建关系可以从 packages/object-safe-get/rollup.config.js 与 config/createRollupConfig.js 看出:以 index.cjs 为输入,输出 ESM 格式的 index.mjs,也就是说 CommonJS 是原始编写格式,ESM 由构建自动生成。
第一步:处理空目标
function get(obj, propsArg, defaultValue) {
if (!obj) {
return defaultValue;
}
// ...
}
实现使用真值判断:当目标对象为 null、undefined(以及任何假值)时,直接返回默认值。这是整个「不抛错」保证的第一道防线。
第二步:路径参数规范化
var props, prop;
if (Array.isArray(propsArg)) {
props = propsArg.slice(0);
}
if (typeof propsArg == 'string') {
props = propsArg.split('.');
}
if (typeof propsArg == 'symbol') {
props = [propsArg];
}
if (!Array.isArray(props)) {
throw new Error('props arg must be an array, a string or a symbol');
}
三种合法的路径输入被统一规范成属性名数组:
- 数组:直接
slice(0)拷贝一份——注意是拷贝而非直接引用,因此传入的路径数组不会被修改,这一点后面还会在测试中得到验证; - 点号字符串:按
.拆分; - Symbol:包装成单元素数组,从而支持
Symbol属性键。
如果传入的类型不属于以上任何一种(例如数字),实现会抛出明确的错误 'props arg must be an array, a string or a symbol'。这一点也能从类型测试 packages/object-safe-get/index.tests.ts 中得到印证——文件中对 get(obj, 3)、get(obj, [3])、get() 等非法调用都标注了 @ts-expect-error。
第三步:逐层安全取值
while (props.length) {
prop = props.shift();
if (!obj) {
return defaultValue;
}
obj = obj[prop];
if (obj === undefined) {
return defaultValue;
}
}
return obj;
循环每次从路径头部弹出一个属性名并向下取值,且每走一步都做两次安全检查:
- 取值前检查当前节点是否为假值(对应中间父级为
null/undefined的情况); - 取值后检查结果是否为
undefined(对应属性不存在的空键情况)。
任一步中断都会立即返回默认值;只有完整走完整个路径,才返回最终值。这就是「路径中断不抛错」的底层实现,核心思想可以概括为:用显式的边界判断替代 JS 原生的抛错行为。
边界行为:假值属性名、空 key 与路径数组不变性
测试文件 test/object-safe-get/index.cjs 用近 20 组用例覆盖了各种边界情况,是理解实现语义的最佳佐证。几个容易踩坑的点值得单独说明:
属性值为假值时也能正常取到
点号路径返回的既有属性不限于真值——get(obj, 'b') 在 b: 0 时返回 0,在 b: null 时返回 null(见测试第 5-30 行)。也就是说,只有当属性确实不存在(取到 undefined)时才会走默认值逻辑,属性值为 0、''、null 这类假值并不会被误判为「路径中断」。
空字符串 key 的两种命运
这一点最能体现字符串与数组路径的差异:
- 字符串路径中的空段是无效的:
get(obj, 'a.')、get(obj, 'b..b')都会返回undefined(或默认值); - 数组路径中的空字符串 key 却会被真实跟随:
get(obj, ['b', '', ''])在obj = {b: {'': {'': 3}}}时能正确取到3(测试第 132-138 行)。
原因很简单:字符串路径 split('.') 后空段会被当作一次普通属性访问,而对象上通常不存在 '' 这个键;但数组路径中的 '' 是显式指定的属性名,只要目标对象真有这个键就能取到。
路径数组不可变
多次测试都验证了传入的路径数组在调用后保持不变(测试第 26-29、67-70、83-86、114-117、154-164 行),例如:
var path = ['a', 'aa', 'aaa'];
get(obj, path); // 2
// path 依然是 ['a', 'aa', 'aaa']
这得益于实现中的 slice(0) 拷贝。
Symbol 键
实现与测试(测试第 167-176 行)都支持以 Symbol 作为单键路径。不过需要注意:类型声明 packages/object-safe-get/index.d.ts 中 target 目前仅声明为 string | string[],从类型层面看尚未覆盖 symbol,使用 Symbol 时需要自行处理类型(get(obj.a, sym as any) 之类)。
版本演进:从 CHANGELOG 看包的维护脉络
packages/object-safe-get/CHANGELOG.md 记录了该包从 4.1.0 到 4.2.0 的三个版本变更,虽然只有寥寥数条,但每一条背后都对应着真实的工程决策,下面按从新到旧的顺序逐一展开。
v4.2.0:Node 模块由 .js 重命名为 .cjs
Rename node module .js -> .cjs
这是最近一次小版本更新(对应当前 package.json 的 4.2.0),把 CommonJS 入口文件从 index.js 重命名为 index.cjs。理解这一改动需要结合 package.json 中的 "type": "module" 字段:
- 在
"type": "module"的包中,.js文件会被 Node.js 当作 ES Module 解析; - 如果 CJS 文件仍叫
index.js,用户require('just-safe-get')时就会因为文件被误判为 ESM 而报错; - 重命名为
.cjs后,Node 会无视type字段、强制按 CommonJS 解析该文件,保证require路径始终可用。
同时 package.json 的 exports 字段(package.json)明确将 require 指向 ./index.cjs、import 指向 ./index.mjs,实现「双格式同包」的经典方案。
v4.1.1:调整导出顺序,将 default 放到最后(#488)
fix: reorder exports to set default last #488
这一补丁涉及 Node.js 条件导出(conditional exports)的匹配规则:exports 字段的对象键按书写顺序自上而下匹配,default 作为兜底条件必须放在最后,否则会被更具体的条件提前命中而失效。
从当前 package.json 可以看到该约定的实际落地形态:
"exports": {
".": {
"types": "./index.d.ts",
"require": "./index.cjs",
"import": "./index.mjs"
},
"./package.json": "./package.json"
}
types(供 TypeScript 解析)在前,require/import 两个运行环境条件紧随其后。这个顺序本身也符合社区普遍推荐的写法,值得在维护自己的双格式包时参考。
v4.1.0:package.json 更新,修复 #467 与 #483
package.json updates to fix #467 and #483
最早的这条记录说明 package.json 层面做过一轮结构性更新以修复两个 issue(编号 #467、#483)。虽然仓库内没有记录这两个 issue 的具体内容,但从当前 package.json 的形态可以推断(结合 CHANGELOG 4.1.1 的导出顺序调整可以互为印证):这一轮更新与 exports 字段、main/types 入口声明 的规范化有关——如今包同时具备 main、types 与 exports 三套入口声明,正是这类调整沉淀下来的结果。
深入探索:相关文件一览
如果你想进一步研究或复用这套实现,可以从以下文件入手:
- 包文档:packages/object-safe-get/README.md(用法示例与安装方式)
- 核心实现:packages/object-safe-get/index.cjs(CJS 源码)与 packages/object-safe-get/index.mjs(ESM 构建产物)
- 类型声明:packages/object-safe-get/index.d.ts
- 行为测试:test/object-safe-get/index.cjs(覆盖点号/数组路径、默认值、假值、空 key、Symbol 等全部边界)
- 类型测试:packages/object-safe-get/index.tests.ts
- 构建配置:config/createRollupConfig.js 与 packages/object-safe-get/rollup.config.js
- 包元数据:packages/object-safe-get/package.json 与 md-variables.json(README 模板变量中记录的同一组示例)
- 变更记录:packages/object-safe-get/CHANGELOG.md
总而言之,just-safe-get 用约 30 行代码完成了「安全取深层属性」这一件事:三种路径输入、逐层守卫、默认值兜底,辅以明确的边界行为与完整的双格式发布方案。无论是直接使用,还是借鉴它「零依赖、单职责、双格式、强测试」的工程组织方式,都是一个值得收藏的最小样本。