rawfile 资源与强类型词库加载器：schema / data / source 三层版本

开口练的核心能力——本地检测填充词、犹豫词、笼统词——建立在三个 JSON 词库上实时词库16 填充 14 犹豫 20 笼统、情感词库146 词、分层候选词库9 组 97 条。这批数据有几个硬约束原版产品JS 实现已在用行为必须 1:1一个词都不能差离线可用是产品卖点不能依赖网络下发词库会迭代但迭代节奏和代码发布不同步版本要能独立演进。结论打进 HAP 的 rawfile配上严格的版本契约和加载校验。这篇讲这套机制。1. 为什么是 rawfile鸿蒙给静态数据几条路写死在 ArkTS 常量里、放resources/base/element/资源文件、放resources/rawfile/、网络下发。逐个排除代码常量数据与代码同编译改一个词要全量构建且几百个词条混在代码里数据 diff 没法审。element 资源面向字符串/颜色/尺寸这类会被系统按配置语言、深浅色解析的资源词库 JSON 不是这个语义。网络下发冷启动引入网络依赖离线卖点直接破产。rawfile任意格式文件原样打进 HAP运行时ResourceManager按文件名读字节——正解。文件布局命名带项目统一的sl_前缀entry/src/main/resources/rawfile/ ├── sl_realtime_lexicon.json ├── sl_emotion_lexicon.json └── sl_tiered_lexicon.json注意路径是resources/rawfile/而不是resources/base/rawfile/——rawfile 不参与 base/dark 那套配置解析直接放 resources 根下。2. 三层版本号schema、data、source 各管一件事每个词库 JSON 的顶层是一个信封带三个版本号{ schemaVersion: 1.0.0, dataVersion: 2026.07.14, sourceVersion: expression-trainer1.0.0, payload: { } }三个版本回答三个不同的问题版本回答的问题代码怎么处理schemaVersion我的结构你还能读懂吗semver 校验 主版本兼容性检查主版本不符直接拒绝加载dataVersion这批数据是哪一版透传进 Catalog供日志/报告标注本次分析基于哪版词库sourceVersion数据从哪个上游移植来溯源凭证对着原版产品核对行为基线时用schema 检查是硬门槛const SUPPORTED_SCHEMA_MAJOR 1; function assertSupportedMajor(version: string, file: string): void { const major version.split(.)[0]; if (major ! SUPPORTED_SCHEMA_MAJOR) { throw lexErr( SpeakLabLexiconErrorCode.UNSUPPORTED_SCHEMA_VERSION, file, 不支持的 schemaVersion 主版本 ${major}当前只支持 ${SUPPORTED_SCHEMA_MAJOR} ); } }只检查主版本是刻意的minor/patch 演进必须向后兼容加字段不删字段主版本变了才允许破坏性格式调整——届时旧版 App 拒绝加载新词库而不是读错结构默默算出错误结果。数据格式契约和 API 契约是同一个道理。3. Parser零 I/O 的纯函数校验严到计较旧拼写解析层和 I/O 层严格分离。SpeakLabLexiconParser文件头写着它的姿态接受文本/字节不含 I/O、UI、ASR 或 AI 依赖。失败时抛异常绝不返回部分结果。纯函数解析器的好处是测试可以脱离设备——Node 脚本拿同样的 JSON 喂同样的契约跑 oracle 对拍B08 讲算法时细说Hypium 里也能直接构造非法文本断言各种错误码。校验强度远超JSON.parse 不炸就行固定计数基线写进代码。词库词条数不是读出来多少算多少而是冻结的行为基线const REALTIME_FILLER_COUNT 16; const REALTIME_HEDGE_COUNT 14; const REALTIME_VAGUE_COUNT 20; const EMOTION_COUNT 146; const TIERED_GROUP_COUNT 9; const TIERED_TOTAL_COUNT 97;解析后逐组核对分层词库 9 个分组的名字、顺序、每组条目数全部固定连每条候选的词数6 个都是常量。少一个词、组序错了都是加载失败。这批数字就是原版产品的行为基线代码把它们变成运行时断言——词库错了不是数据差一点是构建事故必须当场炸。连历史拼写错误都显式处理。原版数据里有个字段拼成了vagueToPresice正确应为vagueToPrecise。Parser 显式识别这个旧拼写并完成迁移而不是把错误拼写传染进新代码/** 旧拼写已显式迁移为 vagueToPrecise。 */ const STALE_FIELD_SPELLING vagueToPresice;还有个 ArkTS 特有的小坑值得一提ArkTS不支持in操作符检测JSON 对象有没有这个键得用Object.keys遍历/** ArkTS 不支持 in 操作符改用 Object.keys 检测键存在性。 */ function hasKey(obj: Recordstring, Object, key: string): boolean { const keys Object.keys(obj); for (let i 0; i keys.length; i) { if (keys[i] key) return true; } return false; }从 JS 移植数据解析代码时这类语言差异点是最容易漏的。4. RepositoryI/O 收口与分层降级I/O 层SpeakLabLexiconRepository只做两件事读字节、定降级策略。读取本身是ResourceManagerTextDecoder两行核心async function readRawfile(mgr: resourceManager.ResourceManager, name: string): Promisestring { try { const bytes: Uint8Array await mgr.getRawFileContent(name); const decoder new util.TextDecoder(utf-8); return decoder.decodeToString(bytes); } catch (e) { throw new SpeakLabLexiconError(SpeakLabLexiconErrorCode.IO_ERROR, name, …); } }真正的设计在降级策略ADR-003 冻结三个词库的可选性不一样容错必须分层。sl_realtime_lexicon.json 必需 → 失败 整体初始化失败抛异常 sl_emotion_lexicon.json 辅助 → 失败 EMOTION_DEGRADEDrealtime 照常可用 sl_tiered_lexicon.json 辅助 → 失败 TIERED_DEGRADEDrealtime 照常可用 两者均失败 → AUXILIARY_DEGRADED代码把策略写得很直白let emotionOk false; try { emotion parseEmotionCatalog(await readRawfile(mgr, FILE_EMOTION), FILE_EMOTION); emotionOk true; } catch (_e) { // 情感词库降级realtime 保留 }两个方向的红线都在这里不用空词库伪装成功。realtime 失败时宁可整体拒绝服务也不能装一份空词库让分析成功地什么都检测不出来——那是拿错误结果冒充正确结果。降级是显式状态不是静默吞错。辅助词库失败会写进 Catalog 的 availability 字段上层 UI 可以据此提示情感建议暂不可用日志里也有明确事件。静默 catch 和显式降级区别是后者能被看见、被测试、被追责。加载时机上这套加载挂在 B03 讲的启动就绪闸门里首屏渲染前ensureSpeakLabShellCompositionReady完成词库加载就绪 promise 进程级去重、失败可重试。词库就绪后设置里的自定义词 overlay 才有附着点。5. 小结静态业务数据随包走 rawfileresources/rawfile/命名带统一前缀ResourceManager TextDecoder 读取。三层版本号各司其职schema 管兼容性主版本硬门槛、data 管数据迭代、source 管移植溯源。Parser 是零 I/O 纯函数固定计数基线即行为断言宁炸不糊弄历史拼写显式迁移注意 ArkTS 无in操作符。降级分层必需数据失败整体失败辅助数据失败显式 availability 降级不用空数据伪装成功不静默吞错。