HarmonyKit | 鸿蒙新特性实践：10 个工具的错误处理统一策略

引言：错误处理是产品功能，不是技术补丁

工具类应用最容易被忽略的是错误处理。“用户输入正确 → 点按钮 → 拿到结果"这个 Happy Path 覆盖了 80% 的使用场景。但剩下 20% 决定了用户是"信任这个工具"还是"觉得它有 bug”。

在 Base64 解码框中粘贴普通文本、在时间戳输入框中输入"昨天下午"、在正则表达式框中输入一个未闭合的括号——这些是真实用户行为。HarmonyKit 为这 20% 的场景建立了四层错误处理策略。这篇文章从每个工具的代码出发，拆解空输入拦截、格式验证、运行时异常和边界处理四个层次的实现方式，以及错误文案的撰写原则。

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

层次一：空输入静默忽略

用户尚未输入任何内容就点击了操作按钮。可能是误触，也可能用户在测试"这个按钮点了会怎样"。HarmonyKit 的处理是不执行操作 + 不展示错误：

doEncode() {
  if (!this.input.trim()) return;  // 静默忽略
  this.output = Base64Utils.encode(this.input);
}

为什么不是 “doDecode()” 展示红色错误"请输入文本"？因为用户在空白状态点按钮大概率是无意的。而如果用户输入了一些文字后再点按钮——即使格式不对——这表明了操作意图，此时需要反馈。

区分标准：输入框非空 + 操作失败 → 需要提示；输入框完全空白 → 静默忽略。 前者是"操作失败了"，后者是"误触"。

层次二：格式验证 + 语义化提示

用户输入了内容但格式不符合工具要求。以下是五个工具的差异化处理：

JSON 格式化——精准定位。 JSON.parse 的错误信息包含了行号和位置（如"Unexpected token at position 42"）。这个信息对开发者的价值远超"格式无效"——能立刻定位到 json 字符串中第 42 个字符处的语法错误。直接展示原生错误信息。

Base64 解码——语义化翻译。 Base64 解码失败时底层抛出异常包含"Invalid character at index 5"的技术细节，但 HarmonyKit 不直接展示——翻译为"解码失败，请检查输入是否为有效的 Base64 字符串"。因为用户不需要知道"第 5 个字符不合法"，只需要确认自己粘贴的内容是不是 Base64。

时间戳格式——格式模板内置在错误信息中。 “日期格式无效，请使用 yyyy-MM-dd HH:mm:ss”——不只告诉用户"你错了"，还告诉他"正确的是什么"。错误信息本身就包含了正确的格式模板。

颜色值——输入拆分与逐项检测。 RGB 输入被 split 为三个数字后逐项检测。如果用户输入了"255, 128"，提示"无效的 RGB 值，格式: 255, 128, 0"——用占位符展示了三个数字的完整格式。

正则表达式——引擎错误直接展示。 new RegExp('\\') 抛出 SyntaxError: Invalid regular expression: /\\/: \\ at end of pattern。正则语法错误通常不需要翻译——调试正则的开发人员看得懂引擎错误信息。

层次三：运行时异常捕获

async doHash() {
  try {
    let algo = this.algorithm as 'MD5' | 'SHA1' | 'SHA256';
    this.output = await HashUtils.hash(this.input, algo);
  } catch (e) {
    this.output = '计算失败: ' + (e as Error).message;
  }
}

关键设计：错误信息展示在输出区域而非弹窗或 Toast。正常情况下这个位置展示计算结果，异常情况下展示错误信息。用户不需要转移视线去找"哪里报错了"。

为什么不弹窗？工具应用的操作流程是"输入→操作→看结果→复制"——弹窗中断这个流程。Toast 的问题是一闪而过，用户可能没看清。输出区域是持久性的——用户有时间仔细阅读错误信息。

层次四：边界情况处理

每个工具有独特的边界：

时间戳超大值：输入 13 位毫秒时间戳时自动除以 1000 转为秒级处理。阈值 10000000000（100亿）。

进制转换负数：parseInt('-10', 16) 返回 -16，用 isNaN 检测。

正则无匹配：match() 返回 null 时展示"无匹配项"——这是正常结果，不是错误。用灰色而非红色。

UUID 数量边界：最少 1 个（if (count > 1) count--），最多 50 个（if (count < 50) count++）。按钮在边界自动禁用。

文本统计空输入：所有统计数字归零，不抛异常。

错误文案四原则

原则一：区分"错误"和"正常结果"。 红色（#ff3b30）用于真正的错误——正则语法错误、Base64 解码失败。灰色用于"无匹配"这类非异常的空白结果。

原则二：提供可操作的指引。 "格式无效"不够——"请使用 yyyy-MM-dd HH:mm:ss"才是可操作的信息。

原则三：控制技术细节粒度。 开发工具的用户是开发者，可以接受技术性错误信息（如"Unexpected token at position 42"）。但不要暴露内部实现细节（如堆栈 trace、内部方法名）。

原则四：错误信息集中展示在固定位置。 操作区下方、输出区上方。用户知道去哪里看错误。

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