Tratamento de erros e logging

O ponto central é ter um funil único de exceções e separar “erro que o usuário vê” de “erro para o log”.

O funil: `Debug.handle(e)` e `Debug.log(...)`

try {
   arriscado();
} catch (Exception e) {
   Debug.handle(e);        // loga e trata de forma uniforme (funil único)
}
Debug.log("estado:", valor);   // diagnóstico livre

Animações e tasks do framework já capturam Throwable via Debug.handle internamente. Por quê um funil: uma exceção não tratada na paint thread derruba o frame — canalizá-la evita crash e dá um ponto único para instrumentar.

Reaja a erros específicos (não engula tudo)

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 traz o código SQLite (Sqlite.OK/BUSY/CONSTRAINT/LOCKED/...). O mesmo vale para outros resultados tipados (ex.: AuthResult.ERROR da biometria).

Erros de callbacks de fundo → mostre na UI com `onUI`

Callbacks (rede, GPS, BLE) rodam fora da paint thread. Para avisar o usuário, marshale com onUI:

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

Hint.show(...) para avisos não bloqueantes; Alert quando exige decisão do usuário.
Separe: o que o usuário precisa ver (Hint/Alert) vs. o que vai só para o log (Debug.log/handle).

Flags de depuração

Debug.traceKeyboard, Debug.showFPS, Debug.beepOnGC ajudam a diagnosticar durante o desenvolvimento.

Boas práticas

Um funil (Debug.handle) para o que não é tratável especificamente.
Trate códigos específicos (CONSTRAINT, BUSY) com mensagem útil ao usuário.
Erro de fundo → onUI + Hint/Alert; nunca toque a UI direto no callback.

Erros comuns

catch (Exception e) {} vazio — engole o problema.
Mostrar stack trace cru ao usuário (use Hint/Alert com mensagem clara; stack vai ao log).
Tocar a UI a partir de thread de fundo sem onUI.

Veja também

Diálogos e modais · Trabalho em background