错误处理与日志记录

核心要点是有唯一的收敛点来处理异常，并把“用户看到的错误”与“进日志的错误”区分开来。

收敛点：`Debug.handle(e)` 与 `Debug.log(...)`

try {
   arriscado();
} catch (Exception e) {
   Debug.handle(e);        // 统一记录并处理（单一漏斗）
}
Debug.log("estado:", valor);   // 自由诊断

框架的动画和任务在内部已通过 Debug.handle 捕获 Throwable。为什么要有一个收敛点： 一个未处理的异常在绘制线程上会拖垮当前帧——把它汇集起来可避免崩溃，并提供一个统一的埋点位置。

对特定错误做出反应（不要吞掉一切）

try (SqliteDb db = SqliteDb.open("app.db")) {
   db.execute("INSERT INTO cliente(email) VALUES(?)", email);
} catch (SqliteException e) {
   if (e.code == Sqlite.CONSTRAINT) Hint.show("E-mail já cadastrado", 2000);   // 19
   else if (e.code == Sqlite.BUSY)  Hint.show("Banco ocupado, tente de novo", 2000);  // 5
   else Debug.handle(e);
}

SqliteException.code 携带 SQLite 代码（Sqlite.OK/BUSY/CONSTRAINT/LOCKED/...）。同样适用于其他类型化结果（例如生物识别的 AuthResult.ERROR）。

后台回调的错误 → 用 `onUI` 在 UI 上展示

回调（网络、GPS、BLE）运行在绘制线程之外。要提醒用户，请用 onUI 编组：

new Thread(() -> {
   try { sincronizar(); }
   catch (Exception e) {
      Component.onUI(() -> Hint.show("Falha ao sincronizar", 2000));   // Hint = 非阻塞
      Debug.handle(e);
   }
}).start();

Hint.show(...) 用于非阻塞提示；当需要用户做决定时用 Alert。
区分开： 用户需要看到的（Hint/Alert）vs. 只进日志的（Debug.log/handle）。

调试标志

Debug.traceKeyboard、Debug.showFPS、Debug.beepOnGC 有助于在开发期间进行诊断。

最佳实践

对于无法专门处理的情况，用一个收敛点（Debug.handle）。
用对用户有用的信息处理特定代码（CONSTRAINT、BUSY）。
后台错误 → onUI + Hint/Alert；绝不要在回调中直接触碰 UI。

常见错误

空的 catch (Exception e) {}——把问题吞掉了。
向用户展示原始堆栈跟踪（应使用带清晰信息的 Hint/Alert；堆栈进日志）。
未使用 onUI 就从后台线程触碰 UI。

另请参阅

对话框与模态框 · 后台工作