词库是一份 950762 字节的 words.json,放在 resources/rawfile 里,4423 个词条、321 个有内容的单元、40 个年级、4 个教材版本。WordRepository 在启动时把它一次性解成内存对象,然后建三张 Map 索引,此后所有查询都是 O(1)。整个解析过程没有用 TaskPool、没有分片、没有懒加载,因为一次解码加一次建表在这个体量上够快,而复杂化会让「什么时候数据才可用」这个判断多出几个状态。

一次解码与三层嵌套

加载入口只有 12 行:

async load(context: Context): Promise<void> {
  if (this.loaded) {
    return;
  }
  const buffer: Uint8Array = await context.resourceManager.getRawFileContent('words.json');
  const decoder = util.TextDecoder.create('utf-8');
  const text: string = decoder.decodeToString(buffer);
  const raw = JSON.parse(text) as RawWordsJson;
  this.rawData = raw;
  this.parseData(raw);
  this.loaded = true;
}

getRawFileContent 返回的是 Uint8Array,不是字符串,所以中间必须有一步 TextDecoder。decodeToString 一次把 95 万个字节转成一个 string,再交给 JSON.parse 建树。这两步是整条链路上最重的两下 —— 一次内存翻倍(字节数组 + 字符串同时存在),一次全量对象化。

loaded 标志放在方法最前面而不是最后,配合 if (this.loaded) return 实现幂等。EntryAbility 和 FormAbility 各自可能调一次,第二次直接返回,不会重复解析。

this.rawData = raw 这一行值得单独说。它把整棵解析树挂在实例上长期持有,但 getRawData() 这个 getter 在全项目里没有任何调用点:

getRawData(): RawWordsJson | null {
  return this.rawData;
}

也就是说,那份原始对象树(约 95 万字节文本对应的完整 JS 对象图)在应用整个生命周期里都无法被回收,换来的是一个没人用的入口。getVersionInfo() 同样如此 —— 它按 code 线性遍历 versions 找版本,但 GradeSelectPage 是直接用 versions 数组渲染的,没有调它。这两个方法留在类里不产生错误,只是让内存账面上多了一笔。

parseData 是三层嵌套循环:版本 → 年级 → 单元 → 词条。

private parseData(raw: RawWordsJson): void {
  for (const rawVersion of raw.versions) {
    const versionInfo: VersionInfo = {
      code: rawVersion.code,
      name: rawVersion.name,
      shortName: rawVersion.shortName,
      note: rawVersion.note,
      tagline: rawVersion.tagline,
      gradeCount: rawVersion.gradeCount,
      wordCount: rawVersion.wordCount
    };
    this.versions.push(versionInfo);

    for (const rawGrade of rawVersion.grades) {
      const gradeKey: string = GradeUtils.normalizeGradeKey(rawGrade.grade);
      const units: UnitInfo[] = [];

      for (const rawUnit of rawGrade.units) {
        if (!rawUnit.words || rawUnit.words.length === 0) {
          continue;
        }
        const words: WordInfo[] = [];
        for (let i: number = 0; i < rawUnit.words.length; i++) {
          const rawWord: RawWordJson = rawUnit.words[i];
          const phonetic: string = rawWord.phonetic ? rawWord.phonetic.trim() : '';
          const category: string = rawWord.category ? rawWord.category.trim() : '单词';
          const wordId: string = `${rawVersion.code}_${gradeKey}_${rawUnit.unitNo}_${i}`;
          const wordInfo: WordInfo = {
            id: wordId,
            text: rawWord.word,
            phonetic: phonetic,
            meaning: rawWord.meaning,
            category: category,
            versionCode: rawVersion.code,
            versionShortName: rawVersion.shortName,
            grade: rawGrade.grade,
            gradeKey: gradeKey,
            unitNo: rawUnit.unitNo,
            unitTopic: rawUnit.topic,
            unitEmoji: rawUnit.topicEmoji
          };
          words.push(wordInfo);
          this.allWords.set(wordId, wordInfo);
        }

单元这一层有一句 continue:词表为空的单元直接跳过,不进 units 数组,也不进 allUnits。这个词库里恰好有一个这样的单元 —— pep 版本五年级上册的 Unit 3「综合词汇」,words 是空数组。JSON 顶部的 stats 字段声明 units: 322,实际进内存的是 321 个。

年级这一层也有对应的跳过:

        if (units.length === 0) {
          continue;
        }

        const gradeInfo: GradeInfo = {
          grade: rawGrade.grade,
          gradeKey: gradeKey,
          unitCount: units.length,
          wordCount: rawGrade.wordCount,
          units: units
        };
        const gradeMapKey: string = `${rawVersion.code}_${gradeKey}`;
        this.allGrades.set(gradeMapKey, gradeInfo);
      }
    }
  }
}

