Thiago Matos

Posted on Dec 29

🚀 Como criar um novo projeto Spring Boot

#java #kotlin #springboot #tutorial

Para: Desenvolvedor 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

Opcional: Instalar Gradle Localmente

O projeto Spring Boot vem com Gradle Wrapper (arquivos gradlew e gradlew.bat) que baixa automaticamente a versão correta do Gradle. Porém, em alguns ambientes corporativos, é preferível usar uma instalação local do Gradle.

Para instalar Gradle no Linux:

# Usando SDKMAN (recomendado)
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install gradle 8.5

# Verificar instalação
gradle --version

Para instalar no macOS:

brew install gradle

💡 Quando usar Gradle local vs Wrapper?

Wrapper (padrão): Garante que todos usem a mesma versão, recomendado para iniciantes

Gradle local: Útil em ambientes corporativos com restrições de rede ou quando você trabalha em múltiplos projetos

⚙️ Configurar IntelliJ IDEA (Importante!)

Antes de importar o projeto, vamos configurar corretamente o IntelliJ para evitar problemas.

Configuração 1: Verificar/Configurar JDK

O IntelliJ precisa saber qual versão do Java usar.

Passo a Passo

Abra o IntelliJ IDEA
Antes de abrir qualquer projeto, vá em:
- File → Project Structure (ou pressione Ctrl+Alt+Shift+S no Linux/Windows, ⌘+; no Mac)
Na janela que abrir, clique em Project (lado esquerdo)
Configure:

Campo	Valor
SDK	Java 17 (ou superior)
Language Level	SDK default

Se não aparecer Java 17 na lista:
- Clique no dropdown do SDK
- Selecione Add SDK → Download JDK...
- Escolha:
  - Vendor: Amazon Corretto, Eclipse Temurin ou Oracle OpenJDK
  - Version: 17
- Clique em Download
Clique em OK para salvar

Verificação:

# No terminal, verifique qual Java está configurado
java -version

# Deve mostrar algo como:
# openjdk version "17.0.x"

Configuração 2: Escolher entre Gradle Wrapper ou Gradle Local

Você pode escolher usar o Gradle que vem com o projeto (wrapper) ou uma instalação local.

Opção A: Usar Gradle Wrapper (Recomendado para Iniciantes)

Esta é a configuração padrão. O IntelliJ usa os arquivos gradlew e gradlew.bat do projeto.

No IntelliJ:

File → Settings (ou Ctrl+Alt+S)
Navegue até: Build, Execution, Deployment → Build Tools → Gradle
Configure:

Campo	Valor
Use Gradle from	`'wrapper' task in Gradle build script`
Gradle JVM	Project SDK (Java 17)
Build and run using	Gradle (Recomendado)
Run tests using	Gradle (Recomendado)

Vantagens:

✅ Garante que todos da equipe usam a mesma versão do Gradle
✅ Não precisa instalar nada manualmente
✅ Versão especificada no arquivo gradle/wrapper/gradle-wrapper.properties

Desvantagens:

❌ Precisa baixar o Gradle na primeira vez (pode demorar)
❌ Pode ter problemas se houver firewall/proxy bloqueando o download

Opção B: Usar Gradle Instalado Localmente

Se sua empresa tem restrições ou você já tem Gradle instalado.

No IntelliJ:

File → Settings (ou Ctrl+Alt+S)
Navegue até: Build, Execution, Deployment → Build Tools → Gradle
Configure:

Campo	Valor
Use Gradle from	`Specified location`
Gradle home	Caminho da instalação (ex: `/usr/local/gradle-8.5` ou `/home/usuario/.sdkman/candidates/gradle/8.5`)
Gradle JVM	Project SDK (Java 17)

Para descobrir o caminho do Gradle:

which gradle
# Mostra algo como: /usr/local/bin/gradle

# Para ver o diretório home do Gradle:
gradle --version
# Mostra Gradle home: /usr/local/gradle-8.5

No macOS (Homebrew):

# O caminho geralmente é:
/usr/local/Cellar/gradle/8.5/libexec

Com SDKMAN:

# O caminho geralmente é:
~/.sdkman/candidates/gradle/current

Vantagens:

✅ Mais rápido (não precisa baixar)
✅ Funciona offline
✅ Útil quando você trabalha em vários projetos

Desvantagens:

