HarmonyKit | 鸿蒙新特性复盘：从 5 到 10 个工具的开发方法论

引言：两个阶段，一次架构验证

HarmonyKit 的开发分两个阶段。首版 5 个工具（JSON、Base64、时间戳、URL、哈希）在一个下午完成编码——目标是最快跑通完整流程：页面导航、组件复用、工具函数封装。二版 5 个工具（正则、UUID、颜色、进制、文本统计）在另一个下午完成——目标是验证架构的扩展性。

两个阶段的代码量相近（每个工具约 100-200 行），但第二阶段的效率提高了约 3 倍。原因不是"写熟了"，而是第一阶段搭建的三层架构（model/utils/components/pages）在第二阶段展现出了真正的价值——新增工具不需要修改任何现有代码。

项目仓库：https://atomgit.com/VON-/harmony-kit

第一阶段学到的五件事

1. 静态方法优于实例方法

所有 utils 类都是纯静态方法：Base64Utils.encode()、JsonUtils.format()、HashUtils.hash()。无 this，无状态，无副作用。好处：可独立测试（不依赖 UI 上下文）、可跨页面复用（无状态冲突）、类型安全（string in → string out）。

// utils/JsonUtils.ets 示例
export class JsonUtils {
  static format(input: string): string {
    const obj: Object = JSON.parse(input);
    return JSON.stringify(obj as object, null, 2);
  }

  static validate(input: string): boolean {
    try {
      JSON.parse(input);
      return true;
    } catch (e) {
      return false;
    }
  }
}

静态方法的另一个优势是单元测试极其简单——不需要创建实例，不需要构造组件环境，直接调用即可验证结果。这在 ArkTS 的 ohosTest 或 LocalUnitTest 中非常方便。

2. 固定高度优于自适应高度

ToolCard 的 158vp 固定高度解决了 2 列网格的对齐问题。自适应高度（让内容撑开）导致的"同行不同高"在视觉上非常明显。Grid 默认行为是每行高度由最高项决定——这导致短内容的卡片底部留白。固定高度让所有卡片在网格中整齐排列。

// ToolCard 的高度策略
GridItem() {
  ToolCard({ tool: tool })
}
.width('100%')
.height(158)  // 统一高度，视觉对齐

当时我测试了三种方案：自适应高度（内容撑开）、minHeight（最小高度+弹性扩展）、固定高度。最终固定高度胜出——它保证了 2 列网格在任何屏幕尺寸下都能保持视觉对齐，且不需要额外的计算逻辑。代价是长内容可能被截断，但 ToolCard 的内容（图标 + 名称 + 描述 + 颜色标识）在 158vp 内恰好完整展示，不存在截断问题。

3. 颜色体系需要提前规划

10 个工具 10 种主题色。如果新增工具时"随便选一个好看的颜色"，很快就会遇到两个工具颜色过近导致混淆的问题。提前规划配色体系——相邻工具在色环上拉开至少 60 度、冷色调和暖色调交错排列——是视觉一致性的基础。

具体的配色方案如下：

工具	色值	色相	冷暖
JSON 格式化	#007AFF	210°	冷
Base64 编解码	#FF9500	30°	暖
时间戳转换	#34C759	140°	冷
URL 编解码	#FF3B30	0°	暖
哈希计算	#5856D6	240°	冷
正则测试器	#FF2D55	345°	暖
UUID 生成器	#00C7BE	175°	冷
颜色转换	#AF52DE	285°	暖
进制转换	#FF6482	355°	暖
文本统计	#36D1A0	155°	冷

暖冷交错排列的目的是：在网格视图中，相邻卡片颜色差异最大化，用户可以通过颜色快速定位工具。如果 10 个工具全用冷色调，网格看起来就像一片蓝色海洋，视觉区分度极差。

4. 编译错误是最好的文档

ArkTS 的严格类型系统（禁止 any、禁止解构参数、禁止对象字面量类型）在开发初期带来了大量编译错误。但每个错误都是一次代码规范的引导——“这里需要一个 interface”“这个 JSON.parse 的返回值需要显式类型标注”。"修复编译错误"的过程就是"学习 ArkTS 最佳实践"的过程。

第一阶段遇到的所有编译错误可以归纳为 6 种类型：

错误代码	原因	修复方法
arkts-no-any-unknown	隐式 any	显式标注类型
arkts-no-obj-literals-as-types	内联对象类型	提取为 interface
arkts-no-destruct-params	解构参数	展开为局部变量
arkts-no-untyped-obj-literals	无类型对象字面量	声明 interface 变量
arkts-strict-ets	build() 内声明变量	移到外部方法
arkts-no-evolutionary-type	类型推断不完整	完整标注类型

每一个错误都被记录下来，并在第 35 篇文章中做了完整汇总。这种"从错误中学习"的方式比读官方文档更高效——因为你遇到的就是你实际用到的。

