🚀 Como criar um novo projeto Spring Boot

Para: Desenvolvedor Backend Júnior Iniciante


Objetivo: Criar o projeto Spring Boot + Kotlin do serviço de faturas

Tempo estimado: 2-3 horas

Nível de dificuldade: ⭐⭐ Iniciante-Intermediário

📋 Pré-requisitos

Antes de começar, verifique se você tem instalado:

• 
  Java 17 ou superior - Execute no terminal: java -version
  


• 
  IntelliJ IDEA (Community) - Download aqui
  


• 
  Git - Execute: git --version
  

🎯 Parte 1: Configurar Spring Initializr

O que é Spring Initializr?

É uma ferramenta web que gera automaticamente a estrutura inicial de um projeto Spring Boot. Pense nele como um "criador de projetos automático" que já configura tudo para você começar a programar rapidamente.

Passo a Passo

1.1 Acessar o Spring Initializr

1. Abra seu navegador


2. Acesse: https://start.spring.io/
   


3. Você verá uma página com vários campos de configuração

1.2 Configurar o Projeto

Preencha os campos EXATAMENTE como descrito abaixo:

1.3 Adicionar Dependências

Na seção Dependencies (lado direito), clique em "ADD DEPENDENCIES" e adicione:

1. 
   

   Spring Web

   
   
   
   
   
   • O que faz: Permite criar APIs REST (endpoints HTTP)
   
   
   • Por que precisa: Vamos criar endpoints para gerenciar faturas
   
   
   
   


2. 
   

   Spring DevTools

   
   
   
   
   
   • O que faz: Reinicia automaticamente a aplicação quando você salva o código
   
   
   • Por que precisa: Agiliza o desenvolvimento, você não precisa parar e iniciar manualmente
   
   
   
   


3. 
   

   Spring Boot Actuator (opcional, mas recomendado)

   
   
   
   
   
   • O que faz: Fornece endpoints de monitoramento (/health, /metrics)
   
   
   • Por que precisa: Útil para verificar se a aplicação está rodando
   
   
   
   

1.4 Gerar o Projeto

1. Clique no botão GENERATE (no final da página)


2. Um arquivo .zip será baixado automaticamente


3. Salve em uma pasta que você lembre (ex: ~/Documentos/projetos/)

1.5 Descompactar o Projeto

No Linux:

cd ~/Documentos/projetos/

unzip invoice-service.zip

cd invoice-service

Agora você tem a estrutura básica do projeto! 🎉

🏗️ Parte 2: Criar Estrutura de Pacotes

O que são pacotes?

Pacotes são pastas que organizam o código. É como organizar documentos em gavetas: cada tipo de arquivo vai em uma gaveta específica.

Passo a Passo

2.1 Importar no IntelliJ IDEA

1. Abra o IntelliJ IDEA
   


2. Clique em File → Open
   


3. Navegue até a pasta invoice-service e selecione-a


4. Clique em OK
   


5. Aguarde o IntelliJ baixar as dependências (veja a barra de progresso no canto inferior)

⏱️ Dica: Primeira vez pode demorar 5-10 minutos baixando bibliotecas. É normal!

2.2 Entender a Estrutura Atual

Depois de abrir, você verá algo assim:

invoice-service/

├── src/

│   ├── main/

│   │   ├── kotlin/

│   │   │   └── com/

│   │   │       └── invoice/

│   │   │           └── InvoiceServiceApplication.kt

│   │   └── resources/

│   │       └── application.properties

│   └── test/

├── build.gradle.kts

└── settings.gradle.kts

O que cada pasta significa:

• 
  src/main/kotlin/ - Onde fica seu código fonte


• 
  src/main/resources/ - Arquivos de configuração


• 
  src/test/ - Onde ficam os testes


• 
  build.gradle.kts - Configurações do projeto e dependências

2.3 Criar os Pacotes

Vamos criar 4 pacotes para organizar nosso código seguindo o padrão de "arquitetura em camadas":

1. No IntelliJ, navegue até: src/main/kotlin/com/invoice/
   


2. Clique com botão direito em invoice → New → Package
   


3. Digite: controller e pressione Enter


4. Repita os passos 2-3 para criar:
   
   
   
   
   • service
   
   
   • model
   
   
   • repository
   
   
   
   

Resultado final:

src/main/kotlin/com/invoice/

├── controller/      (endpoints da API)

├── service/         (lógica de negócio)

├── model/           (classes de dados)

├── repository/      (acesso a dados)

└── InvoiceServiceApplication.kt

Por que essa estrutura?

• 
  Controller: Recebe as requisições HTTP (ex: POST /invoices)


• 
  Service: Contém as regras de negócio (ex: calcular juros)


• 
  Model: Define estruturas de dados (ex: classe Invoice)


• 
  Repository: Conversa com banco de dados

Essa separação é chamada de Separation of Concerns - cada camada tem uma responsabilidade específica!

⚙️ Parte 3: Configurar application.yml

Por que configurar?

O arquivo de configuração define como sua aplicação se comporta: em que porta roda, nome da aplicação, configurações de banco, etc.

Passo a Passo

3.1 Converter .properties para .yml

O Spring Initializr cria um arquivo application.properties, mas vamos usar .yml que é mais organizado.

1. Localize: src/main/resources/application.properties
   


2. Clique com botão direito → Refactor → Rename
   


3. Renomeie para: application.yml
   

3.2 Adicionar Configurações Básicas

Abra o arquivo application.yml e adicione:

server:

  port: 8080



spring:

  application:

    name: invoice-service



logging:

  level:

    com.invoice: DEBUG