❌ Precisa manter o Gradle atualizado manualmente
❌ Pode ter incompatibilidade se a versão local for diferente da esperada pelo projeto

Configuração 3: Configurar Gradle JVM Corretamente

IMPORTANTE: O Gradle precisa rodar usando a JVM correta!

No IntelliJ → Settings → Build Tools → Gradle:

Gradle JVM: Selecione o Java 17 que você configurou anteriormente
- Opção comum: Project SDK (java version "17")...
- Evite: Usar JVMs antigas (Java 8, Java 11) ou muito novas se o projeto especifica Java 17

Se o Gradle JVM não aparecer:

Clique no dropdown Gradle JVM
Selecione Add JDK...
Navegue até a pasta onde o Java 17 está instalado:
- Linux (SDKMAN): ~/.sdkman/candidates/java/17.x.x-tem
- Linux (apt): /usr/lib/jvm/java-17-openjdk-amd64
- macOS (Homebrew): /usr/local/Cellar/openjdk@17/17.x.x
- Windows: C:\Program Files\Java\jdk-17

Verificar Configurações

Depois de configurar, verifique se está tudo certo:

Abra o Terminal do IntelliJ (aba na parte inferior)
Execute:

# Se usar Gradle Wrapper:
./gradlew --version

# Se usar Gradle local:
gradle --version

Resultado esperado:

------------------------------------------------------------
Gradle 8.5
------------------------------------------------------------

Build time:   2023-11-15 13:36:12 UTC
Revision:     1234567890

Kotlin:       1.9.10
Groovy:       3.0.17
Ant:          Apache Ant(TM) version 1.10.13
JVM:          17.0.9 (Amazon.com Inc. 17.0.9+8-LTS)
OS:           Linux 5.15.0-91-generic amd64

✅ Ótimo! O campo JVM: deve mostrar Java 17 (ou superior).

🎯 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

Abra seu navegador
Acesse: https://start.spring.io/
Você verá uma página com vários campos de configuração

1.2 Configurar o Projeto

Preencha os campos EXATAMENTE como descrito abaixo:

Campo	Valor	Por que?
Project	Gradle - Kotlin	Ferramenta para gerenciar dependências
Language	Kotlin	A linguagem que vamos usar
Spring Boot	3.2.x (mais recente)	Versão do framework
Group	`com.invoice`	Identificador da sua empresa/projeto
Artifact	`invoice-service`	Nome do seu projeto
Name	`invoice-service`	Nome da aplicação
Description	`Invoice Processing Service`	Descrição curta
Package name	`com.invoice`	Deixe o padrão
Packaging	Jar	Formato do pacote final
Java	17	Versão do Java

1.3 Adicionar Dependências

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

Spring Web
- O que faz: Permite criar APIs REST (endpoints HTTP)
- Por que precisa: Vamos criar endpoints para gerenciar faturas
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
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

Clique no botão GENERATE (no final da página)
Um arquivo .zip será baixado automaticamente
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

Abra o IntelliJ IDEA
Clique em File → Open
Navegue até a pasta invoice-service e selecione-a
Clique em OK
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":

No IntelliJ, navegue até: src/main/kotlin/com/invoice/
Clique com botão direito em invoice → New → Package
Digite: controller e pressione Enter
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 Repositórios Privados (Artifactory)

Por que usar repositórios privados?

Em ambientes corporativos, muitas empresas usam repositórios privados (como Artifactory ou Nexus) para:

Armazenar bibliotecas internas - Código compartilhado entre equipes
Cache de dependências - Mais rápido que baixar direto da internet
Segurança - Controlar quais bibliotecas podem ser usadas
Trabalhar offline - Dependências já estão no repositório da empresa

Analogia: É como ter uma biblioteca da empresa ao invés de sempre ir à biblioteca pública.

Passo a Passo

3.1 Criar arquivo gradle.properties

Este arquivo guarda configurações globais do Gradle, incluindo URLs de repositórios.

Na raiz do projeto, crie o arquivo gradle.properties
Adicione as seguintes configurações:

# URL base do Artifactory da empresa
artifactoryUrl=https://artifactory.suaempresa.com/artifactory

# Repositórios específicos
artifactoryReleaseRepo=libs-release
artifactorySnapshotRepo=libs-snapshot
artifactoryPluginRepo=plugins-release

# Credenciais (NÃO commitar em produção!)
# Em produção, use variáveis de ambiente
artifactoryUser=seu.usuario
artifactoryPassword=sua.senha

