Pular para conteúdo

0020 — Serde (build-time) e HTTP declarativo

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-17 · Decidido em: 2026-06-17

Contexto

A serialização HTTP usava micronaut-jackson-databind (Jackson por reflexão em runtime); os @Serdeable nos DTOs estavam inertes. E o TelegramService montava o POST ao Telegram à mão com java.net.http.HttpClient + serialização manual de JSON. Ambos eram código caseiro onde o framework oferece o primitivo recomendado.

Decisão

  • Serialização HTTP → micronaut-serde-jackson (o serde, recomendado pelo Micronaut): geração de serializers em build-time (sem reflexão), allowlist de segurança (só tipos @Serdeable são (de)serializáveis — evita desserialização acidental de tipos arbitrários). Os DTOs de resposta ganharam @Serdeable. O serde 3.0.0 usa Jackson 3 (tools.jackson) como backend — sem conflito com o Jackson 3 já adotado (decisão 0019).
  • Jackson direto permanece para a árvore JSON: CoolifyClient (parse de JsonNode) e ProcessamentoJsonExporter (export canônico) — o serde não tem API de árvore equivalente, e o serde-jackson traz o tools.jackson.databind transitivo.
  • TelegramService → @Client declarativo (TelegramApi): some o HttpClient manual, a montagem de JSON e o JacksonObjectMapperFactory (que perdeu o injetor). Custo aceito: micronaut-http-client passa a ser dependência de runtime.
  • CoolifyClient NÃO migra para @Client: o tratamento de erro de domínio dele é load-bearing (cada falha vira mensagem específica que o reset propaga) e a URL/token vêm de config em runtime — fica em java.net.http de propósito.

Consequências

  • HTTP (de)serialização build-time + allowlist de segurança; DTOs explicitamente @Serdeable. TelegramService ~50 linhas mais enxuto e declarativo.
  • O contrato JSON (de resposta e do export canônico) é preservado — suíte completa verde (293), incl. ProcessamentoConformidadeTest.
  • O projeto passa a ter micronaut-http-client no runtime (revertendo o antigo "sem dependência HTTP nova" — decisão consciente, só pro Telegram).

Alternativas consideradas

  • Manter jackson-databind reflexivo: funciona, mas é o caminho não-recomendado e os @Serdeable ficariam inertes. Descartado por alinhamento + segurança.
  • Migrar tudo para serde (inclusive a árvore do Coolify/exporter): o serde não oferece API de árvore equivalente; reescrever seria pior. Mantém-se jackson direto ali.
  • @Client também no Coolify: descartado — perderia o tratamento de erro de domínio.