just-safe-get 源码解析:零依赖对象安全取值工具从 API 到实现的完整指南

原创2026-10-14 18:21:311,694 阅读
文章标签:开发工具

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;

循环每次从路径头部弹出一个属性名并向下取值,且每走一步都做两次安全检查:

  1. 取值前检查当前节点是否为假值(对应中间父级为 null/undefined 的情况);
  2. 取值后检查结果是否为 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 三套入口声明,正是这类调整沉淀下来的结果。

深入探索:相关文件一览

如果你想进一步研究或复用这套实现,可以从以下文件入手:

总而言之,just-safe-get 用约 30 行代码完成了「安全取深层属性」这一件事:三种路径输入、逐层守卫、默认值兜底,辅以明确的边界行为与完整的双格式发布方案。无论是直接使用,还是借鉴它「零依赖、单职责、双格式、强测试」的工程组织方式,都是一个值得收藏的最小样本。

登录后查看全文
just