⚠️ IMPORTANTE: Nunca commite senhas reais no Git! Em produção, use variáveis de ambiente ou ferramentas como Vault.

Explicação de cada propriedade:

artifactoryUrl - URL base do servidor Artifactory da empresa
artifactoryReleaseRepo - Nome do repositório de versões estáveis
artifactorySnapshotRepo - Nome do repositório de versões em desenvolvimento
artifactoryPluginRepo - Nome do repositório de plugins Gradle
artifactoryUser / artifactoryPassword - Suas credenciais de acesso

3.2 Usar Variáveis de Ambiente (Recomendado para Produção)

Para não expor senhas, use variáveis de ambiente:

No Linux/Mac, adicione no ~/.bashrc ou ~/.zshrc:

export ARTIFACTORY_USER="seu.usuario"
export ARTIFACTORY_PASSWORD="sua.senha"

No gradle.properties:

artifactoryUrl=https://artifactory.suaempresa.com/artifactory
artifactoryReleaseRepo=libs-release
artifactorySnapshotRepo=libs-snapshot
artifactoryPluginRepo=plugins-release

# Credenciais virão de variáveis de ambiente
artifactoryUser=${ARTIFACTORY_USER}
artifactoryPassword=${ARTIFACTORY_PASSWORD}

3.3 Configurar settings.gradle.kts

O arquivo settings.gradle.kts controla de onde o Gradle baixa plugins.

Abra o arquivo settings.gradle.kts e substitua o conteúdo por:

pluginManagement {
    repositories {
        // 1. MavenLocal - cache local da sua máquina
        mavenLocal()

        // 2. Artifactory privado - repositório da empresa
        maven {
            url = uri("${settings.extra["artifactoryUrl"]}/${settings.extra["artifactoryPluginRepo"]}")
            credentials {
                username = settings.extra["artifactoryUser"] as String?
                password = settings.extra["artifactoryPassword"] as String?
            }
        }

        // 3. Gradle Plugin Portal - repositório público oficial
        gradlePluginPortal()

        // 4. Maven Central - repositório público (fallback)
        mavenCentral()
    }
}

rootProject.name = "invoice-service"

Explicação linha por linha:

pluginManagement { } - Seção que configura onde buscar plugins do Gradle
mavenLocal() - Primeiro procura no cache local (~/.m2/repository)
maven { url = ... } - Configura repositório privado (Artifactory)
- ${settings.extra["artifactoryUrl"]} - Lê a URL do gradle.properties
- credentials { } - Adiciona usuário e senha para autenticação
gradlePluginPortal() - Repositório oficial de plugins do Gradle
mavenCentral() - Repositório público (caso não encontre nos anteriores)

Ordem de busca: mavenLocal → Artifactory → Gradle Plugin Portal → Maven Central

3.4 Configurar build.gradle.kts

O arquivo build.gradle.kts controla de onde o Gradle baixa dependências da aplicação.

Abra o arquivo build.gradle.kts e localize a seção repositories. Substitua por:

repositories {
    // 1. MavenLocal - cache local
    mavenLocal()

    // 2. Artifactory - releases (bibliotecas estáveis)
    maven {
        url = uri("${project.findProperty("artifactoryUrl")}/${project.findProperty("artifactoryReleaseRepo")}")
        credentials {
            username = project.findProperty("artifactoryUser") as String?
            password = project.findProperty("artifactoryPassword") as String?
        }
    }

    // 3. Artifactory - snapshots (bibliotecas em desenvolvimento)
    maven {
        url = uri("${project.findProperty("artifactoryUrl")}/${project.findProperty("artifactorySnapshotRepo")}")
        credentials {
            username = project.findProperty("artifactoryUser") as String?
            password = project.findProperty("artifactoryPassword") as String?
        }
    }

    // 4. Maven Central - repositório público (fallback)
    mavenCentral()
}

Explicação:

mavenLocal() - Busca primeiro no cache local
Primeiro maven { } - Repositório de releases (versões 1.0.0, 2.3.1, etc.)
Segundo maven { } - Repositório de snapshots (versões 1.0.0-SNAPSHOT)
mavenCentral() - Repositório público como fallback

Diferença entre Release e Snapshot:

Release	Snapshot
Versão estável (1.0.0)	Versão em desenvolvimento (1.0.0-SNAPSHOT)
Não muda depois de publicada	Pode ser atualizada a qualquer momento
Para produção	Para testes internos

