Pular para o conteúdo principal

Boas Práticas

Recomendações de uso da plataforma Nukk, reunidas a partir das capacidades documentadas em cada área. O objetivo é ajudar a decidir quando usar o quê — Flow, Backend App, Frontend App, Add-on, ZTNA, Secret, Config Map, MCP — em vez de listar features isoladas.

1. Secrets e Config Maps​

  • Nunca coloque uma credencial em texto puro dentro de um Flow, Backend App ou Frontend App. Se o valor é sensível (senha, token, chave de API, connection string com credencial embutida), ele é uma Secret — o valor fica mascarado mesmo depois de salvo.
  • Se o valor é apenas configuração por ambiente, mas não é sigiloso (URL de um serviço, nome de host, flag de feature), use um Config Map — não crie uma Secret só para evitar hardcode; isso esconde informação que poderia ser consultada livremente e dificulta debugging.
  • Regra prática: se o valor pode ser mostrado em texto puro sem risco, é Config Map; se ele concede acesso a algo, é Secret.
  • Sempre vincule explicitamente a Secret/Config Map ao Flow/App que vai usá-la, na aba correspondente — a existência da Secret na plataforma não é suficiente, ela precisa ser selecionada no consumidor.
  • Use properties diferentes por ambiente (test, production) dentro da mesma Secret/Config Map (ex: HOST, PASSWORD) em vez de criar uma Secret por ambiente — isso mantém a mesma expressão ({$.env.nome.property}) funcionando em qualquer ambiente sem mudar o código do Flow/App.
  • Nomeie Secrets e Config Maps de forma que o propósito fique óbvio (db-credentials, db-config) — facilita auditoria de quem usa o quê.

2. API Management​

  • Trate o API Gateway como a única porta de entrada para APIs — não crie caminhos alternativos de exposição direta de um Backend App ou Flow além do necessário; centralizar em Routes facilita segurança, rate limit e observabilidade.
  • Toda API que vai para produção deveria ter Security Type = API Key (ou equivalente), com um Consumer dedicado por integração/cliente — evite reaproveitar o mesmo Consumer para múltiplos sistemas, para poder revogar/limitar o acesso de um consumidor sem afetar os outros.
  • Configure rate limits (por segundo e por minuto) compatíveis com a capacidade real do backend — um Consumer sem limite pode derrubar um Flow/App downstream em caso de uso indevido ou bug no lado do cliente.
  • Ajuste os timeouts (read/send/connect) para o comportamento real da integração — manter o padrão de ~60s em toda rota esconde lentidão; rotas rápidas devem ter timeouts mais agressivos para falhar rápido, e integrações lentas por natureza precisam de timeouts maiores para não cortar respostas válidas.
  • Só crie uma Route quando a intenção é realmente expor a API para o consumidor final — Flows e Backend Apps internos, que só se comunicam entre si, não precisam de uma Route pública.

3. Quando usar Flow (integração e automação)​

Use um Flow quando o problema é essencialmente orquestrar chamadas entre sistemas — consultar um banco, chamar uma API externa, transformar um payload, enviar uma notificação, reagir a um evento ou a um agendamento. É o lugar certo para:

  • Integrações com CRMs, ERPs, provedores de nuvem, bancos de dados, mensageria — o catálogo de conectores já resolve autenticação, serialização e retry, então a integração fica só na configuração dos campos, não em código de baixo nível.
  • Automações disparadas por Scheduler, webhook (HTTP), evento (Event Consumer) ou mensagem (WhatsApp Trigger) — qualquer processo que "acontece quando X ocorre", sem precisar de uma interface própria.
  • Lógica que se beneficia de IA dentro do próprio fluxo (componente AI Agent) — interpretar texto livre, resumir documentos, decidir dinamicamente entre múltiplas sub-tarefas.

Não force um Flow a virar uma aplicação completa. Se a necessidade é uma interface de usuário rica, ou uma lógica de domínio complexa com muitas regras de negócio versionadas em código, considere um Backend/Frontend App e use o Flow só para a parte de integração/orquestração.

Boas práticas dentro do Flow:

  • Sempre configure caminhos de erro (executionOnError) nos conectores críticos — um Flow sem tratamento de erro falha silenciosamente ou derruba a execução inteira por um problema pontual de um sistema externo.
  • Separe em módulos quando o Flow cresce — isole a lógica de negócio reutilizável da parte que é só gatilho/exposição (API, Scheduler), para poder reaproveitar a mesma lógica a partir de diferentes triggers sem duplicar conectores.
  • Use o FlowSpec (JSON) para revisar a configuração completa antes de publicar uma mudança importante, especialmente em fluxos com muitos conectores encadeados.
  • Depois do build, só configure uma Route em API Management se o Flow realmente precisa ser chamado de fora — Flows disparados por Scheduler ou Event Consumer normalmente não precisam de rota nenhuma.