40 个年级每一个都至少有一个非空单元,所以这一句 continue 在这份数据上不会命中,但它是必要的 —— 否则 getGrades 里「至少一个单元有词」的过滤条件就要多写一遍。

复合 id 与三张表

wordId 的拼法是 ${versionCode}_${gradeKey}_${unitNo}_${index},例如 pep_grade_3_up_1_0。它同时承担两个角色:Map 的键,以及一个「可反解」的位置坐标。

三张表各管一层查询:

表键的形态值示例键
allGrades${code}_${gradeKey}GradeInfopep_grade_3_up
allUnits${code}_${gradeKey}_${unitNo}UnitInfopep_grade_3_up_1
allWords${code}_${gradeKey}_${unitNo}_${i}WordInfopep_grade_3_up_1_0

三张表的键是前缀包含关系:词 id 的前三段正好是单元键,单元键的前两段正好是年级键。这个设计让「我手上有一个 wordId,想知道它属于哪个单元」这类问题不需要额外字段 —— 切一刀取前三段即可(UnitRowItem 就是反过来用这套规则现场拼 id 回查学习的,见统计那篇)。

查接口都罩在这三张表上:

getGradeByKey(versionCode: string, gradeKey: string): GradeInfo | undefined {
  const key: string = `${versionCode}_${gradeKey}`;
  return this.allGrades.get(key);
}

getUnits(versionCode: string, gradeKey: string): UnitInfo[] {
  const grade: GradeInfo | undefined = this.getGradeByKey(versionCode, gradeKey);
  if (grade) {
    return grade.units;
  }
  return [];
}

getUnit(versionCode: string, gradeKey: string, unitNo: number): UnitInfo | undefined {
  const key: string = `${versionCode}_${gradeKey}_${unitNo}`;
  return this.allUnits.get(key);
}

getWords(versionCode: string, gradeKey: string, unitNo: number): WordInfo[] {
  const unit: UnitInfo | undefined = this.getUnit(versionCode, gradeKey, unitNo);
  if (unit) {
    return unit.words;
  }
  return [];
}

getWordById(wordId: string): WordInfo | undefined {
  return this.allWords.get(wordId);
}

getWords 与 getUnit 是两层,前者返回 unit.words,后者返回整个 UnitInfo。allUnits 与 UnitInfo.words 指向同一个数组(不是拷贝),所以从任一入口拿到的 WordInfo 都是同一批对象 —— CardLearnPage 里把 repo.getWords(...) 的结果直接赋给 @State words,改动数组会污染仓库。目前没有页面这么干,因为学习数据全部另存在 StorageService 里。

批量查询只做一次循环:

getWordsByIds(wordIds: string[]): WordInfo[] {
  const result: WordInfo[] = [];
  for (const id of wordIds) {
    const word: WordInfo | undefined = this.allWords.get(id);
    if (word) {
      result.push(word);
    }
  }
  return result;
}

FavoritePage 用它把收藏的 id 列表换成词对象。这里 if (word) 的过滤是必要的 —— 用户切换教材版本后,旧版本产生的 wordId 在新版词库的 allWords 里仍然存在(因为四份词库同时加载),但如果词库本身被裁剪或换版本,就会拿到 undefined,直接 push 会让列表渲染时崩在 word.text 上。

年级列表的双过滤

getGrades 是全类里唯一一个遍历全表的查询:

getGrades(versionCode: string): GradeInfo[] {
  const result: GradeInfo[] = [];
  this.allGrades.forEach((grade: GradeInfo, key: string) => {
    if (key.startsWith(`${versionCode}_`)) {
      let hasWords: boolean = false;
      for (const unit of grade.units) {
        if (unit.words.length > 0) {
          hasWords = true;
          break;
        }
      }
      if (hasWords) {
        result.push(grade);
      }
    }
  });
  return result;
}

按 code + '_' 前缀筛版本,再确认年级下至少有一个非空单元。pep 这个前缀同时也是 pep 与其他版本的分界 —— 四个版本的 code 分别是 pep、xinqidian、waiyan-y1、waiyan-y3,没有一个版本 code 是另一个的前缀,所以 startsWith 不会串版本。

年级选择页面

图:词库过滤后呈现给用户的年级选择列表。

四个版本的实际结构:

版本code年级有词单元词条最厚年级最厚单元
人教版 PEPpep847136926272
人教版新起点xinqidian127689312940
外研版一年级起点waiyan-y112118113311725
外研版三年级起点waiyan-y3880102815247

pep 只有 8 个年级(三年级到六年级),词条数却是最多的 1369,平均每个年级 171 词;waiyan-y1 摊到 12 个年级后每年级只有 94 词。「最厚单元 72 词」这个数字决定了 CardLearnPage 一次最多要渲染多少张卡片。

GradeSelectPage 的版本按钮没有遍历 versions,而是硬切了前四个:

