直接覆盖JSON文件有一个隐蔽窗口：旧内容已经截断，新内容还没完全落盘。进程在这个窗口退出，下次启动只能读到半段文本。原子保存应把“生成新版本”和“让新版本生效”拆成两个步骤。

方案面向HarmonyOS 6.1.1 Release SDK（API 24），系统Kit调用进入适配层，命令约束、状态归并和恢复策略进入可测试的业务层。范围包含状态与资源生命周期设计、失败恢复和验收合同，不包含业务内容生产、服务端协议改造以及特定厂商网页或媒体源的兼容承诺。

复现半写入文件

方案维护data.json、data.tmp和data.bak。写入先序列化稳定字段，计算SHA-256并把校验值写入包裹对象；随后创建tmp、写入并关闭。旧正式文件移动为bak后，再把tmp替换成正式文件。任何一步失败都保留可识别的候选版本。

状态数量不是越多越好。每个状态必须回答三个问题：当前允许哪些命令、收到迟到事件怎样处理、页面退出后是否还可以更新UI。下面的状态对象携带operationId，新的操作开始后，旧操作回调会被拒绝。

export enum AtomicFileState {
  READING = 'reading',
  SERIALIZING = 'serializing',
  WRITING_TEMP = 'writing_temp',
  SWAPPING = 'swapping',
  VERIFYING = 'verifying',
  RECOVERED = 'recovered'
}

export interface AtomicFileSnapshot {
  state: AtomicFileState;
  progress: number;
  message: string;
  operationId: number;
  updatedAt: number;
}

export type AtomicFileEvent =
  | { type: 'START'; operationId: number }
  | { type: 'PROGRESS'; operationId: number; progress: number }
  | { type: 'SUCCESS'; operationId: number }
  | { type: 'FAIL'; operationId: number; message: string };

export function acceptEvent(
  snapshot: AtomicFileSnapshot,
  event: AtomicFileEvent
): boolean {
  return event.type === 'START' || event.operationId === snapshot.operationId;
}

保存协议由三个文件组成

恢复器扫描三个文件，只接受JSON可解析、schemaVersion受支持且校验和一致的候选项，再按version和committedAt排序。bak不会无限保留，每次成功启动后清理过旧文件。URI来自系统或其他应用时先校验scheme与授权，不把外部URI当作普通沙箱路径拼接。

这套分层把系统事实和产品行为分开：Kit适配器负责获得事实，领域对象决定是否接受事件，页面只渲染快照。更换API版本或加入真机能力时，只需要替换适配器；状态归并和异常策略仍可在模拟器中重复验证。

校验和阻止损坏版本生效

下面是主题专属的接入或核心算法代码。示例刻意保留资源创建、前置条件和清理逻辑，因为高频故障往往出现在成功调用之外。

import { fileIo } from '@kit.CoreFileKit';

export class AtomicWriter {
  constructor(private basePath: string) {}

  save(text: string): void {
    const target = this.basePath + '/data.json';
    const temp = this.basePath + '/data.tmp';
    const backup = this.basePath + '/data.bak';
    const file = fileIo.openSync(temp,
      fileIo.OpenMode.CREATE | fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.TRUNC);
    try {
      fileIo.writeSync(file.fd, text);
      fileIo.fsyncSync(file.fd);
    } finally {
      fileIo.closeSync(file);
    }
    if (fileIo.accessSync(target)) {
      if (fileIo.accessSync(backup)) fileIo.unlinkSync(backup);
      fileIo.renameSync(target, backup);
    }
    fileIo.renameSync(temp, target);
  }

  readCandidate(path: string): string | undefined {
    if (!fileIo.accessSync(path)) return undefined;
    const file = fileIo.openSync(path, fileIo.OpenMode.READ_ONLY);
    try {
      return fileIo.readTextSync(file.fd);
    } finally {
      fileIo.closeSync(file);
    }
  }
}

代码迁入业务工程时，应把错误码转换为稳定的领域错误，不让页面直接判断系统错误字符串。对于异步回调，还要在写入状态前比较operationId或资源版本；仅检查组件是否存在，无法阻止旧任务污染新页面。

替换提交必须保持顺序

异常注入按钮用于稳定复现应用侧恢复路径。真实错误发生时，诊断记录同时保存错误码、权限结果、设备能力和用户可见状态；敏感原始数据不进入日志，截图只呈现与问题直接相关的结果。

启动恢复如何选择候选文件

页面层不直接调用Kit，而是通过动作按钮驱动同一份状态模型。这样既能在系统能力可用时接真实适配器，也能在模拟器缺少硬件时验证错误页面、幂等逻辑和资源清理。

@Component
struct AtomicFilePanel {
  @State stateText: string = 'READING';
  @State progress: number = 0;
  @State logs: string[] = [];

  private append(message: string): void {
    const time = new Date().toLocaleTimeString();
    this.logs = [`${time}  ${message}`, ...this.logs].slice(0, 8);
  }

  private startDemo(): void {
    this.stateText = 'SERIALIZING';
    this.progress = 20;
    this.append('开始：Core File原子写入与崩溃恢复');
  }

  private injectFailure(): void {
    this.stateText = 'RECOVERED';
    this.append('已注入可恢复故障');
  }

  build() {
    Column({ space: 12 }) {
      Text('Core File原子写入与崩溃恢复').fontSize(24).fontWeight(FontWeight.Bold)
      Text(this.stateText).fontSize(18).fontColor('#2563EB')
      Progress({ value: this.progress, total: 100 }).width('100%')
      Row({ space: 12 }) {
        Button('开始实验').onClick(() => this.startDemo())
        Button('注入故障').onClick(() => this.injectFailure())
      }
      ForEach(this.logs, (item: string) => Text(item).fontSize(13))
    }.padding(20).width('100%')
  }
}

页面提供五个故障注入点：序列化后、写入一半、fsync后、备份后、替换后。每次强制结束再启动，显示被选择的文件、版本号和恢复原因。验收要求任何中断都只能得到旧完整版本或新完整版本，不能出现半份业务对象。

原子写入还要考虑多调用方竞争。仓库层为同一业务键串行化保存请求，新请求可以合并尚未开始的旧请求，但不能在文件替换阶段插队。恢复器读取候选文件时先限制文件大小，避免损坏长度导致一次性分配过多内存。校验通过后再反序列化业务对象，最后执行字段级迁移。文件系统保证只能覆盖“完整字节提交”，业务兼容仍由schemaVersion和迁移函数负责，两者不能混为一层。应用升级后的第一次成功读取要立即生成新格式备份，确保下一次启动不再依赖旧迁移分支。磁盘空间不足时应保留旧正式文件，并把失败明确返回给上层，不能删除旧版本后假装保存成功。

验收记录至少包括SDK版本、模拟器系统版本、操作顺序、预期状态、实际状态和截图编号。快速点击、返回再进入、故障后重试和页面销毁是必测项；涉及资源的主题还要显示活动对象计数，涉及异步任务的主题要验证迟到结果不会改变当前页面。

五种中断点的恢复结果

这套方案的技术闭环由“输入约束—状态模型—Kit适配—异常恢复—可观察验收”组成。业务状态不持有系统对象，适配器不直接操作页面，异常路径有明确的恢复动作，后续SDK升级时可以分别回归每一层。

官方资料：CoreFileKit相关开发文档