O que cada configuração faz:

• 
  server.port: 8080 - A aplicação rodará em http://localhost:8080
  


• 
  spring.application.name - Nome da aplicação (útil em logs)


• 
  logging.level - Mostra logs detalhados do seu código (útil para debug)

🚀 Parte 4: Executar a Aplicação

Momento da Verdade

Vamos subir a aplicação pela primeira vez. 😊

Passo a Passo

4.1 Executar pelo IntelliJ

1. Abra o arquivo InvoiceServiceApplication.kt
   


2. Você verá um código assim:
   

package com.invoice



import org.springframework.boot.autoconfigure.SpringBootApplication

import org.springframework.boot.runApplication



@SpringBootApplication

class InvoiceServiceApplication



fun main(args: Array<String>) {

    runApplication<InvoiceServiceApplication>(*args)

}

1. Clique no ícone ▶️ verde ao lado de fun main
   


2. Selecione Run 'InvoiceServiceApplication'
   

4.2 Verificar se Funcionou

Observe o console (painel inferior do IntelliJ). Você deve ver:

  .   ____          _            __ _ _

 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \

( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \

 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )

  '  |____| .__|_| |_|_| |_\__, | / / / /

 =========|_|==============|___/=/_/_/_/

 :: Spring Boot ::                (v3.2.x)



...

Started InvoiceServiceApplication in 2.345 seconds

✅ Se você viu isso, PARABÉNS! Sua aplicação está rodando! 🎉

4.3 Testar no Navegador

1. Abra seu navegador


2. Acesse: http://localhost:8080
   


3. Você verá uma página de erro "Whitelabel Error Page"

Isso está CORRETO! 😎

A página de erro aparece porque ainda não criamos nenhum endpoint. O importante é que a aplicação está respondendo!

✅ Critérios de Aceite - Checklist Final

Marque cada item que você completou:

Configurar Spring Initializr

• [ ] Projeto gerado com Java 17+


• [ ] Linguagem: Kotlin


• [ ] Dependências: Spring Web e Spring DevTools


• [ ] Projeto baixado e descompactado

Criar Estrutura de Pacotes

• [ ] Projeto importado no IntelliJ


• [ ] Pacote controller criado


• [ ] Pacote service criado


• [ ] Pacote model criado


• [ ] Pacote repository criado

Configurar application.yml

• [ ] Arquivo .properties renomeado para .yml
  


• [ ] Porta configurada: 8080


• [ ] Nome da aplicação definido


• [ ] Nível de log configurado

Executar Aplicação

• [ ] Aplicação compila sem erros


• [ ] Console mostra "Started InvoiceServiceApplication"


• [ ] http://localhost:8080 retorna página de erro do Spring (esperado!)

🐛 Problemas Comuns e Soluções

Erro: "Java version mismatch"

Causa: Versão errada do Java configurada


Solução:

1. No IntelliJ: File → Project Structure → Project
   


2. Configure SDK para Java 17


3. Em Language Level, selecione 17 - Sealed types, always-strict floating-point...
   

Erro: "Port 8080 already in use"

Causa: Outra aplicação já está usando a porta 8080


Solução:

1. No terminal: lsof -i :8080 (veja qual processo está usando)


2. Mate o processo ou mude a porta no application.yml para 8081
   

Dependências não baixam

Causa: Problema de rede ou cache do Gradle


Solução:

1. No terminal, dentro da pasta do projeto:
   

./gradlew clean build --refresh-dependencies

IntelliJ não reconhece código Kotlin

Causa: Plugin Kotlin não instalado


Solução:

1. File → Settings → Plugins


2. Procure por "Kotlin"


3. Clique em Install
   


4. Reinicie o IntelliJ

🎓 Conceitos Importantes para Entender

O que é Spring Boot?

É um framework (conjunto de ferramentas) que facilita criar aplicações Java/Kotlin. Ele já vem com muita coisa pronta, então você foca na lógica do seu negócio.

Analogia: É como comprar um carro pronto ao invés de construir cada peça do zero.

O que é API REST?

É uma forma de aplicações conversarem entre si usando HTTP (mesmo protocolo do navegador). Você cria "endpoints" (URLs) que recebem e envolvam dados.

Exemplo:

• 
  POST /invoices - Cria uma nova fatura


• 
  GET /invoices/123 - Busca a fatura de ID 123

O que é Gradle?

É uma ferramenta que:

1. Baixa bibliotecas (dependências) que seu projeto precisa


2. Compila seu código


3. Empacota tudo em um arquivo .jar executável

Analogia: É como um assistente que busca todas as ferramentas que você precisa e organiza tudo.

💡 Dicas

Não copie e cole código sem entender!


Leia cada linha, tente compreender. Se não entender algo, pergunte!

Erros são normais


Você vai ver MUITAS mensagens de erro. Aprenda a lê-las com calma. Geralmente a última linha diz o problema.

Documente suas dúvidas


Anote o que não entendeu para perguntar depois. Isso mostra proatividade!

Commits frequentes


Quando algo funcionar, salve no Git. É como criar pontos de restore de um jogo.

🎉 Parabéns

Se você chegou até aqui e sua aplicação está rodando, você acabou de:

✅ Criar seu primeiro projeto Spring Boot


✅ Entender estrutura de pacotes


✅ Configurar uma aplicação


✅ Executar um servidor web

Isso é MUITA coisa para um dia de trabalho! 🚀

Lembre-se: Todo desenvolvedor sênior já esteve no seu lugar. A diferença é que eles persistiram e continuaram aprendendo. Você está no caminho certo! 💪