从 API 12 升级到 API 26：英语学习 App 的渐进式迁移路线图

一、引言

HarmonyOS API 版本从 12（5.0）到 26（7.0 Beta）经历了 4 个大版本升级。对于我们的英语学习 App 而言，这意味着需要在 11 个模块中同步适配 API 变更、替换废弃 API、并逐步接入新特性。

一次性升级所有模块风险高、工作量大。因此，我们制定了一条渐进式的迁移路线图——遵循"先编译通过 → 再新特性接入 → 后废弃 API 替换"的三步策略，按模块优先级分批验证，确保每个阶段都有可交付的中间产物。本文将从 API 变更分析入手，详细阐述各模块的迁移优先级和具体方案。

二、API 版本关键变更点

2.1 API 12 → API 20（5.0 → 6.0）

变更类型	具体内容	影响范围
V2 装饰器	引入 @ObservedV2/@Trace/@ComponentV2/@Local/@Param	全部组件
路由系统	NavPathStack 取代 router.replace	features 模块
音频 API	Media Kit 重构，AVPlayer 变更	AudioPlayer
资源管理	$r 引用规范变化	UI 全局

2.2 API 20 → API 21（6.0.0）

变更类型	具体内容	影响范围
ContainerReader	新增容器断点组件	布局组件
systemMaterial	新增系统材质属性	UI 全局
Live View	实况窗 API	学习页面
@ReusableV2	全局复用池	列表组件

2.3 API 21 → API 23（6.1.0）

变更类型	具体内容	影响范围
方舟引擎	GC 优化、渲染加速	全部
HMAF	智能体框架	首页、推荐
端云大模型	AI Kit 统一接口	AI 功能

2.4 API 23 → API 26（7.0 Beta）

变更类型	具体内容	影响范围
AgentCard	智能体卡片	桌面入口
ArkTS Skill	脚本扩展	挑战、报告
星盾安全	加密存储、TEE	数据持久化
纯血鸿蒙	移除 APK 兼容层	全部
FrameNode	帧级更新	动画组件

三、废弃 API 替换方案

3.1 @State → @Local/@Param

这是 API 20 引入 V2 装饰器体系后最大的变更。迁移方案：

// 旧方案（API 12）
@Component
export struct WordCardComponent {
  @State wordText: string = '';
  @Prop meaning: string = '';

  build() {
    Text(this.wordText)
  }
}

// 新方案（API 20+）
@ComponentV2
export struct WordCardComponent {
  @Local wordText: string = '';   // 组件内部状态
  @Param meaning: string = '';     // 父组件传入数据（只读）

  build() {
    Text(this.wordText)
  }
}

迁移要点：

• @State → @Local：保持内部可变状态
• @Prop → @Param：保持只读父传数据
• @Link → 回调函数：子组件通过回调通知父组件

3.2 其他废弃 API

废弃 API	替换方案	受影响模块
router.replace()	NavPathStack.pushPath()	features 模块
@Observed	@ObservedV2	数据模型
window.getLastWindow()	UIAbilityContext.getWindow()	EntryAbility
media.createAVPlayer()	avPlayer.createAVPlayer()	AudioPlayer

四、模块兼容性配置策略

在迁移过程中，不同模块需要设置不同的兼容版本：

// commonLib/oh-package.json5 — 核心库，最低兼容 API 12
{
  "apiType": "stageMode",
  "minAPIVersion": 12,
  "targetAPIVersion": 26
}

// homePage/oh-package.json5 — 业务模块兼容 API 20+
{
  "apiType": "stageMode",
  "minAPIVersion": 20,
  "targetAPIVersion": 26
}

// entry/oh-package.json5 — 入口模块使用最高 API
{
  "apiType": "stageMode",
  "minAPIVersion": 20,
  "targetAPIVersion": 26,
  "compatibleSdkVersion": 20  // 兼容模式
}

compatibleSdkVersion 是 API 26 新增的配置项。设置为 20 意味着应用在 API 26 设备上运行时会启用兼容模式，使用新的运行时但限制部分新 API 的使用。

五、迁移优先级排序

5.1 各模块评估

模块	依赖层级	迁移工作量	影响面	优先级
commonLib	0（最底层）	中	所有模块	P0
EntryAbility	1	中	入口	P0
homePage	2	大	主要 UI	P1
minePage	2	中	个人中心	P1
topicPage	2	大	专题学习	P2
base_select	1	小	通用组件	P1
select_category	1	小	分类组件	P2
answer_questions	1	中	答题	P2
AudioPlayer	1（commonLib 内）	小	语音播放	P1
Aggregated Payment	2	小	支付	P3
feedback/search	2	小	辅助功能	P3

5.2 核心组件 commonLib 优先升级

commonLib 是所有其他模块的依赖，必须最先完成迁移。包含的迁移项：

1. 数据模型：WordCard、LearningPlan、StatisticsData 改用 @ObservedV2 + @Trace
2. 工具类：PreferenceUtil、Logger、RouterModule 替换废弃 API
3. 管理器：LearningPlanManager、StatisticsManager、NewWordManager 保持接口不变

六、迁移后回归测试方案

6.1 测试策略

迁移完成后，需要回归测试覆盖以下维度：

测试维度	测试内容	工具/方法
编译测试	所有模块编译通过	hvigor assemble
功能测试	10 个核心功能页面正常	手动 E2E + LocalUnit
性能测试	启动时间、列表滑动、动画帧率	HiProfiler
兼容性测试	API 20/21/23/26 四档版本	虚拟机/真机矩阵
存储测试	Preferences 数据读写正确	自动测试

6.2 分阶段回归流程

Phase 1: commonLib + AudioPlayer 迁移 → 编译通过 + 单元测试
Phase 2: EntryAbility + 三个 features 模块 → 编译通过 + 功能测试
Phase 3: 全部 components 模块 → 编译通过 + 功能测试
Phase 4: 全量回归测试 + 性能测试
Phase 5: 新特性接入（ContainerReader、Live View 等）
Phase 6: 废弃 API 清理

每个阶段预计耗时 2-3 天，总计约 15 个工作日完成全量迁移。

七、"先编译通过→新特性接入→废弃 API 替换"三步策略

第一步：先编译通过

目标是让项目在新 API 版本下编译通过，不做任何优化和新特性接入：

1. 更新 oh-package.json5 中的 targetAPIVersion 为 26
2. 修复编译错误（主要是废弃 API 和类型变化）
3. 使用 @SuppressDeprecation 临时屏蔽废弃警告
4. 确保所有模块编译通过，应用可以正常运行

第二步：新特性接入

编译通过后，逐步接入新版本的特有能力：

1. ContainerReader 替换全局 BreakpointModel
2. @ReusableV2 增加组件复用池
3. systemMaterial 替换自定义毛玻璃效果
4. Live View 实况窗增加锁屏学习进度

第三步：废弃 API 替换

最后清理所有废弃 API：

1. 移除 @SuppressDeprecation 注解
2. 将临时保留的旧 API 全部替换
3. 清理兼容层代码
4. 最终确认无任何 Deprecation 警告

八、总结

从 API 12 到 API 26 的迁移是一项系统工程，涉及 11 个模块、数十个 API 变更点。通过"commonLib 优先、按模块分批、三步递进"的策略，我们可以在保证应用稳定性的前提下平滑地完成升级。迁移完成后，英语学习 App 将获得方舟引擎性能提升、星盾安全增强、AgentCard 桌面入口、端侧大模型等 7.0 新特性的全面赋能。