从崩溃到流畅：我的HarmonyOS记账应用开发实战与认知升级

LIYan_Leo

516人浏览 · 2026-03-25 19:57:14

LIYan_Leo · 2026-03-25 19:57:14 发布

“不是代码写错了，是开发思维需要重构。”
—— 一个HarmonyOS初学者的血泪开发日记

一、起因：从“Hello World”到“无法编译”的深渊

2026年2月，我决定用HarmonyOS 3.1（API 9）开发一款轻量级记账应用。作为Web开发者，我以为只需照搬Vue的组件化思维就能快速上手。然而，当我在DevEco Studio中按下Build按钮时，编译器抛出的错误像一记重拳：

ERROR: Cannot find module '@ohos/ability'
ERROR: Cannot find name 'RecordItem'
ERROR: Could not resolve "./AccountBookAbility"

那一刻，我意识到：HarmonyOS不是“Web+原生”的简单叠加，而是一套全新的开发范式。

二、致命错误：三个“致命伤”暴露认知盲区

1. 依赖配置的“配置即代码”哲学（最致命）

错误操作：
在oh-package.json5中留空dependencies，以为系统模块会自动加载。

真实教训：

HarmonyOS的系统模块（如@ohos/ability）必须显式声明，这是与NPM生态的本质区别。
修复后配置：
"dependencies": {
  "@ohos/ability": "latest",
  "@ohos/data/relationalStore": "latest",
  "@ohos/arkui": "latest"
}
关键认知：HarmonyOS将依赖管理从“运行时”前置到“配置阶段”，配置即代码是基石。

2. 文件路径的“目录结构迷宫”（最易忽视）

错误操作：
在pages/Index.ets中导入AccountBookAbility时使用"./AccountBookAbility"。

真实教训：

AccountBookAbility.ets位于src/main/ets/，而Index.ets在src/main/ets/pages/，正确路径应为../AccountBookAbility。
调试时刻：
当我在DevEco Studio的“Project Structure”视图中拖动文件时，终于看清了目录层级——HarmonyOS对路径的敏感度远超Web项目。

3. 类型缺失的“编译器审判”（最隐蔽）

错误操作：

import { RdbStore, RdbPredicates, BusinessError } from '@ohos/data/relationalStore';
// 缺少 RecordItem 和 ValueBucket

真实教训：

RecordItem和ValueBucket是relationalStore导出的关键类型，必须显式导入。
修复后：
import { RecordItem, ValueBucket } from '@ohos/data/relationalStore';
认知升级：
ArkTS的类型安全不是可选项，而是编译器强制的契约。当编译器拒绝any时，你才真正开始理解HarmonyOS的工程化思维。

三、破局：重构开发思维的三步法

第一步：理解HarmonyOS的“配置驱动”哲学

不再依赖npm install：系统模块通过oh-package.json5声明，DevEco Studio自动匹配SDK版本
关键动作：
```
# 修复依赖后执行
hvigor sync
```
认知飞跃：

“不是代码写错了，是开发工具链的规则未被遵守。”

第二步：建立“路径即代码”的目录意识

目录结构对照：

src/main/ets/
├── AccountBookAbility.ets    # 全局能力类
└── pages/
    └── Index.ets            # 页面组件

核心原则：
所有导入路径必须基于ets/根目录计算，./表示当前目录，../表示上一级。

第三步：拥抱类型安全的开发范式

错误代码（Web思维残留）：
```
let data = []; // 用any替代
```

正确代码（HarmonyOS思维）：

let data: RecordItem[] = []; // 显式类型

编译器反馈：
Use explicit types instead of "any" → 这是HarmonyOS的开发圣经。

四、技术沉淀：从“能跑”到“可维护”的架构设计

1. 数据库生命周期管理（能力层）

export class AccountBookAbility extends AbilityStage {
  private db: relationalStore.RdbStore | null = null;

  onWindowStageCreate(windowStage: WindowStage) {
    this.initDatabase() // 异步初始化
      .then(() => windowStage.loadContent('pages/Index'));
  }

  onDestroy() {
    this.db?.close(); // 安全释放资源
  }

  private initDatabase(): Promise<void> {
    return new Promise((resolve, reject) => {
      relationalStore.getRdbStore(context, config, (err, store) => {
        // 初始化表结构...
        resolve();
      });
    });
  }
}

设计价值：
将数据库初始化绑定到AbilityStage生命周期，避免在页面中重复操作，符合HarmonyOS的“能力即服务”理念。

2. 安全的事务操作（业务层）

private deleteRecord(id: number) {
  const predicates = new RdbPredicates('records').equalTo('id', id);
  
  db.beginTransaction()
    .then(() => db.delete(predicates))
    .then(() => db.commit())
    .catch((err) => {
      db.rollback(); // 事务回滚
      ToastDialog.show({ message: `删除失败: ${err.message}` });
    });
}

设计价值：
通过beginTransaction/commit/rollback确保数据一致性，避免了Web开发中常见的“数据不一致”陷阱。

五、认知升维：HarmonyOS开发的核心思维

传统Web开发	HarmonyOS开发	认知升级点
依赖通过npm安装	依赖在配置文件声明	配置即代码
路径基于项目根目录	路径基于`ets/`根目录	路径敏感性
`any`是常见选择	编译器强制类型安全	类型即契约
组件状态管理简单	通过`@State`+`AppStorage`实现全局状态	状态管理架构化