Melhores Práticas do Helidon

Seu objetivo é me ajudar a escrever aplicações Helidon de alta qualidade, seguindo as melhores práticas estabelecidas.

Mudanças de API do Helidon 3 → 4

O Helidon 4 renomeou ou resignou APIs que aparecem amplamente em sua forma do Helidon 3. A coluna da esquerda não compila no Helidon 4. Verifique o código gerado com esta tabela antes de retorná-lo.

Value.as(Class) no Helidon 4 retorna OptionalValue<T>, não T. Este é o erro de compilação mais comum do Helidon 4 em código gerado.

Configuração e Estrutura do Projeto

• Modelo de Programação: Determine se o projeto usa Helidon SE ou Helidon MP antes de gerar o código. Não misture os dois modelos de programação, a menos que seja explicitamente necessário.
• Versão do Java: Use Java 21 ou posterior para aplicações Helidon 4.
• Ferramenta de Build: Use Maven (pom.xml) ou Gradle (build.gradle) para gerenciamento de dependências.
• Gerenciamento de Dependências: Use o BOM ou plataforma Helidon para manter as versões dos módulos Helidon alinhadas.
• Estrutura de Pacotes: Organize o código por funcionalidade ou domínio, como com.example.app.order e com.example.app.customer, em vez de apenas por camada técnica.

Helidon SE

• Composição Explícita: Construa serviços e dependências explicitamente na camada de bootstrap da aplicação.
• Injeção de Construtor: Passe as dependências necessárias através de construtores e declare os campos de dependência como private final.
• Serviços HTTP: Agrupe rotas relacionadas em implementações focadas de HttpService.
• Lógica de Negócios: Mantenha a lógica de negócios fora dos manipuladores de rota.
• Threads Virtuais: Prefira código bloqueante direto com o tratamento de requisições baseado em threads virtuais do Helidon 4. Não introduza complexidade reativa sem um motivo claro. O Helidon 4 não é reativo; não gere cadeias de Single, Multi ou CompletionStage.

Helidon MP

• Jakarta e MicroProfile: Prefira APIs padrão do Jakarta EE e Eclipse MicroProfile quando disponíveis.
• Injeção de Dependência: Use CDI com injeção de construtor para dependências necessárias.
• Escopos de Bean: Use escopos CDI como @ApplicationScoped e @RequestScoped intencionalmente.
• Beans de Escopo Normal: Adicione um construtor não privado e sem argumentos a beans de escopo normal que usam injeção de construtor, para que o proxy cliente CDI possa ser criado de forma portátil.
• Lógica de Negócios: Mantenha as classes de recurso Jakarta REST enxutas e delegue operações de negócios para classes de serviço.
• Portabilidade: Prefira APIs Jakarta e MicroProfile portáteis em vez de APIs específicas do Helidon quando a portabilidade for importante.

Configuração

• Configuração Externalizada: Armazene configurações não secretas em application.yaml ou application.properties.
• Configuração Helidon SE: Use Helidon Config e passe valores de configuração ou objetos de configuração tipados para os componentes.
• Configuração Helidon MP: Use MicroProfile Config para configurações de aplicação injetadas.
• Substituições de Ambiente: Use variáveis de ambiente ou fontes de configuração específicas de implantação para valores dependentes do ambiente.
• Gerenciamento de Segredos: Nunca codifique credenciais, chaves de API, tokens ou certificados privados.

Camada Web

…