Conceitos Importantes

MavenLocal: Um cache local de dependências no seu computador. O Gradle verifica aqui primeiro para evitar downloads repetidos.
Artifactory (ou Nexus): Repositórios privados usados por empresas para gerenciar suas próprias bibliotecas e fazer cache de dependências públicas.
Gradle Plugin Portal: O repositório oficial para plugins do Gradle.
Maven Central: O maior repositório público de bibliotecas Java/Kotlin. É o "fallback" caso a dependência não seja encontrada nos repositórios anteriores.
settings.gradle.kts vs build.gradle.kts:
- settings.gradle.kts: Configura de onde o Gradle baixa plugins.
- build.gradle.kts: Configura de onde o Gradle baixa dependências da aplicação.
--refresh-dependencies: Um comando Gradle que força o download de todas as dependências novamente, ignorando o cache local. Útil para garantir que você está usando as versões mais recentes.

3.5 Exemplo Completo do build.gradle.kts

Aqui está como deve ficar o arquivo completo:

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
    id("org.springframework.boot") version "3.2.0"
    id("io.spring.dependency-management") version "1.1.4"
    kotlin("jvm") version "1.9.20"
    kotlin("plugin.spring") version "1.9.20"
}

group = "com.invoice"
version = "0.0.1-SNAPSHOT"

java {
    sourceCompatibility = JavaVersion.VERSION_17
}

repositories {
    // 1. MavenLocal
    mavenLocal()

    // 2. Artifactory - releases
    maven {
        url = uri("${project.findProperty("artifactoryUrl")}/${project.findProperty("artifactoryReleaseRepo")}")
        credentials {
            username = project.findProperty("artifactoryUser") as String?
            password = project.findProperty("artifactoryPassword") as String?
        }
    }

    // 3. Artifactory - snapshots
    maven {
        url = uri("${project.findProperty("artifactoryUrl")}/${project.findProperty("artifactorySnapshotRepo")}")
        credentials {
            username = project.findProperty("artifactoryUser") as String?
            password = project.findProperty("artifactoryPassword") as String?
        }
    }

    // 4. Maven Central
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    developmentOnly("org.springframework.boot:spring-boot-devtools")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

tasks.withType<KotlinCompile> {
    kotlinOptions {
        freeCompilerArgs += "-Xjsr305=strict"
        jvmTarget = "17"
    }
}

tasks.withType<Test> {
    useJUnitPlatform()
}

3.6 Testar a Configuração

Agora vamos verificar se está tudo funcionando!

No terminal, execute:

./gradlew clean build --refresh-dependencies

O que esse comando faz:

clean - Remove arquivos compilados antigos
build - Compila o projeto
--refresh-dependencies - Força o download das dependências novamente

Resultado esperado:

BUILD SUCCESSFUL in 45s

Se aparecer erros, veja a seção de troubleshooting mais abaixo.

3.7 Verificar de Onde as Dependências Foram Baixadas

Para ver de qual repositório cada dependência veio:

./gradlew dependencies --configuration runtimeClasspath

Você verá algo assim:

com.fasterxml.jackson.module:jackson-module-kotlin:2.15.3
   -> Downloaded from: https://artifactory.suaempresa.com/artifactory/libs-release/...

⚙️ Parte 4: 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.

Localize: src/main/resources/application.properties
Clique com botão direito → Refactor → Rename
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 5: Executar a Aplicação

Momento da Verdade

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

Passo a Passo

4.1 Executar pelo IntelliJ

Abra o arquivo InvoiceServiceApplication.kt
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)
}

Clique no ícone ▶️ verde ao lado de fun main
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

Abra seu navegador
Acesse: http://localhost:8080
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 IntelliJ IDEA

[ ] IntelliJ IDEA instalado
[ ] JDK 17 configurado no IntelliJ (Project Structure → SDK)
[ ] Gradle configurado (Wrapper ou Local)
[ ] Gradle JVM configurado para usar Java 17
[ ] Comando ./gradlew --version ou gradle --version executado com sucesso

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 Repositórios Privados (Artifactory)

[ ] Arquivo gradle.properties criado na raiz do projeto
[ ] URL do Artifactory configurada
[ ] Credenciais configuradas (ou variáveis de ambiente)
[ ] settings.gradle.kts atualizado com repositórios de plugins
[ ] build.gradle.kts atualizado com repositórios de dependências
[ ] Comando ./gradlew clean build executado com sucesso

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:

