exemplo

Escopo, pré-requisitos e objetivo

Projeto que serve de referência para o desenvolvimento de software em Java.

É um projeto proposto para ser clonado e reutilizado, faz uso de Spring Boot 3, JDK 17 (exigido) e Maven 3.8.6.

Há um conjunto relativamente extenso de ferramentas para avaliação do código do projeto, o que é um bom ponto de partida para implementação de DevOps.

Para ilustrar o projeto inclui: (a) uma biblioteca formada por um único método que identifica o dia da semana para uma data fornecida; (b) uma aplicação que oferece tal funcionalidade via linha de comandos e (c) uma RESTFul API ambas para acesso à funcionalidade da biblioteca.

Objetivo: ilustrar uma organização de código em Java usando "boas práticas" para inspirar projetos reais.

Iniciando...

• git clone https://github.com/kyriosdata/exemplo
• cd exemplo

Agora você poderá executar os vários comandos abaixo.

Pré-requisitos

• mvn --version você deverá ver a indicação da versão do Maven instalada e a versão do JDK, dentre outras. Observe que o JDK é obrigatório, assim como a definição das variáveis de ambiente JAVA_HOME e M2_HOME.

Limpar, compilar, executar testes de unidade e cobertura

• mvn clean remove diretório target

• mvn compile compila o projeto, deposita resultados no diretório target

• mvn test executa todos os testes do projeto. Para executar apenas parte dos testes, por exemplo, aqueles contidos em uma dada classe execute mvn -Dtest=NomeDaClasseTest test. Observe que o sufixo do nome da classe de teste é Test (padrão recomendado). Para executar um único teste mvn -Dtest=NomeDaClasseTest#nomeDoMetodo test.

• mvn verify -P cobertura executa testes de unidade e produz relatório de cobertura em target/site/jacoco/index.html além de verificar se limite mínimo de cobertura, conforme configurado, é satisfeito.

Produzindo código executável (depende da JVM)

• mvn package gera arquivo exemplo.jar no diretório target. Observe que o arquivo gerado não é executável. Um arquivo jar é um arquivo no formato zip. Você pode verificar o conteúde deste arquivo ao executar o comando jar vft exemplo.jar.

• mvn package -P executavel-dir gera exemplo-dir.jar, executável, mas dependente do diretório jars, também criado no diretório target. Para executar basta o comando java -jar target/exemplo-dir.jar. Observe que se o diretório jars for removido, então este comando falha. Por último, o diretório jars deve ser depositado no mesmo diretório do arquivo exemplo.jar. A execução deste arquivo refere-se à aplicação via linha de comandos.

• mvn package -P executavel-unico gera jar executável correspondente ao aplicativo a ser executado via linha de comandos, em um único arquivo, target/exemplo-unico.jar, suficiente para ser transferido e executado. Para executá-lo basta o comando java -jar target/exemplo-unico.jar.

• mvn package -P api gera jar executável juntamente com todas as dependências reunidas em um único arquivo, target/api.jar. Este arquivo jar pode ser transferido para outro diretório ou máquina e ser executado pelo comando java -jar target/api.jar.

A execução e exemplos de chamadas são fornecidos na seção seguinte.

Executando a aplicação e a RESTFul API

• mvn exec:java -Dexec.mainClass="nome.completo.Classe" -Dexec.args="arg1 arg2" executa o método main da classe indicada na configuração do plugin pertinente no arquivo pom.xml. Depende de mvn compile.

• java -jar target/exemplo-unico.jar executa o aplicativo por meio do arquivo jar criado pelo comando mvn package -P executavel-unico, conforme comentado anteriormente. Observe que o comando anterior e o corrente produzem o mesmo efeito, contudo, o arquivo jar permite que seja enviado para um outro diretório ou outro computador, onde pode ser executado, enquanto o comando anterior (acima) exige, inclusive, a disponibilidade do Maven (o que pode ser útil em tempo de desenvolvimento).

• java -jar target/api.jar ou ainda mvn spring-boot:run coloca em execução a API gerada por mvn package -P api na porta padrão (8080). Para fazer uso de porta diferente use java -jar -Dserver.port=9876 target/api.jar, por exemplo. Requisições podem ser submetidas conforme abaixo:

  • Abra o endereço http://localhost:8080/ds no seu navegador, ou forneça a seguinte URL para um dia específico http://localhost:8080/ds?data=01-01-2015.
  • Via linha de comandos (curl), curl http://localhost:8080/ds ou curl http://localhost:8080/ds?data=01-01-200.
  • Página HTML (há uma interface gráfica) no diretório gui, basta abrir o arquivo index.html.

Produzindo código executável (native image) (em testes)

• Depende de GraalVM.
• JDK 17
• Visual Studio (Windows)
• mvn -P native native:compile

Documentação

• mvn javadoc:javadoc produz documentação do projeto depositada em target/site/apidocs/index.html. Este comando está configurado para o JDK 9.

