深入解读expo/json-fileExpo 工具链中读写与操纵 JSON 文件的基础库【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expoexpo/json-file是 Expo 开源仓库中一个面向 JSON 文件的高效封装库提供类型安全的读、写、查询、合并与删除等操作。本文将以其 README 为核心骨架结合 核心实现、原子写入 与 错误处理 等源码系统讲解其安装方式、完整 API、配置项语义与源码级原理并展示其在 Expo CLI如 UserSettings.ts中的真实落地场景。读完后你将能够熟练使用该库为 CLI 工具、构建脚本或配置系统实现可靠的 JSON 持久化。一、为什么需要expo/json-file在 Expo 生态中CLI 工具与构建系统需要频繁读取与改写各类 JSON 配置例如用户状态文件、缓存清单、打包结果元数据等。直接使用fs.readFileSync与JSON.parse虽然可行但会带来大量重复的样板代码并普遍存在以下痛点类型安全缺失手动断言解析结果的形状容易出错错误信息不友好JSON 语法错误往往难以定位到具体行列文件不存在时抛异常很多场景希望回退到默认值写入过程可能损坏文件普通写入在进程中断时可能留下半截文件JSON5 支持一些配置文件允许注释与尾逗号。expo/json-file用一个JsonFile类统一解决这些问题。正如其在 package.json 中的描述A module for reading, writing, and manipulating JSON files。每个方法都提供同步与异步两个版本并且同时支持类上的实例调用与静态调用两种形态。二、安装与快速上手1. 安装在任意 Node.js 项目中通过包管理器安装即可yarn add expo/json-file也可以使用npm install expo/json-file或pnpm add expo/json-file。该包的运行时依赖只有json5与babel/code-frame用于美化错误输出体积轻量。2. 最小可用示例仓库 README 给出的核心用法如下import JsonFile, { JSONObject } from expo/json-file; // Create a file instance const jsonFile new JsonFileJSONObject(filePath); // Interact with the file await jsonFile.readAsync(); await jsonFile.writeAsync({ some: data });更完整的流程通常是实例化 → 读取容错→ 修改 → 原子写回import JsonFile, { JSONObject } from expo/json-file; type AppConfig JSONObject { version?: string; features?: { darkMode?: boolean }; }; const file new JsonFileAppConfig(config.json, { ensureDir: true, // 目录不存在时自动创建 jsonParseErrorDefault: {},// 文件损坏时回退为空对象 cantReadFileDefault: {}, // 文件不存在时也回退为空对象 }); const config await file.readAsync(); // 读取带容错 await file.setAsync(version, 2.0.0); // 更新单个键并原子写回 const version file.get(version, 1.0.0); // 读取键带默认值三、完整 API同步 / 异步与实例 / 静态双形态在 JsonFile.ts 的类定义中所有公共方法都被同时注册为实例方法与静态方法static read read等。下表基于源码逐一对应方法作用返回值read()/readAsync()读取并解析整个文件解析后的对象write(object)/writeAsync(object)序列化并写入整个对象写入的对象rewrite()/rewriteAsync()读取后原样重写用于统一格式化对象parseJsonString(str)直接解析一段 JSON/JSON5 字符串对象get(key, default)/getAsync(key, default)读取顶层某个键的值该键的值set(key, value)/setAsync(key, value)更新或新增顶层键并落盘更新后的对象merge(sources)/mergeAsync(sources)合并一个或多个对象并落盘合并后的对象deleteKey(key)/deleteKeyAsync(key)删除单个顶层键更新后的对象deleteKeys(keys[])/deleteKeysAsync(keys[])批量删除多个顶层键更新后的对象每个异步方法返回PromiseTJSONObject同步方法直接返回对象。测试 JsonFile-test.ts 中对上述 8 组方法逐一断言了静态与实例形态的存在性。1. 实例方法绑定文件路径与默认选项const file new JsonFileJSONObject(package.json); const obj await file.readAsync(); await file.setAsync(name, my-app);构造函数签名如下源码 JsonFile.ts#L69-L72constructor(file: string, options: OptionsTJSONObject {})实例持有file与options每次方法调用时临时传入的选项会通过_getOptions与构造选项做浅合并{ ...this.options, ...options }实现实例默认 单次覆盖。2. 静态方法无状态的一次性调用不需要复用实例时可直接静态调用const obj await JsonFile.readAsyncJSONObject(app.json); await JsonFile.writeAsync(app.json, { name: demo }); const v JsonFile.get(package.json, version, 0.0.0); await JsonFile.setAsync(package.json, license, MIT); await JsonFile.mergeAsync(app.json, [{ expo: { name: Demo } }]);3. 常用操作的行为语义get/getAsync先读取整个文件再检查key in object。键存在则返回值键不存在且未提供defaultValue时会抛出JsonFileError消息为No value at key path ...提供了则返回默认值。源码见 JsonFile.ts#L233-L263。set/setAsync等价于先read整个对象再展开写入{ ...object, [key]: value }随后整体落盘。注意它仅操作顶层键。merge/mergeAsync入参可以是单个对象或对象数组内部通过Object.assign依次并入后整体写回。deleteKey(s)/deleteKey(s)Async批量删除只有确实发生了删除时才触发磁盘写入源码通过didDelete标志判断避免无谓 I/O。rewrite/rewriteAsync先读取、再原样写回典型用途是统一重新格式化/规范化现有文件例如按新的缩进风格重排。四、Options 配置项详解所有读写方法都接受可选的 Options 对象其完整定义与默认值都在 JsonFile.ts#L16-L38选项类型默认值语义defaultTJSONObjectundefined读取失败不可读或解析失败时的兜底默认对象badJsonDefaultTJSONObjectundefined声明兼容用实际兜底逻辑见下方两个选项jsonParseErrorDefaultTJSONObjectundefined文件内容存在但解析失败非法 JSON时返回的对象cantReadFileDefaultTJSONObjectundefined文件不存在/无权限等无法读取时返回的对象ensureDirbooleanfalse写入前自动创建父目录递归mkdirmodefs.Modeundefined写入后强制设置的文件权限位json5booleanfalse为true时以 JSON5 语法解析/序列化spacenumber2序列化缩进空格数addNewLineAtEOFbooleantrue写出的文件末尾追加一个换行符1. 三个默认值选项的优先级源码中的jsonParseErrorDefault()与cantReadFileDefault()JsonFile.ts#L444-L462揭示了一个容易忽略的细节当专门的默认值选项未设置时会回退读取default。因此default是读取失败的通用兜底而两个专项选项可以分别控制文件坏了与文件读不到两种失败分支的返回值。当所有兜底都未配置且读取/解析失败时才会抛出异常。2.get的第三个参数默认值注意get/getAsync的方法签名中第二个参数defaultValue就是键缺失时的兜底值键不存在时的兜底而 Options 中的default系列处理的是整个文件读取失败的情况——两者场景不同不要混淆。五、JSON5 支持宽松语法的配置文件当json5: true时读取走JSON5.parse、写入走JSON5.stringifyJsonFile.ts#L209-L213。这意味着文件可以包含单行/多行注释尾逗号不带引号的键名单引号字符串。仓库 fixtures 中的 test-json5.json 就演示了以上全部语法例如itParsedProperly: 42、x: z与块注释而对应的标准 JSON 版本在 test.json 中则必须全部使用双引号键。测试 JsonFile-test.ts 验证了json5: true时能正确解析该 fixture 并读到score: 5与itParsedProperly: 42。六、写入可靠性原子写与文件权限write并非直接覆盖目标文件而是委托给 writeAtomic.ts 实现原子写入以文件内容计算 SHA-256生成唯一临时文件名${filename}.${hash}base64url 编码先写入临时文件再通过rename原子替换目标文件。由于rename在同一文件系统内是原子操作中途崩溃也不会留下半个文件这保证了并发或异常场景下配置文件的完整性。细节上源码特意注释说明rename会保留目标文件原有的权限模式因此在指定了mode选项时会随后执行一次chmod来强制施加期望的权限位writeAtomic.ts#L21-L24。write/writeAsync的流程为JsonFile.ts#L265-L315若ensureDir为真先递归创建父目录依据json5、space序列化对象序列化失败会抛出JsonFileError依据addNewLineAtEOF决定是否在末尾追加\n以原子方式写入并带上mode。测试 JsonFile-test.ts 中通过mode: 0o600验证了写入后fs.stat(...).mode 0o777恰为0o600另一个用例验证了文件最后一个字符是\n对应addNewLineAtEOF默认值true。七、错误处理JsonFileError 与友好的诊断信息错误体系定义在 JsonFileError.ts 中JsonFileError所有失败的统一错误类型。其构造器会把文件路径与底层cause拼进多行消息使用├─/└─字符绘制错误树并暴露cause、code、fileName以及标记位isJsonFileError: true。注意源码注释特别提醒该类的实例不会通过instanceof JsonFileError因为它直接继承Error而非再继承一个中间类构造器里也没有调用Object.setPrototypeOf实际中通常靠isJsonFileError标志位来判别。EmptyJsonFileError当文件内容为空字符串trim()后为空时抛出错误码为EJSONEMPTY。当内容解析失败时parseJsonString 还会利用babel/code-frame生成带行列高亮的代码帧并拼入错误消息JSON5 的 SyntaxError 直接携带lineNumber/columnNumber原生 JSON 的 SyntaxError 则通过消息里的at position N反推出行列见locationFromSyntaxError。这让开发者能在终端直接看到出错位置附近的原文。测试 JsonFileError-test.ts 验证了isJsonFileError标志与cause的携带JsonFile-test.ts 则断言了 JSON 与 JSON5 两种语法错误的Cause: SyntaxError: ...消息片段。八、源码级工作流一次readAsync发生了什么以异步读取为例调用链如下file.readAsync()→readAsync(file, options)fs.promises.readFile(file, utf8)读取原文JsonFile.ts#L189读取抛错时先经assertEmptyJsonString排除空文件再依据cantReadFileDefault/default决定返回默认值还是抛出带原因链的JsonFileError读取成功则进入parseJsonString依据json5选项选择解析器解析失败且无兜底时附加 code frame 后抛出JsonFileError错误码EJSONPARSE。类型层面JsonFileTJSONObject是泛型类约束TJSONObject extends JSONObjectJsonFile.ts#L8-L12 定义了递归的JSONValue boolean | number | string | null | JSONArray | JSONObject等类型保证读取结果与写入入参都被类型检查覆盖。九、仓库内的真实应用从 CLI 工具看典型用法expo/json-file不是孤立的教学包而是 Expo CLI 与多个工具模块的实际依赖。例如 packages/expo/cli/src/api/user/UserSettings.ts 中CLI 将用户会话状态持久化到~/.expo/state.json// state.json holds the auth session secret, so restrict it to the owner only. const SETTINGS_FILE_MODE 0o600; export function getSettings(): JsonFileUserSettingsData { return new JsonFileUserSettingsData(getSettingsFilePath(), { ensureDir: true, mode: SETTINGS_FILE_MODE, jsonParseErrorDefault: {}, // This will ensure that an error isnt thrown if the file doesnt exist. cantReadFileDefault: {}, }); }这段真实代码几乎用到了前文讲到的全部容错特性ensureDir: true保证.expo目录不存在时也能自动创建mode: 0o600将含认证机密的state.json限制为仅属主可读写jsonParseErrorDefault/cantReadFileDefault配合空对象使首次运行文件不存在或文件损坏时优雅回退而不是崩溃随后通过getSettings().get(auth, null)读取会话、setAsync(auth, sessionData, { default: {} })更新会话。在同一个 CLI 中bundledNativeModules.ts、ESlintPrerequisite.ts、getExpoSchema.ts 等十余个模块也都在使用expo/json-file足以说明该库承担了 Expo CLI 中几乎所有 JSON 配置的读写职责。如果你在开发需要持久化 JSON 的 Node 工具或 CI 脚本完全可以套用同样的模式。十、测试与质量保障包内置完整的 Jest 测试入口见 jest.config.js测试用例集中在tests目录并通过memfs在内存文件系统中模拟磁盘覆盖了同步/异步读取、JSON5 解析、语法错误的错误消息写入、rewrite、文件权限模式、EOF 换行符set的增改、deleteKey/deleteKeys的删除连续 50 轮高频写读下的无竞态验证测试注释指出约 200 轮以上在高并发压力下可能失败但真实场景几乎不会如此高频。通过cd packages/expo/json-file yarn test或pnpm test可在本地复跑这些用例是理解各 API 行为的直接参考。总结expo/json-file用极简的接口把 JSON 文件的读、写、查、改、并、删、格式化重写收敛到一个泛型类中并同时提供同步/异步、实例/静态四种调用组合。其差异化价值集中在三点统一的容错默认值体系default/jsonParseErrorDefault/cantReadFileDefault、基于临时文件 rename 的原子写入以及附代码帧的友好错误诊断json5选项与mode/ensureDir则让它可以安全地处理宽松语法的配置文件与含敏感信息的系统状态文件。从 Expo CLI 中state.json等真实实践可以看出这一模式已成为 Expo 工具链处理 JSON 持久化的标准答案同样值得在自研 CLI 与脚本工程中借鉴。【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考