4. Backend Apps vs. Frontend Apps​

  • Use Backend App para APIs e workers com lógica de domínio própria, versionada como código (não como configuração visual) — especialmente quando a lógica é complexa demais para caber confortavelmente em um Flow, ou quando o time já tem um serviço existente para importar via GitHub.
  • Use Frontend App para telas, dashboards e páginas — publicação é mais simples (build + deploy já gera um link público), sem precisar de Route em API Management.
  • Em ambos, um Dockerfile correto é obrigatório ao importar do GitHub — valide localmente que a imagem builda e sobe na porta configurada antes de importar, para não descobrir o problema só no build da plataforma. Ao criar via vibe code, a plataforma já resolve isso — prefira esse caminho quando não há necessidade de trazer um repositório já existente.
  • Backend App: se a stack for Java Quarkus, configure corretamente para ganhar o preview em Swagger de graça — é a forma mais rápida de validar contratos de API durante o desenvolvimento. Depois do deploy, lembre de configurar a Route em API Management se a API deve ser pública — esse passo é fácil de esquecer e é uma causa comum de "a API está deployada mas não responde de fora".
  • Frontend App: use o Preview (live preview) para validar a interface antes de cada build, e o AI Copilot para acelerar tarefas repetitivas (error handling, refactor, testes) diretamente na IDE do app.
  • Vincule Secrets/Config Maps por ambiente desde o início (ex: URL de API diferente em test e production) — evita hardcode de URL/configuração que só aparece como bug na hora de promover para produção.

5. Pense em Add-ons antes de construir a infraestrutura você mesmo​

Antes de subir um banco, um cache ou uma camada de autenticação manualmente dentro de um Backend/Frontend App, verifique se um Add-on já resolve:

  • Precisa de autenticação/SSO/OAuth2? Use o add-on FusionAuth em vez de implementar login do zero.
  • Precisa de um banco relacional? Use o add-on PostgreSQL — já vem com backups automáticos configuráveis, evitando ter que montar rotina de backup manualmente.
  • Precisa de cache, sessão ou pub/sub em memória? Use o add-on Cache (Valkey), escolhendo o Persistence Mode de acordo com a necessidade real (cache puro descartável vs. dado que precisa sobreviver a um restart).

Isso reduz tempo de setup, centraliza patch/manutenção da infraestrutura na plataforma, e mantém o Backend/Frontend App focado só na lógica da aplicação.

Quando usar Cloudflare ZTNA​

Use o add-on Cloudflare ZTNA quando precisar expor um Flow, App ou outro Add-on sem abrir portas no ambiente e sem depender de uma Route pública tradicional em API Management — por exemplo, para dar acesso a um painel administrativo interno, a um ambiente de homologação restrito a um grupo de usuários, ou a qualquer serviço que não deveria ficar exposto diretamente na internet. Prefira API Management quando o objetivo é uma API pública, com Consumers e rate limit; prefira ZTNA quando o objetivo é acesso controlado via Zero Trust, especialmente para interfaces administrativas ou ambientes não destinados ao público geral.

6. Use o MCP no seu fluxo de desenvolvimento​

Conecte seu assistente de IA (Claude Code, Claude, GitHub Copilot) via MCP desde o início de um projeto, não só quando um problema já aconteceu:

  • Peça para o assistente consultar Secrets e Config Maps vinculados a um Flow/App antes de investigar um bug de configuração — é mais rápido do que navegar manualmente pela plataforma.
  • Use o assistente para subir um Flow, fazer deploy de um app, ou inspecionar Routes/Consumers direto da conversa, mantendo o contexto de código e infraestrutura no mesmo lugar.
  • Aproveite a consulta de observabilidade (logs, métricas) pelo MCP para acelerar debugging sem trocar de tela a cada hipótese.
  • Lembre que nenhuma operação de exclusão é exposta pelo MCP — ele é seguro para diagnóstico e ações construtivas, mas remoção de recursos ainda precisa ser feita manualmente na plataforma.

7. Observabilidade e custo — hábito, não exceção​

  • Configure Monitoring e olhe Top Errored Executions regularmente, não só quando um usuário reclama — problemas costumam aparecer no monitoramento antes de virarem incidente.
  • Use o Trace para entender exatamente em qual etapa uma execução lenta ou com erro está gastando tempo, em vez de adivinhar pelo comportamento externo.
  • Acompanhe Usage por ambiente e por tipo de recurso — comparar Test com Production, e separar custo de infraestrutura do custo de tokens de IA, ajuda a identificar rapidamente se um recurso está superdimensionado ou se o gasto de IA está saudável.