• mvn jxr:jxr Produz documentação do código fonte depositada em target/site/xref/index.html.

Análise estática

Trata-se da análise do código sem que seja executado. Esta análise produz uma "noção de quão bom" está o código sob alguns aspecto e, em consequência, permite orientar eventuais ações de melhoria. Fique atento, "sair bem" na análise estática não significa que "agrada usuários". A análise estática observa o código.

Todas estas análises devem ser realizadas em todos os projetos? Não! Aquelas relevantes para um dado projeto deverão ser configuradas em conformidade com o contexto em questão.

• Checkstyle

  • mvn checkstyle:checkstyle gera análise de estilo em target/site/checkstyle.html. Observe que o uso do plugin jxr é necessário para geração de relatório do código fonte referenciável pelo relatório gerado pelo Checkstyle. Contudo, o uso do jxr não é obrigatório.

  • mvn checkstyle:check faz com que o build falhe se pelo menos um estilo é violado

• Dependency Check (vulnerabilidades)

  • mvn verify -P owasp análise de vulnerabilidades depositadas em target/dependency-check-report.html. A primeira execução é relativamente "longa", esteja preparado para esperar...

• JavaNCSS

  • mvn javancss:check verifica limites de complexidade ciclomática (CC) e de linhas de código sem comentário (NCSS). Este comando depende da compilação prévia, ou seja mvn compile

  • mvn javancss:report gera relatório em target/site/javancss.html e também depende de compilação prévia, ou seja, mvn compile

• JDepend

  • mvn jdepend:generate gera relatório de algumas métricas, inclusive presença de ciclos em target/site/jdepend-report.html

• PMD

  • mvn jxr:jxr pmd:pmd gera relatório em target/site/pmd.html. Observe que o uso do plugin jxr é necessário para geração de relatório do código fonte referenciável pelo relatório perado pelo PMD. Contudo, o uso do jxr não é obrigatório.

  • mvn pmd:check falha se pelo menos uma regra é violada

  • mvn jxr:jxr pmd:cpd gera relatório de duplicidades encontradas. Observe que o uso do plugin jxr é necessário para geração de relatório do código fonte referenciável pelo relatório gerado pelo PMD. Contudo, o uso do jxr não é obrigatório. O resultado é depositado no arquivo target/site/cpd.html.

• Spotbugs

  • mvn spotbugs:spotbugs detecção de bugs. Resultado em target/spotbugs.html.
  • apenas verifica se há erros

Relatório do projeto

• mvn package site -P cobertura Gera documentação do projeto, incluindo relatórios de análises estáticas em target/site/index.html.

• mvn site:run executa serviço que disponibiliza em http://localhost:8080 a documentação gerada no passo anterior.

Disponibilizando biblioteca no repositório Maven Central

A boa notícia é que este pom.xml está devidamente configurado para publicação no Maven Central, contudo, depende de outras ações e da configuração do arquivo HOMEDIR/.m2/settings.xml.

• Nexus Staging Maven Plugin
  • mvn deploy -P deploy

A publicação usando o Maven Central é mais complexa do que a alternativa recente oferecida pelo JitPack, ou até mesmo pelo Github Packages, por exemplo.

Dependências

O desenvolvimento de código em Java, em geral, usufrui de um significativo conjunto de bibliotecas e frameworks. Esta reutilização é incorporada em um projeto por meio de dependências. Gerenciá-las torna-se necessário e há dois plugins úteis para tal. Consulte a documentação deles para outros além daqueles ilustrados abaixo: Version Maven Plugin (aqui) e Apache Maven Dependency Plugin (aqui).

• mvn versions:display-dependency-updates Lista dependências para as quais há versões mais recentes do que aquelas empregadas.

• mvn versions:display-plugin-updates Lista plugins para as quais há versões mais recentes do que aquelas empregadas.

• mvn dependency:analyze Analisar as dependências de um projeto. Dependência citada mas não utilizada, dentre outras situações são relatadas por meio desta análise.

• mvn dependency:purge-local-repository limpa dependências do projeto em questão do repositório local e obtém dependências novamente. Útil quando o repositório local é corrompido.

• mvn dependency:copy-dependencies Copia dependências do projeto para o diretório target/dependency.

Banco de Dados H2

Nos cenários onde é feito uso de um banco relacional, aqui são oferecidos recursos para desenvolvimento usando o H2 (https://www.h2database.com).

• mvn exec:java -P start-shell-h2 Abre/cria banco para uso via linha de comandos. Para criar o banco de nome bancoNome no diretório dir forneça jdbc:h2:<dir>/bancoNome. Se existir, apenas será aberto. Adicionalmente, forneça como driver a classe org.h2.Driver. Você pode fazer uso do diretório de sua preferência, contudo, a sugestão é criar o banco no diretório target (usado pelo comando seguinte). Na shell que é aberta, digite `create table teste (i