本文的文件名、路径片段、状态、日志和界面均为演示构造不代表已经在 HarmonyOS 设备上写盘、断电或恢复成功。示例只讨论应用沙箱内的文件处理不涉及用户公共目录授权或云同步。一、一个看似正常的“导出成功”提示我见过的离线审核工具里最让人难查的问题通常不是根本写不出文件而是写出了一半页面却已经提示完成。用户第二天重新打开看到了一个存在的文件文件尾巴少了两条关键审计记录。此时若再让应用重新导出旧文件可能被覆盖真正的失败现场也就没了。与其把导出按钮做得很漂亮不如先问一句哪一个时刻才值得向用户展示成功本轮的第二个 Demo 叫AuditHarbor界面页面AuditExportPage任务AL-2213。它只导出三条预置的离线审核事件版本号固定v7R-01/START、R-02/CHECK、R-03/CLOSE。目标文件名为audit-AL-2213-v7.jsonl写入中间文件名为audit-AL-2213-v7.jsonl.part。界面最终状态使用PROMOTED因为“写完临时文件”和“准备给用户读取的正式文件”应该是两个事件。这里故意不用文件选择器也不碰相册。示意路径来自应用上下文的filesDir不是随手拼一个公共存储路径。Core File Kit 的fileIo负责访问应用文件但它并不替业务检查审计事件是不是重复、文本中是不是混入了换行、版本是不是已经生成。把格式、安全输入与写盘动作分开是这篇工程复盘的第一条约束。二、先决定要写什么再决定怎么写示例选用 JSON Lines每行是一条完整 JSON便于之后按行解析也能让单条字段内的换行被 JSON 字符串转义避免人工拼接冒出伪造的第二条记录。为便于复核我把三条事件的seq固定为一、二、三任务 ID 不从输入框自由拼进文件路径导出版本也由页面的固定流程提供而不是来自未经校验的任意文件名。第一段代码解决生成稳定负载的问题。它先校验任务、记录数量、顺序和字段白名单再按顺序形成 JSONL。实际项目还需要额外校验签名来源、时钟可信度、隐私字段以及允许导出的最大体积。本文不把“JSON 能解析”误说成“审计内容可信”这两件事是不同层面的校验。interface AuditRow { seq: number; recordId: string; action: string; } function buildAuditJsonl(taskId: string, rows: AuditRow[]): string { const actions: string[] [START, CHECK, CLOSE]; if (taskId ! AL-2213 || rows.length ! 3) { throw new Error(INVALID_BATCH); } let lines: string[] []; rows.forEach((row: AuditRow, i: number) { if (row.seq ! i 1 || row.recordId ! R-0${i 1} || row.action ! actions[i]) { throw new Error(INVALID_ROW); } lines.push(JSON.stringify({ taskId: taskId, seq: row.seq, recordId: row.recordId, action: row.action })); }); const payload: string lines.join(\n) \n; if (payload.length 4096) { throw new Error(TOO_LARGE); } return payload; }这个函数不持有文件句柄也没有线程需要释放任何异常都在接触磁盘前返回。长度限制只是演示上限以字符数量粗筛不能代替严格的 UTF-8 字节预算。中文、多字节字符或后续增加的附件必须按实际字节数校验。固定的R-01到R-03让案例容易对照不意味着真实业务只能写三条。批量数据很大时应切换为流式分段写入并处理背压而不是用一个巨大字符串占满 UI 线程内存。三、正式文件只能在读回验证后出现主要工程动作是先写.part关闭描述符再从同一路径读回校验内容最后才执行重命名。为什么把“关闭”排在读回前因为我们需要明确写操作已经结束不应在描述符还活着时混着读同一个文件。为何不用直接覆盖正式文件因为一旦写盘或校验失败用户应当继续看到此前有效版本而不是看到一个中途断掉的半成品。下面的代码采用单个导出者、固定批次版本和应用沙箱目录三项前提。fileIo.openSync、writeSync、closeSync、readTextSync、renameSync与unlinkSync都属于文件基础操作。它们并不帮我们做版本独占或任务排队正式文件已存在时直接拒绝复写。代码特意在finally关闭句柄避免异常分支遗漏释放。这里使用同步 API 是为了凸显操作顺序生产项目不应在 UI 主线程执行大文件同步 I/O。import { fileIo } from kit.CoreFileKit; function stageAndPromote(filesDir: string, payload: string): string { const temp: string ${filesDir}/audit-AL-2213-v7.jsonl.part; const target: string ${filesDir}/audit-AL-2213-v7.jsonl; let file: fileIo.File | null null; if (fileIo.accessSync(target)) { throw new Error(VERSION_EXISTS); } try { if (fileIo.accessSync(temp)) { fileIo.unlinkSync(temp); } file fileIo.openSync(temp, fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY); fileIo.writeSync(file.fd, payload); } finally { if (file ! null) { fileIo.closeSync(file); } } try { if (fileIo.readTextSync(temp) ! payload) { throw new Error(READBACK_MISMATCH); } fileIo.renameSync(temp, target); return target; } catch (error) { if (fileIo.accessSync(temp)) { fileIo.unlinkSync(temp); } throw error; } }读回检查可抓住短写、尾部残留、编码变更或内容不一致却不能证明存储介质在突然断电后一定保留最近写入。重命名与彻底持久化不是同一个保证是否支持同目录替换、错误码如何表达、是否需要额外持久化步骤应该按设备文件系统及目标 SDK 文档核对。尤其不能把当前示例称为跨文件事务或数据库级原子提交。生产级审计数据若要求断电一致性应考虑合适的事务存储与恢复协议。示意 DevEco 白色主题画面中的项目树叫AuditHarbor核心方法是stageAndPromote右侧模拟器展示PROMOTED和三条记录底部 HiLog 也明确标为“演示”。三条日志按业务定义依次是STAGING、READBACK_OK lines3、PROMOTED v7。这里没有声称它们来自真实的文件系统也没有用一张成功画面代替故障注入测试。四、失败不是“弹一个 Toast”就算收口写盘过程中可能遇到只读目录、空间耗尽、意外退出、同名文件冲突或描述符关闭失败。最重要的不是把每个错误都归为“保存失败”而是知道已经产生了哪些资源。若打开文件之前校验失败就没有句柄可关若写入发生异常finally必须执行关闭若读回不一致就不允许生成正式文件若关闭句柄本身失败则也不能直接向页面回报成功。第三段代码是启动页面时的受限清理示意只处理本任务、指定版本的临时文件。它不做全目录模糊匹配更不会删除用户已经导出的正式日志。若此时另一条导出流程正在使用同一个.part删除就会造成竞态因此调用者必须先获得单任务串行执行权本文把“只允许一个导出会话”当成业务前提而不是系统替我们提供的锁。function removeOwnStalePart(filesDir: string, busy: boolean): boolean { if (busy) { return false; } const temp: string ${filesDir}/audit-AL-2213-v7.jsonl.part; const target: string ${filesDir}/audit-AL-2213-v7.jsonl; if (fileIo.accessSync(target)) { return false; } if (!fileIo.accessSync(temp)) { return false; } fileIo.unlinkSync(temp); return true; }清理函数返回true只说明本轮成功清除了一个指定残留文件不代表“恢复了审计记录”。如果正式文件已经存在就不应根据临时文件推测正式文件损坏并覆盖它如果残留文件包含唯一的一份重要业务数据也不应直接删除应该先展示风险并走经过设计的恢复流程。本例只用可重新生成的演示事件因此可以把孤儿.part当作未提交的工作区。五、拿三条记录设计一套失败矩阵正常路径的约定输入是AL-2213/v7三条事件R-01/START、R-02/CHECK、R-03/CLOSE目标audit-AL-2213-v7.jsonl。负载构建成功后状态从READY到STAGING文件写入且读回一致后变为READBACK_OK完成重命名才展示PROMOTED。手机图中的“3 条已核验”仅是示例期望结果不是实际落盘数量的统计截图。故障验收至少要覆盖五项构造数据字段非法时不能创建.part写入一半时没有正式文件读回少一行时不能重命名目标文件已存在时不能复写下一次进入页面时只清理当前任务的废弃.part。每次都应核对句柄是否正确关闭、状态是否回到可重试、原有可用文件是否保持不变。对于真实审核环境还应把日志校验方式和权限策略作为独立安全需求不要让演示样例误导为完整审计合规方案。在工程里最容易造成事故的是两句不加限定的话“文件存在就是成功”“重命名了就一定不会丢”。我更愿意保留一个看起来啰嗦的阶段名PROMOTED让调用者知道它代表应用本次可观察到的写盘流程已完成但不等于设备级断电可靠性已经经过验证。这样下一次做异步写入、任务队列或用户文件分享时原有边界也不会被一句“沿用现成方法”带过去。参考资料华为开发者联盟 Core File Kit 文件基础操作 APIhttps://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-file-fs官方应用文件访问说明https://developer.huawei.com/consumer/en/doc/atomic-guides-V5/atomic-app-file-access-V5。部分在线细项未能完整读取接口签名应以目标 SDK 为准尚未进行目标 SDK 编译与实机故障注入。
本文的文件名、路径片段、状态、日志和界面均为演示构造不代表已经在 HarmonyOS 设备上写盘、断电或恢复成功。示例只讨论应用沙箱内的文件处理不涉及用户公共目录授权或云同步。一、一个看似正常的“导出成功”提示我见过的离线审核工具里最让人难查的问题通常不是根本写不出文件而是写出了一半页面却已经提示完成。用户第二天重新打开看到了一个存在的文件文件尾巴少了两条关键审计记录。此时若再让应用重新导出旧文件可能被覆盖真正的失败现场也就没了。与其把导出按钮做得很漂亮不如先问一句哪一个时刻才值得向用户展示成功本轮的第二个 Demo 叫AuditHarbor界面页面AuditExportPage任务AL-2213。它只导出三条预置的离线审核事件版本号固定v7R-01/START、R-02/CHECK、R-03/CLOSE。目标文件名为audit-AL-2213-v7.jsonl写入中间文件名为audit-AL-2213-v7.jsonl.part。界面最终状态使用PROMOTED因为“写完临时文件”和“准备给用户读取的正式文件”应该是两个事件。这里故意不用文件选择器也不碰相册。示意路径来自应用上下文的filesDir不是随手拼一个公共存储路径。Core File Kit 的fileIo负责访问应用文件但它并不替业务检查审计事件是不是重复、文本中是不是混入了换行、版本是不是已经生成。把格式、安全输入与写盘动作分开是这篇工程复盘的第一条约束。二、先决定要写什么再决定怎么写示例选用 JSON Lines每行是一条完整 JSON便于之后按行解析也能让单条字段内的换行被 JSON 字符串转义避免人工拼接冒出伪造的第二条记录。为便于复核我把三条事件的seq固定为一、二、三任务 ID 不从输入框自由拼进文件路径导出版本也由页面的固定流程提供而不是来自未经校验的任意文件名。第一段代码解决生成稳定负载的问题。它先校验任务、记录数量、顺序和字段白名单再按顺序形成 JSONL。实际项目还需要额外校验签名来源、时钟可信度、隐私字段以及允许导出的最大体积。本文不把“JSON 能解析”误说成“审计内容可信”这两件事是不同层面的校验。interface AuditRow { seq: number; recordId: string; action: string; } function buildAuditJsonl(taskId: string, rows: AuditRow[]): string { const actions: string[] [START, CHECK, CLOSE]; if (taskId ! AL-2213 || rows.length ! 3) { throw new Error(INVALID_BATCH); } let lines: string[] []; rows.forEach((row: AuditRow, i: number) { if (row.seq ! i 1 || row.recordId ! R-0${i 1} || row.action ! actions[i]) { throw new Error(INVALID_ROW); } lines.push(JSON.stringify({ taskId: taskId, seq: row.seq, recordId: row.recordId, action: row.action })); }); const payload: string lines.join(\n) \n; if (payload.length 4096) { throw new Error(TOO_LARGE); } return payload; }这个函数不持有文件句柄也没有线程需要释放任何异常都在接触磁盘前返回。长度限制只是演示上限以字符数量粗筛不能代替严格的 UTF-8 字节预算。中文、多字节字符或后续增加的附件必须按实际字节数校验。固定的R-01到R-03让案例容易对照不意味着真实业务只能写三条。批量数据很大时应切换为流式分段写入并处理背压而不是用一个巨大字符串占满 UI 线程内存。三、正式文件只能在读回验证后出现主要工程动作是先写.part关闭描述符再从同一路径读回校验内容最后才执行重命名。为什么把“关闭”排在读回前因为我们需要明确写操作已经结束不应在描述符还活着时混着读同一个文件。为何不用直接覆盖正式文件因为一旦写盘或校验失败用户应当继续看到此前有效版本而不是看到一个中途断掉的半成品。下面的代码采用单个导出者、固定批次版本和应用沙箱目录三项前提。fileIo.openSync、writeSync、closeSync、readTextSync、renameSync与unlinkSync都属于文件基础操作。它们并不帮我们做版本独占或任务排队正式文件已存在时直接拒绝复写。代码特意在finally关闭句柄避免异常分支遗漏释放。这里使用同步 API 是为了凸显操作顺序生产项目不应在 UI 主线程执行大文件同步 I/O。import { fileIo } from kit.CoreFileKit; function stageAndPromote(filesDir: string, payload: string): string { const temp: string ${filesDir}/audit-AL-2213-v7.jsonl.part; const target: string ${filesDir}/audit-AL-2213-v7.jsonl; let file: fileIo.File | null null; if (fileIo.accessSync(target)) { throw new Error(VERSION_EXISTS); } try { if (fileIo.accessSync(temp)) { fileIo.unlinkSync(temp); } file fileIo.openSync(temp, fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY); fileIo.writeSync(file.fd, payload); } finally { if (file ! null) { fileIo.closeSync(file); } } try { if (fileIo.readTextSync(temp) ! payload) { throw new Error(READBACK_MISMATCH); } fileIo.renameSync(temp, target); return target; } catch (error) { if (fileIo.accessSync(temp)) { fileIo.unlinkSync(temp); } throw error; } }读回检查可抓住短写、尾部残留、编码变更或内容不一致却不能证明存储介质在突然断电后一定保留最近写入。重命名与彻底持久化不是同一个保证是否支持同目录替换、错误码如何表达、是否需要额外持久化步骤应该按设备文件系统及目标 SDK 文档核对。尤其不能把当前示例称为跨文件事务或数据库级原子提交。生产级审计数据若要求断电一致性应考虑合适的事务存储与恢复协议。示意 DevEco 白色主题画面中的项目树叫AuditHarbor核心方法是stageAndPromote右侧模拟器展示PROMOTED和三条记录底部 HiLog 也明确标为“演示”。三条日志按业务定义依次是STAGING、READBACK_OK lines3、PROMOTED v7。这里没有声称它们来自真实的文件系统也没有用一张成功画面代替故障注入测试。四、失败不是“弹一个 Toast”就算收口写盘过程中可能遇到只读目录、空间耗尽、意外退出、同名文件冲突或描述符关闭失败。最重要的不是把每个错误都归为“保存失败”而是知道已经产生了哪些资源。若打开文件之前校验失败就没有句柄可关若写入发生异常finally必须执行关闭若读回不一致就不允许生成正式文件若关闭句柄本身失败则也不能直接向页面回报成功。第三段代码是启动页面时的受限清理示意只处理本任务、指定版本的临时文件。它不做全目录模糊匹配更不会删除用户已经导出的正式日志。若此时另一条导出流程正在使用同一个.part删除就会造成竞态因此调用者必须先获得单任务串行执行权本文把“只允许一个导出会话”当成业务前提而不是系统替我们提供的锁。function removeOwnStalePart(filesDir: string, busy: boolean): boolean { if (busy) { return false; } const temp: string ${filesDir}/audit-AL-2213-v7.jsonl.part; const target: string ${filesDir}/audit-AL-2213-v7.jsonl; if (fileIo.accessSync(target)) { return false; } if (!fileIo.accessSync(temp)) { return false; } fileIo.unlinkSync(temp); return true; }清理函数返回true只说明本轮成功清除了一个指定残留文件不代表“恢复了审计记录”。如果正式文件已经存在就不应根据临时文件推测正式文件损坏并覆盖它如果残留文件包含唯一的一份重要业务数据也不应直接删除应该先展示风险并走经过设计的恢复流程。本例只用可重新生成的演示事件因此可以把孤儿.part当作未提交的工作区。五、拿三条记录设计一套失败矩阵正常路径的约定输入是AL-2213/v7三条事件R-01/START、R-02/CHECK、R-03/CLOSE目标audit-AL-2213-v7.jsonl。负载构建成功后状态从READY到STAGING文件写入且读回一致后变为READBACK_OK完成重命名才展示PROMOTED。手机图中的“3 条已核验”仅是示例期望结果不是实际落盘数量的统计截图。故障验收至少要覆盖五项构造数据字段非法时不能创建.part写入一半时没有正式文件读回少一行时不能重命名目标文件已存在时不能复写下一次进入页面时只清理当前任务的废弃.part。每次都应核对句柄是否正确关闭、状态是否回到可重试、原有可用文件是否保持不变。对于真实审核环境还应把日志校验方式和权限策略作为独立安全需求不要让演示样例误导为完整审计合规方案。在工程里最容易造成事故的是两句不加限定的话“文件存在就是成功”“重命名了就一定不会丢”。我更愿意保留一个看起来啰嗦的阶段名PROMOTED让调用者知道它代表应用本次可观察到的写盘流程已完成但不等于设备级断电可靠性已经经过验证。这样下一次做异步写入、任务队列或用户文件分享时原有边界也不会被一句“沿用现成方法”带过去。参考资料华为开发者联盟 Core File Kit 文件基础操作 APIhttps://developer.huawei.com/consumer/en/doc/harmonyos-references/js-apis-file-fs官方应用文件访问说明https://developer.huawei.com/consumer/en/doc/atomic-guides-V5/atomic-app-file-access-V5。部分在线细项未能完整读取接口签名应以目标 SDK 为准尚未进行目标 SDK 编译与实机故障注入。
