列表新增一条记录后再执行一次查询，既增加往返，也会在并发写入时读到已经变化的结果。Returning接口允许写操作同时返回指定字段，适合把数据库生成的主键、版本号和更新时间作为同一次提交的结果交给页面。

方案面向HarmonyOS 6.1.1 Release SDK（API 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;
}

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): Promise<WriteReceipt | 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或资源版本；仅检查组件是否存在，无法阻止旧任务污染新页面。

冲突策略必须由业务显式选择

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

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相关开发文档