No IntelliJ: File → Project Structure → Project
Configure SDK para Java 17
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:

No terminal: lsof -i :8080 (veja qual processo está usando)
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:

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:

File → Settings → Plugins
Procure por "Kotlin"
Clique em Install
Reinicie o IntelliJ

Erro: "Unsupported class file major version XX"

Causa: Versão do Java incompatível (código compilado com Java mais novo que o configurado)

Solução:

Verifique qual Java o projeto precisa: abra build.gradle.kts e procure sourceCompatibility
No IntelliJ: File → Project Structure → Project
Configure SDK para a versão correta (Java 17+)
No IntelliJ: File → Settings → Build Tools → Gradle
Configure Gradle JVM para a mesma versão
Execute: ./gradlew clean build

Erro: "Could not determine Java version"

Causa: Gradle JVM não configurado ou apontando para local inválido

Solução:

File → Settings → Build Tools → Gradle
Em Gradle JVM, selecione um JDK válido (Java 17+)
Se não aparecer nenhum JDK:
- Clique em Add JDK...
- Navegue até a pasta de instalação do Java
- No Linux: /usr/lib/jvm/java-17-openjdk-amd64
Clique em Apply e depois OK

Erro: "Gradle version X.X is required. Current version is Y.Y"

Causa: Versão do Gradle instalada não é compatível com o projeto

Solução:

Se usando Gradle Local:

Instale a versão correta: sdk install gradle 8.5 (usando SDKMAN)
Atualize o caminho no IntelliJ: Settings → Gradle → Gradle home

Se usando Wrapper (recomendado):

Settings → Gradle → Use Gradle from
Selecione: 'wrapper' task in Gradle build script
O wrapper baixará automaticamente a versão correta

Erro: "Could not resolve all dependencies" (Artifactory)

Causa: Credenciais incorretas ou URL do Artifactory errada

Solução:

Verifique se a URL no gradle.properties está correta
Teste acessar a URL no navegador: https://artifactory.suaempresa.com/artifactory
Confirme usuário e senha
Se usar variáveis de ambiente, execute: echo $ARTIFACTORY_USER para verificar

Erro: "HTTP 401 Unauthorized" (Artifactory)

Causa: Senha expirada ou usuário sem permissão

Solução:

Verificar suas permissões no Artifactory
Tente resetar sua senha no portal do Artifactory
Verifique se não há espaços extras no gradle.properties

Erro: "UnknownHostException" (Artifactory)

Causa: Você está fora da rede da empresa ou VPN desconectada

Solução:

Conecte-se à VPN da empresa
Verifique conexão: ping artifactory.suaempresa.com
Se estiver offline, comente temporariamente os repositórios privados e use só mavenCentral()

🎓 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:

Baixa bibliotecas (dependências) que seu projeto precisa
Compila seu código
Empacota tudo em um arquivo .jar executável

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

O que é Artifactory?

É um gerenciador de repositórios de artefatos usado em empresas. Funciona como um "armazém central" que:

Guarda bibliotecas internas - Código criado pela sua empresa
Faz cache de bibliotecas públicas - Copia do Maven Central para a rede da empresa
Controla versões - Sabe exatamente qual versão de cada biblioteca está sendo usada

Analogia: É como um armazém da Amazon, mas só para código da sua empresa.

Outros nomes: Nexus, Azure Artifacts, GitHub Packages (fazem a mesma coisa)

O que é Maven Local?

É uma pasta no seu computador (~/.m2/repository) que funciona como cache local de bibliotecas já baixadas.

Por que usar:

Evita baixar a mesma biblioteca várias vezes
Funciona offline se a biblioteca já foi baixada antes
Acelera o build (compilar sem internet)

Analogia: É como ter uma cópia local de livros que você já pegou emprestado antes.

Diferença: Plugins vs Dependências

Plugins (`settings.gradle.kts`)	Dependências (`build.gradle.kts`)
Ferramentas que ajudam a construir	Bibliotecas que o código usa
Exemplos: plugin do Kotlin, Spring Boot	Exemplos: Jackson, Spring Web
Baixados durante configuração do Gradle	Baixados durante compilação
Configura como o projeto é compilado	Código que roda na aplicação

💡 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! 💪