5. 快速编译循环是无价的

增量编译 1-1.5 秒的反馈速度让"改一行 → 编译 → 模拟器验证"的循环非常流畅。在一个需要视觉调试的 UI 项目中，编译速度直接影响开发效率。hvigor 的 --daemon 模式和增量编译机制是这个速度的保障。

与之对比的是全量编译（clean build）约 7-8 秒。在开发过程中，我养成了一个习惯：只在必要时做全量编译（比如切换分支、升级 SDK），日常开发保持 daemon 模式下的增量编译。

第二阶段验证的扩展性

新增 5 个工具的标准流程只需要四步：

1. model/ToolItem.ets 的 TOOL_LIST 追加对象
2. pages/tools/ 创建页面文件
3. main_pages.json 添加路由
4. 如果逻辑复杂，utils/ 创建工具类

每一步不涉及任何现有代码的修改——无需改动 Index.ets、无需改动 ToolCard、无需改动 CopyButton。这是"零破坏性扩展"。

实际的开发节奏是这样的：

步骤 1（30 秒）: TOOL_LIST 追加一条
步骤 2（15 分钟）: 编写工具页面 UI + 交互逻辑
步骤 3（10 秒）: main_pages.json 加一行路由
步骤 4（可选）: 如果逻辑复用度高则抽取 utils
验证（20 秒）: 运行模拟器查看效果

一个工具从 0 到完成大约需要 15-20 分钟。这个效率对于"两下午完成 5 个工具"的目标是足够的。

组件复用模式

除了页面层面的零修改扩展，组件层面的复用也值得总结。HarmonyKit 的组件复用有三个层次：

层次一：通用组件。 ToolCard 和 CopyButton 被所有工具页共享。ToolCard 在主页网格中渲染每个工具入口，CopyButton 在每个工具页的输出区域提供"复制到剪贴板"功能。

层次二：工具函数。 utils/ 目录下的每个工具类都是纯静态方法，可以被任何页面调用。例如 JsonUtils.format() 在 JSON 格式化页面中使用，也可以被其他页面导入用于数据处理。

层次三：Builder 片段。 @Builder 装饰的函数在页面内部复用。文本统计工具的 6 个统计卡片通过一个 StatCard Builder 生成，进制转换的 5 种进制结果显示通过一个 ResultRow Builder 生成。

这三个层次覆盖了从"跨页面复用"到"页面内复用"的全频谱需求。

代码统计

指标	数据
总文件数	约 50 个
纯源代码	约 2000 行 ArkTS
HAP 体积	约 3MB
utils 行数	约 400 行
components 行数	约 100 行
pages 行数	约 1200 行
平均每工具	约 120 行
编译 warning	0（迁移 UIContext 后）

从代码行数分布可以看到：pages 占了 60%，utils 占了 20%，components 只占 5%。这个比例是合理的——工具应用的核心在于页面交互（pages），业务逻辑（utils）次之，通用 UI 组件（components）最少。components 行数少说明复用度高——150 行的代码支撑了 10 个页面的 UI 一致性。

架构的复利效应

花 70% 时间做架构设计，功能实现只需 30%。如果反过来——初期一把梭写所有 10 个工具——结果可能是每个工具有不同的 UI 模式、CopyButton 有 3 种写法、错误处理有 5 种风格。重构的代价远超预先设计的成本。

HarmonyKit 的架构复利体现在：

• 第一个工具花的时间最多（约 25 分钟），因为需要搭建页面模板、验证路由、测试 ToolCard 和 CopyButton 的集成
• 第二个到第五个工具的平均时间约 15 分钟，页面模板已经成熟，只需要替换业务逻辑
• 第六到第十个工具的平均时间约 10 分钟，模板和工具函数都稳定了，新增工具只需要写核心交互代码

如果从第一个工具开始就直接写 10 次，没有架构抽象，每个工具的时间可能始终是 25 分钟——因为每个工具都要自己处理路由、CopyButton 集成、错误处理。架构投资的复利就在这里。

如果重来一次

• 先定义 CopyButton 和错误处理规范，再写工具页
• 第一版就应该用 HdsTabs 而非基础 Tabs（避免后续迁移成本）
• 主题色体系在第一个工具之前就规划好
• 单元测试在写完前三个工具时就建立而非之后补
• 把 main_pages.json 的路由声明自动化（脚本生成而非手动维护）

最后一点值得展开。目前 10 个工具页面的路由声明是手动维护在 main_pages.json 中的。当工具数量增长到 20 个、30 个时，手动维护的出错概率会显著上升。一个简单的脚本——扫描 pages/tools/ 目录下的文件并自动生成 main_pages.json——就可以解决这个问题。

项目仓库：https://atomgit.com/VON-/harmony-kit