Row() {
  ForEach(this.versions.slice(0, 2), (v: VersionInfo) => {
    this.versionButton(v)
  })
}
Row() {
  ForEach(this.versions.slice(2, 4), (v: VersionInfo) => {
    this.versionButton(v)
  })
}

两行各放两个,slice(0, 2) 与 slice(2, 4)。这段代码依赖 versions 的顺序与 JSON 里的书写顺序一致 —— parseData 里 this.versions.push(versionInfo) 按遍历顺序追加,JSON.parse 保留数组顺序,所以确实一致。但如果哪天词库加了第五个版本,它不会自动出现在界面上,因为 slice(2, 4) 把上界钉死在了 4。

字段缺失的两级兜底

词库里 4423 条记录,其中 2495 条没有 phonetic(占 56.4%),3913 条的 category 是 null(占 88.5%)。这两个比例说明兜底不是防御性代码,而是主路径:

const phonetic: string = rawWord.phonetic ? rawWord.phonetic.trim() : '';
const category: string = rawWord.category ? rawWord.category.trim() : '单词';

音标缺失给空串,分类缺失给「单词」。trim 同时处理了「字段存在但是空白」的情况。这两种兜底在 UI 上产生了不同的效果:

字段缺失时UI 表现
phonetic''卡片与列表都不渲染音标行
category'单词'卡片底部始终有一个标签

WordCard 里的判断是 if (this.phoneticStr.length > 0),StatsDetailPage 与 FavoritePage 也是同样的写法,空串直接不占位。category 走另一条路 —— 它无条件渲染:

Text(this.categoryStr)
  .fontSize(11)
  .fontColor(AppColors.TEXT_DARK)
  .backgroundColor('#40FFFFFF')
  .borderRadius(AppSizes.TAG_RADIUS)
  .padding({ left: 10, right: 10, top: 4, bottom: 4 })
  .margin({ right: 6 })

所以 3913 个词条会在卡片上显示一个「单词」标签。这是把缺失信息显式化的选择:有标签总比标签位置空着好,尤其卡片底排有「分类 + Unit N」两个标签并排,少一个会让对齐看起来歪。

卡片侧还有第三级兜底,出现在 FormAbility 里:

'phonetic': word.phonetic || '/--/',

|| 而不是 ??,空串也会落到 /--/。这里必须给一个非空值,因为桌面卡片的布局对文本高度敏感 —— 4*4 卡片里音标行的高度变化会让下面三个元素整体位移,两次刷新之间出现跳动。给一个固定占位的 /--/ 换稳定的布局。

phonetic 的存储格式也值得一提:原始数据里没有斜杠,pen、pensl 都是裸音标,斜杠由 UI 补:

Text(`/${this.phoneticStr}/`)
  .fontSize(18)
  .fontColor(AppColors.TEXT_GRAY)
  .margin({ bottom: 16 })

这层「数据不带装饰、展示时才包裹」的分工让同一份 phonetic 能在三处用不同格式呈现:卡片用 /{phonetic}/、详情列表也用 /{phonetic}/、桌面卡片直接用 phonetic。如果解析时就把斜杠拼进去,桌面卡片就得再剥一次。

索引表的内存账

4423 个 WordInfo 对象,每个 12 个字段:

字段类型说明
idstring复合键,约 24 字符
textstring单词原文
phoneticstring无音标时为 ''
meaningstring中文释义
categorystring缺失时为 '单词'
versionCodestring与版本对象共享引用
versionShortNamestring与版本对象共享引用
gradestring与年级对象共享引用
gradeKeystring与年级对象共享引用
unitNonumber单元号
unitTopicstring与单元对象共享引用
unitEmojistring与单元对象共享引用

真正独占的数据是前五个字段,后面四个字符串都是对上层对象的引用(rawVersion.code 这类赋值赋的是同一个字符串的引用,不是拷贝)。粗算每个对象 150 到 200 字节,4423 个约 0.7 到 0.9 MB,加上三张 Map 的哈希开销和那份被 rawData 扣住的原始树,整个词库常驻成本在 3 MB 量级。

这个量级不值得做懒加载。词库全是只读数据,没有失效问题,没有并发写入,也没有增量更新 —— load() 只在启动时跑一次。把 4423 条放进内存换来的收益很直接:getWords 返回的是引用,CardLearnPage 渲染一个单元不需要任何异步等待;getWordById 是哈希查找,HistoryPage 把 200 条历史翻译成词对象是一次 200 次 Map.get。

如果词库涨到十万条,这套结构会先在三处出现压力:JSON.parse 的单次耗时、allWords 的哈希桶数量、以及 getGrades 的全表遍历(虽然只在上层调用一次)。到那个体量再谈分片和 TaskPool 才有意义。

词库这一层到这里就完整了:一次解码、三层遍历、三张前缀嵌套的表、两级字段兜底。上层拿到的是可以随便查的只读对象,写入完全不在这一层发生。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