Node.js 写入 JSON 文件不完整?用原子写入保护任务状态
JSON 文件坏了,损失的可能是“已经执行过”的记忆
定时任务凌晨退出,第二天重跑时弹出 Unexpected end of JSON input。如果损坏的是页面缓存,重新获取即可;如果是“哪些文章已经发布”的记录,把它重置为空就可能再发一遍。修复 JSON 写入时,首先要区分这两种后果。
Node.js 写入 JSON 状态文件的起点是:同目录写临时文件,写完再 rename 替换;需要并发修改时再加锁或使用事务。下面用故障注入验证旧版本能否保留,并说明 fsync 和原子替换各自负责什么。
把提交点放到 rename
先在目标文件所在目录写一个临时文件,完成写入后再用 renameSync 替换目标。读取者在替换前读旧版本,替换后读新版本,避免看到正在写入的中间内容。临时文件必须放在同一文件系统;跨文件系统移动可能直接报错,不能据此假设仍有相同语义。
临时文件名使用 UUID,wx 表示只允许新建,权限设置为 0600。文件描述符必须先关闭,异常路径也要关闭和清理。下面的 beforeRename 是故障注入点,生产调用时不需要传入。
可运行的最小示例
将代码保存为 example.cjs,使用 Node.js 22 执行 node example.cjs。它只操作系统临时目录,不接触业务状态。
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const assert = require('node:assert/strict');
const {randomUUID} = require('node:crypto');
function saveJSON(file, value, beforeRename = () => {}) {
const temporary = file + '.' + randomUUID() + '.tmp';
let fd;
try {
fd = fs.openSync(temporary, 'wx', 0o600);
fs.writeFileSync(fd, JSON.stringify(value) + '\n');
fs.fsyncSync(fd);
fs.closeSync(fd); fd = undefined;
beforeRename();
fs.renameSync(temporary, file);
} finally {
if (fd !== undefined) fs.closeSync(fd);
fs.rmSync(temporary, {force:true});
}
}
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'atomic-demo-'));
try {
const file = path.join(dir, 'state.json');
saveJSON(file, {version:1});
assert.throws(() => saveJSON(file, {version:2}, () => {
throw new Error('simulated interruption');
}));
assert.deepEqual(JSON.parse(fs.readFileSync(file)), {version:1});
saveJSON(file, {version:2});
assert.deepEqual(JSON.parse(fs.readFileSync(file)), {version:2});
assert.deepEqual(fs.readdirSync(dir), ['state.json']);
console.log('PASS old state survives; replacement succeeds; no temporary files');
} finally { fs.rmSync(dir, {recursive:true, force:true}); }
预期输出以 PASS old state survives 开头。第一轮写入版本 1;第二轮在替换前主动抛错;断言确认旧文件仍然能解析且版本未变;最后一次正常替换为版本 2,并检查没有遗留临时文件。这是主动注入异常后的行为验证,不是对操作系统突然断电的模拟。
该继续用 JSON,还是换成 SQLite?
先按写入者数量和恢复要求选方案,不必为一个小状态文件立即引入完整数据库,也不要让一个 JSON 承担它做不到的事务职责。
| 你的场景 | 可选起点 | 还需要确认什么 |
|---|---|---|
| 单进程维护少量任务状态 | 同目录临时文件加原子替换 | 解析失败后有明确恢复路径 |
| 多个本机入口读改同一状态 | 覆盖整个读改写过程的文件锁 | 所有入口都遵守同一把锁 |
| 多条记录必须一起提交或回滚 | SQLite 等事务存储 | 事务边界、约束与备份 |
| 多台机器同时更新 | 支持并发事务的共享存储 | 不能依赖本机文件锁协调其他主机 |
故障注入点也有讲究:异常发生在 rename 之前,应读到旧版本;rename 成功之后,应读到新版本。不要用“临时文件存在”判断业务已提交,真正的本地替换点是 rename。
遇到现有状态损坏时,先保留原始字节和最近报告,查证远端提交记录,再修复本地状态;先覆盖成空对象会丢掉最重要的排查线索。这里的恢复顺序比“用哪个 JSON 库”更重要。
原子替换仍然会丢更新
设两个进程同时读取版本 1,各自增加一项成果,再分别写入。即使两次替换都原子完成,后一次仍会覆盖前一次新增的内容。原子替换保证文件不会被读到半截,无法保证两个修改自动合并。因此,读状态、判断、执行、写状态这整段仍需互斥锁,或者改用具备事务的存储。
示例对临时文件执行 fsync,让文件数据提交到系统提供的同步边界,但没有同步父目录元数据。需要承受机器断电的系统还要根据平台和文件系统同步目录,并验证实际持久性要求。不能把“进程退出后文件完整”直接扩展成“突然断电绝不丢失”。
读取失败时不要默默当作从未执行
操作记录无法解析时,catch { return {} } 看起来能让任务继续跑,实际可能把已经执行的写操作当作首次执行。更合适的做法是保留原文件、报告读取失败,并先查远端记录。缓存可重建,提交历史不能凭空重置。
将这个保存函数接入业务时,先确定三个问题:谁持有写锁、状态损坏后由什么证据恢复、文件落盘能证明哪一步已经完成。只有这些边界明确,JSON 文件才是可靠的记录载体,而不只是一个“上次运行好像成功”的标记。
参考资料与延伸阅读
- Node.js fs:文件写入、同步与重命名:
https://nodejs.org/api/fs.html
- 点赞
- 收藏
- 关注作者
评论(0)