HarmonyOS 6.1+ 新特性实战（21）：ArkData Returning事务回读与冲突处理方案

列表新增一条记录后再执行一次查询既增加往返也会在并发写入时读到已经变化的结果。Returning接口允许写操作同时返回指定字段适合把数据库生成的主键、版本号和更新时间作为同一次提交的结果交给页面。方案面向HarmonyOS 6.1.1 Release SDKAPI 24系统Kit调用进入适配层命令约束、状态归并和恢复策略进入可测试的业务层。范围包含状态与资源生命周期设计、失败恢复和验收合同不包含业务内容生产、服务端协议改造以及特定厂商网页或媒体源的兼容承诺。写后再查会引入哪类竞态方案把新增、更新、删除统一描述为WriteCommand包含table、values、predicates、returningFields和expectedVersion。仓库在同一事务中执行命令并返回WriteReceipt页面只根据receipt刷新目标行不再对整表做一次无条件查询。状态数量不是越多越好。每个状态必须回答三个问题当前允许哪些命令、收到迟到事件怎样处理、页面退出后是否还可以更新UI。下面的状态对象携带operationId新的操作开始后旧操作回调会被拒绝。export enum ReturningWriteState { PREPARING preparing, IN_TRANSACTION in_transaction, WRITING writing, RETURNING returning, COMMITTING committing, CONFLICT conflict } export interface ReturningWriteSnapshot { state: ReturningWriteState; progress: number; message: string; operationId: number; updatedAt: number; } export type ReturningWriteEvent | { type: START; operationId: number } | { type: PROGRESS; operationId: number; progress: number } | { type: SUCCESS; operationId: number } | { type: FAIL; operationId: number; message: string }; export function acceptEvent( snapshot: ReturningWriteSnapshot, event: ReturningWriteEvent ): boolean { return event.type START || event.operationId snapshot.operationId; }设计对象保存内容不应该保存的内容页面状态可展示阶段、进度、错误摘要系统对象和页面Context适配器Kit实例、监听注册、资源句柄ArkUI组件引用业务记录operationId、版本、恢复点未脱敏的敏感原始数据诊断信息阶段耗时、错误码、能力检测Token、图片原始内容Returning结果只带必要字段Returning字段限制为id、version和updatedAt避免把大字段重新搬回内存。更新命令把expectedVersion放入谓词返回行数为零时进入CONFLICT由页面选择刷新、覆盖或保留草稿。批量导入要么整批提交要么整批回滚不向UI暴露半成功集合。这套分层把系统事实和产品行为分开Kit适配器负责获得事实领域对象决定是否接受事件页面只渲染快照。更换API版本或加入真机能力时只需要替换适配器状态归并和异常策略仍可在模拟器中重复验证。批量写入怎样划定事务边界下面是主题专属的接入或核心算法代码。示例刻意保留资源创建、前置条件和清理逻辑因为高频故障往往出现在成功调用之外。import { relationalStore } from kit.ArkData; export interface WriteReceipt { id: number; version: number; updatedAt: number; } export class ReturningRepository { constructor(private store: relationalStore.RdbStore) {} async updateTitle(id: number, version: number, title: string): PromiseWriteReceipt | undefined { const tx await this.store.createTransaction(); try { const predicates new relationalStore.RdbPredicates(notes) .equalTo(id, id) .and() .equalTo(version, version); const values: relationalStore.ValuesBucket { title, version: version 1, updatedAt: Date.now() }; const config: relationalStore.ReturningConfig { columns: [id, version, updatedAt] }; const result await tx.updateWithReturning(values, predicates, config); await tx.commit(); if (result.rows.length 0) return undefined; return result.rows[0] as WriteReceipt; } catch (error) { await tx.rollback(); throw error; } } }代码迁入业务工程时应把错误码转换为稳定的领域错误不让页面直接判断系统错误字符串。对于异步回调还要在写入状态前比较operationId或资源版本仅检查组件是否存在无法阻止旧任务污染新页面。冲突策略必须由业务显式选择故障输入状态变化恢复动作版本谓词不匹配返回零行并进入CONFLICT刷新后由用户决定批量中一条失败事务回滚页面不插入部分结果Returning字段过多缩减columns避免大对象回传结果集未关闭统一finally释放活动游标回到零异常注入按钮用于稳定复现应用侧恢复路径。真实错误发生时诊断记录同时保存错误码、权限结果、设备能力和用户可见状态敏感原始数据不进入日志截图只呈现与问题直接相关的结果。LiteResultSet的资源关闭责任页面层不直接调用Kit而是通过动作按钮驱动同一份状态模型。这样既能在系统能力可用时接真实适配器也能在模拟器缺少硬件时验证错误页面、幂等逻辑和资源清理。Component struct ReturningWritePanel { State stateText: string PREPARING; 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 IN_TRANSACTION; this.progress 20; this.append(开始ArkData Returning事务回读); } private injectFailure(): void { this.stateText CONFLICT; this.append(已注入可恢复故障); } build() { Column({ space: 12 }) { Text(ArkData Returning事务回读).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%) } }准备同版本双端更新、批量插入中间失败、删除后回读主键和大字段排除四组用例。每组记录事务编号、受影响行数、返回字段和最终版本冲突发生时数据库内容保持先提交者版本失败批次不留下孤立行。Returning不能代替业务版本控制。数据库返回了行只能说明谓词命中并执行成功若谓词没有携带版本后写入者仍可能静默覆盖先写入者。删除操作返回主键便于同步内存列表但不应把完整敏感行作为删除回执。批量接口要限制每批大小避免一次事务长期占锁。对旧系统缺少新接口的情况适配层可以回退到事务内写入加精确主键查询并保持相同WriteReceipt合同。迁移完成后通过指标比较SQL次数、冲突数和事务耗时而不是只比较一条正常路径的延迟。回滚路径也要纳入自动化回归。验收记录至少包括SDK版本、模拟器系统版本、操作顺序、预期状态、实际状态和截图编号。快速点击、返回再进入、故障后重试和页面销毁是必测项涉及资源的主题还要显示活动对象计数涉及异步任务的主题要验证迟到结果不会改变当前页面。四组并发写入验收矩阵这套方案的技术闭环由“输入约束—状态模型—Kit适配—异常恢复—可观察验收”组成。业务状态不持有系统对象适配器不直接操作页面异常路径有明确的恢复动作后续SDK升级时可以分别回归每一层。官方资料ArkData相关开发文档