# Tratamento de erros e logging

> Debug.handle como funil de exceções, reagir a erros específicos e mostrar falhas ao usuário.

Source: https://crossfly.dev/pt/docs/best-practices/tratamento-de-erros-e-logging — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 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(...)`
```java
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)
```java
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`:
```java
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](/docs/ui/navigation/dialogs-and-modals) · [Trabalho em background](/docs/data-and-services/background-work)