【听见课堂 HarmonyOS NEXT 实战系列 11】先定义接口再选数据库：ClassroomRepository 的可替换数据层

m0_74969023

352人浏览 · 2026-08-31 01:44:20

m0_74969023 · 2026-08-31 01:44:20 发布

【听见课堂 HarmonyOS NEXT 实战系列 11】先定义接口再选数据库：ClassroomRepository 的可替换数据层

很多 ArkUI 项目在第一版里会直接从页面调用 RelationalStore：按钮点击后拼 RdbPredicates，列表刷新时执行 SQL，删除时顺手清理几张表。功能少时看似高效，等到要增加内存降级、测试替身、迁移或多页面刷新，页面就会同时承担展示、业务规则和数据一致性。

听见课堂没有让页面认识 RdbStore。它先定义 ClassroomRepository，再提供 RelationalStore 和内存两套实现；ClassroomService 只依赖接口，ArkUI 只依赖 Service。本文结合当前源码，拆解接口粒度、状态约束、事务边界和替换步骤。

ClassroomRepository 可替换数据层

一、先看真实依赖方向

项目的数据调用链是：

ArkUI Page
  -> ClassroomService
  -> ClassroomRepository
     -> RelationalClassroomRepository
     -> InMemoryClassroomRepository

这条链最重要的性质是单向依赖。页面不知道 SQL，Service 不知道表名，Repository 不处理页面提示。具体数据库实现可以变化，但候选任务必须人工确认、已确认任务才能完成等业务语义保持稳定。

二、Repository 接口暴露的不是 CRUD 表名

当前 ClassroomRepository 只有一个领域接口：

export interface ClassroomRepository {
  getTodayCourse(): Promise<CourseSummary>;
  getTranscript(): Promise<Array<TranscriptSegment>>;
  replaceTranscript(courseId: string, transcript: Array<TranscriptSegment>): Promise<boolean>;
  getScanNotes(): Promise<Array<ScanNote>>;
  getTasks(): Promise<Array<TaskItem>>;
  updateCourse(course: CourseSummary): Promise<boolean>;
  deleteCourse(courseId: string): Promise<boolean>;
  clearAllData(): Promise<boolean>;
  updateScanText(scanId: string, text: string, source?: string): Promise<boolean>;
  updateTask(taskId: string, title: string, dueText: string, dueAtMillis: number): Promise<boolean>;
  confirmTask(taskId: string): Promise<boolean>;
  unconfirmTask(taskId: string): Promise<boolean>;
  setTaskCompleted(taskId: string, completed: boolean): Promise<boolean>;
  toggleTask(taskId: string): Promise<boolean>;
}

它没有暴露 querySql()、表名或 ValuesBucket，而是使用课程、字幕、扫描、任务这些领域语言。调用方关注“替换某课程字幕”而不是“删除后批量插入 transcript_segments”。

三、读操作和写操作要分开理解

接口可以分为三类：

1. 快照读取

getTodayCourse()、getTranscript()、getScanNotes()、getTasks() 返回当前 canonical data。Service 再据此构造复盘、任务中心、历史搜索等页面快照。

2. 领域更新

updateScanText()、updateTask()、confirmTask() 等方法表达一个明确状态变化。它们避免页面直接更新某个字段，同时为两套 Repository 保留相同契约。

3. 组合与破坏性操作

replaceTranscript()、deleteCourse()、clearAllData() 可能影响多条或多表记录，需要原子性和明确失败语义。事务属于具体 Repository，而二次确认和用户提示属于页面与 Service。

这种分类能阻止接口退化成“万能 execute”。如果 Repository 只提供 execute(sql)，上层仍会泄漏数据库细节，替换实现没有实际价值。

四、为什么 Service 只持有接口

ClassroomService 的构造函数接收 ClassroomRepository：

export class ClassroomService {
  private repository: ClassroomRepository;
  private storageMode: string = '内存降级';

  constructor(repository: ClassroomRepository) {
    this.repository = repository;
  }

  useRepository(repository: ClassroomRepository, storageMode: string): void {
    this.repository = repository;
    this.storageMode = storageMode;
  }
}

Service 可以在应用初始化成功后切换到 RelationalStore，也可以在初始化失败时继续使用内存实现。页面调用 getTaskCenterSnapshot() 时，无需判断当前数据来自数据库还是内存。

Repository、Service 与数据源边界

五、业务规则应该放在 Service 还是 Repository

一个实用判断是：规则是否与数据源无关。

例如任务标题和截止时间不能为空，这是所有实现都要遵守的输入规则，放在 Service：

async updateTask(taskId: string, title: string, dueText: string): Promise<boolean> {
  const normalizedTitle: string = title.trim();
  const normalizedDueText: string = dueText.trim();
  if (normalizedTitle.length === 0 || normalizedDueText.length === 0) {
    return false;
  }
  const dueAtMillis: number = TaskDateResolver.resolveDueText(normalizedDueText);
  return this.repository.updateTask(taskId, normalizedTitle, normalizedDueText, dueAtMillis);
}

而“更新哪张表、如何构造 predicates、影响了几行”与数据源相关，属于 Repository。两层都可以做防御：当前两套 Repository 都会拒绝编辑已确认任务，从而保证即使调用方绕过部分页面流程，也不会静默改写稳定事实。

六、事务为什么必须留在具体实现

替换课堂字幕不是单条 UPDATE，而是删除课程旧字幕后按顺序插入新字幕。如果中途失败，旧数据和新数据不能各留一半。

RelationalStore 实现使用事务：

store.beginTransaction();
try {
  await this.deleteWhere(TABLE_TRANSCRIPT, 'course_id', courseId);
  for (let index: number = 0; index < transcript.length; index++) {
    await store.insert(TABLE_TRANSCRIPT, {
      id: transcript[index].id,
      course_id: courseId,
      sort_order: index + 1
    });
  }
  store.commit();
  return true;
} catch (error) {
  store.rollBack();
  throw new Error('Failed to replace classroom transcript.');
}

内存实现不需要数据库事务，但必须保持同样的对外语义：参数无效返回 false，成功后整组替换，不能先修改一半再返回失败。

七、接口让内存降级真正可替换

InMemoryClassroomRepository implements ClassroomRepository 是可替换性的直接证明。它用数组保存课程、字幕、扫描和任务，却仍然支持确认、撤销确认、完成、撤销完成、删除课程和清空全部数据。

初始化逻辑只在组合根选择实现：

export async function initializeClassroomData(context: common.UIAbilityContext): Promise<boolean> {
  try {
    const repository = new RelationalClassroomRepository();
    await repository.initialize(context);
    classroomService.useRepository(repository, 'RelationalStore');
    return true;
  } catch (error) {
    classroomService.useRepository(fallbackRepository, '内存降级');
    return false;
  }
}