Criando Seu Primeiro Projeto Spring Boot: Guia Completo para Iniciantes

Índice

1. Por Que Spring Boot Mudou o Desenvolvimento Java?

Imagine poder criar uma aplicação web completa em Java sem precisar configurar dezenas de arquivos XML ou se perder em configurações complexas. Era exatamente esse o sonho de todo desenvolvedor Java há alguns anos — e o Spring Boot tornou isso realidade.

Antes do Spring Boot, configurar um projeto Spring tradicional era como montar um quebra-cabeça de mil peças: você precisava juntar manualmente cada componente, configurar servidores de aplicação, ajustar arquivos XML intermináveis e, só então, começar a escrever seu código de verdade.

O Spring Boot virou esse jogo de cabeça para baixo. Ele trouxe a filosofia de “convenção sobre configuração”, o que significa: menos tempo configurando, mais tempo criando.

2. O Que Você Vai Aprender

Neste guia, vamos construir juntos uma aplicação do zero, entendendo cada passo do caminho. Não se preocupe se você nunca mexeu com Spring antes — vou explicar tudo de forma clara e objetiva.

Ao final deste artigo, você terá:

✅ Um projeto Spring Boot funcionando na sua máquina
✅ Compreensão das peças fundamentais do framework
✅ Uma API REST simples que você mesmo criou
✅ Base sólida para explorar recursos mais avançados

3. Preparando o Terreno

Antes de começar, certifique-se de ter instalado:

Java 25: Spring Boot 3.x exige no mínimo o Java 17
Maven ou Gradle: gerenciadores de dependências (usaremos Maven nos exemplos)
IDE de sua preferência: IntelliJ IDEA, Eclipse, VS Code ou qualquer editor que você goste

Para verificar se o Java está instalado corretamente:

java -version

Se aparecer algo como java version "25.0.x" ou superior, está tudo certo!

4. Criando o Projeto: Três Caminhos Possíveis

Caminho 1: Spring Initializr (Recomendado)

O Spring Initializr é uma ferramenta web oficial que gera o esqueleto do seu projeto em segundos.

Segue explicação para cada campo na imagem:

Project: Nesse campo você precisa escolher qual ferramenta de gerenciamento e compressão você vai utilizar. Para esse projeto de exemplo irei utilizar o Maven. Haaa, lembrando quê, o Meven também é um gerenciado de dependências do Java assim como o Gradle;
Language: Selecione a linguagem de programação que você ira utilizar para implementar o projeto. No nosso casa iremos utilizar o Java;
Spring Boot: Selecione a versão do Spring Boot que será utilizado para criar o projeto. O Spring Boot é um framework que torna fácil a criação de aplicações Spring autossuficientes e robustas, possibilitando a sua execução imediata. Para o nosso exemplo iremos utilizar a versão 3.5.6;
Project Metadata: São as informações do projeto. Nesse campo você irá informar o Grupo, Artefato, Nome, Descricão, Nome do pacote, tipo de empacotamento e a versão do Java;
Dependencies: Selecione as dependências para o projeto. Como esse é um projeto exemplo muito simples iremos selecionar apenas três dependências, são elas: Spring Boot DevTools, Spring Boot Actuator e Spring Web.

Passo a passo:

Acesse https://start.spring.io/
Configure seu projeto:
- Project: Maven
- Language: Java
- Spring Boot: 3.5.6 (ou a versão estável mais recente)
- Group: com.exemplo
- Artifact: meu-primeiro-app
- Packaging: Jar
- Java: 25
Adicione as dependências iniciais:
- Spring Web: para criar APIs REST
- Spring Boot DevTools: para reiniciar automaticamente durante desenvolvimento
Clique em “GENERATE” e baixe o arquivo ZIP

Descompacte o arquivo em uma pasta de sua escolha e abra na sua IDE favorita.

Caminho 2: Via Linha de Comando (Para os Aventureiros)

Se preferir usar o terminal:

curl https://start.spring.io/starter.zip \
  -d dependencies=web,devtools \
  -d type=maven-project \
  -d language=java \
  -d bootVersion=3.5.6 \
  -d groupId=com.exemplo \
  -d artifactId=meu-primeiro-app \
  -d packageName=com.exemplo.meuprimeiro \
  -d javaVersion=25 \
  -o meu-primeiro-app.zip

Depois é só descompactar:

unzip meu-primeiro-app.zip -d meu-primeiro-app
cd meu-primeiro-app

Caminho 3: Direto na IDE

IntelliJ IDEA Community e Ultimate possuem integração direta com Spring Initializr. Basta ir em:

File → New → Project → Spring Initializr

3. Desvendando a Estrutura do Projeto

Quando você abre o projeto gerado, encontra uma estrutura organizada:

meu-primeiro-app/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/exemplo/meuprimeiro/
│   │   │       └── MeuPrimeiroAppApplication.java
│   │   └── resources/
│   │       ├── application.properties
│   │       ├── static/
│   │       └── templates/
│   └── test/
│       └── java/
├── pom.xml
└── mvnw (Maven Wrapper)

Entendendo Cada Parte

src/main/java/: Aqui fica todo o código Java da sua aplicação.

src/main/resources/: Arquivos de configuração, templates HTML, arquivos estáticos (CSS, JS).

application.properties: Arquivo central de configuração — é aqui que você define porta do servidor, conexão com banco de dados, etc.

pom.xml: Lista todas as dependências (bibliotecas) que seu projeto usa. O Maven baixa tudo automaticamente.

MeuPrimeiroAppApplication.java: O ponto de entrada da aplicação — é a classe principal que inicia tudo.

6. A Classe Principal: O Coração da Aplicação

Abra o arquivo MeuPrimeiroAppApplication.java. Você verá algo assim:

package com.exemplo.meuprimeiro;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MeuPrimeiroAppApplication {

    public static void main(String[] args) {
        SpringApplication.run(MeuPrimeiroAppApplication.class, args);
    }
}

Parece simples, mas há muita mágica acontecendo aqui.

Desvendando a Anotação @SpringBootApplication

A anotação @SpringBootApplication é na verdade três anotações em uma:

@Configuration: Diz ao Spring que essa classe pode conter definições de beans (componentes gerenciados)
@EnableAutoConfiguration: Ativa a configuração automática baseada nas dependências do projeto
@ComponentScan: Procura por outros componentes no mesmo pacote e subpacotes

Pense nela como o maestro de uma orquestra: ela coordena todas as peças da aplicação para trabalharem em harmonia.

7. Rodando Pela Primeira Vez

Vamos ver a mágica acontecer! No terminal, dentro da pasta do projeto:

./mvnw spring-boot:run

Ou, se estiver no Windows:

mvnw.cmd spring-boot:run

Você verá várias linhas de log passando rapidamente. Procure por algo como:

Started MeuPrimeiroAppApplication in 2.847 seconds

Parabéns! Sua aplicação está rodando na porta 8080.

Abra o navegador e acesse http://localhost:8080. Você verá uma página de erro — mas calma, isso é esperado! Ainda não criamos nenhuma rota. Vamos fazer isso agora.

8. Criando Sua Primeira API REST

Vamos criar um endpoint simples que retorna uma mensagem de boas-vindas.

Crie uma nova classe chamada OlaController.java dentro de src/main/java/com/exemplo/meuprimeiro/:

package com.exemplo.meuprimeiro;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class OlaController {

    @GetMapping("/ola")
    public String dizerOla(@RequestParam(defaultValue = "Mundo") String nome) {
        return "Olá, " + nome + "! Bem-vindo ao Spring Boot!";
    }
}

Entendendo o Código

@RestController: Combina @Controller + @ResponseBody, indicando que essa classe manipula requisições HTTP e retorna dados diretamente (geralmente JSON).

@GetMapping("/ola"): Define que o método abaixo responde a requisições GET no caminho /ola.

@RequestParam: Captura parâmetros da URL. Se não for informado, usa “Mundo” como padrão.

Salve o arquivo e, graças ao DevTools, a aplicação reinicia automaticamente.

Agora acesse no navegador:

http://localhost:8080/ola → “Olá, Mundo! Bem-vindo ao Spring Boot!”
http://localhost:8080/ola?nome=João → “Olá, João! Bem-vindo ao Spring Boot!”

🎉 Você acabou de criar sua primeira API REST!

9. Trabalhando com JSON: O Padrão da Web Moderna

APIs REST geralmente trafegam dados em formato JSON. Vamos evoluir nosso exemplo.

Crie uma classe Usuario.java:

package com.exemplo.meuprimeiro;

public class Usuario {
    private String nome;
    private String email;
    private int idade;

    // Construtor
    public Usuario(String nome, String email, int idade) {
        this.nome = nome;
        this.email = email;
        this.idade = idade;
    }

    // Getters e Setters
    public String getNome() { return nome; }
    public void setNome(String nome) { this.nome = nome; }
    
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    
    public int getIdade() { return idade; }
    public void setIdade(int idade) { this.idade = idade; }
}

Agora, adicione um novo método no OlaController:

@GetMapping("/usuario")
public Usuario obterUsuario() {
    return new Usuario("Maria Silva", "maria@exemplo.com", 28);
}

Acesse http://localhost:8080/usuario e veja a mágica:

{
  "nome": "Maria Silva",
  "email": "maria@exemplo.com",
  "idade": 28
}

O Spring Boot automaticamente converte o objeto Java em JSON. Essa conversão é feita pela biblioteca Jackson, que já vem incluída.

10. Criando uma Lista de Recursos

Vamos criar algo mais realista: uma API de tarefas (to-do list).

Primeiro, crie a classe Tarefa.java:

package com.exemplo.meuprimeiro;

public class Tarefa {
    private Long id;
    private String descricao;
    private boolean concluida;

    public Tarefa(Long id, String descricao, boolean concluida) {
        this.id = id;
        this.descricao = descricao;
        this.concluida = concluida;
    }

    // Getters e Setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    
    public String getDescricao() { return descricao; }
    public void setDescricao(String descricao) { this.descricao = descricao; }
    
    public boolean isConcluida() { return concluida; }
    public void setConcluida(boolean concluida) { this.concluida = concluida; }
}

Agora crie o TarefaController.java:

package com.exemplo.meuprimeiro;

import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;

@RestController
@RequestMapping("/tarefas")
public class TarefaController {

    private List<Tarefa> tarefas = new ArrayList<>();
    private Long proximoId = 1L;

    // Construtor com dados iniciais
    public TarefaController() {
        tarefas.add(new Tarefa(proximoId++, "Aprender Spring Boot", false));
        tarefas.add(new Tarefa(proximoId++, "Criar minha primeira API", true));
    }

    // Listar todas as tarefas
    @GetMapping
    public List<Tarefa> listarTodas() {
        return tarefas;
    }

    // Buscar tarefa por ID
    @GetMapping("/{id}")
    public Tarefa buscarPorId(@PathVariable Long id) {
        return tarefas.stream()
            .filter(t -> t.getId().equals(id))
            .findFirst()
            .orElse(null);
    }

    // Criar nova tarefa
    @PostMapping
    public Tarefa criar(@RequestBody Tarefa novaTarefa) {
        novaTarefa.setId(proximoId++);
        tarefas.add(novaTarefa);
        return novaTarefa;
    }

    // Marcar como concluída
    @PatchMapping("/{id}/concluir")
    public Tarefa concluir(@PathVariable Long id) {
        Tarefa tarefa = buscarPorId(id);
        if (tarefa != null) {
            tarefa.setConcluida(true);
        }
        return tarefa;
    }

    // Deletar tarefa
    @DeleteMapping("/{id}")
    public String deletar(@PathVariable Long id) {
        tarefas.removeIf(t -> t.getId().equals(id));
        return "Tarefa removida com sucesso!";
    }
}

Testando a API de Tarefas

Você pode usar ferramentas como Postman, Insomnia ou o próprio cURL:

Listar todas as tarefas:

curl http://localhost:8080/tarefas

Buscar tarefa específica:

curl http://localhost:8080/tarefas/1

Criar nova tarefa:

curl -X POST http://localhost:8080/tarefas \
  -H "Content-Type: application/json" \
  -d '{"descricao":"Estudar Controllers","concluida":false}'

Marcar como concluída:

curl -X PATCH http://localhost:8080/tarefas/1/concluir

Deletar tarefa:

curl -X DELETE http://localhost:8080/tarefas/2

11. Personalizando Configurações

O arquivo application.properties é onde você ajusta o comportamento da aplicação.

# Alterar a porta do servidor
server.port=9090

# Definir contexto da aplicação
server.servlet.context-path=/api

# Configurar logs
logging.level.root=INFO
logging.level.com.exemplo.meuprimeiro=DEBUG

# Mensagens personalizadas
app.mensagem-boas-vindas=Seja bem-vindo à nossa aplicação!

Você pode injetar essas propriedades no código:

@RestController
public class ConfigController {

    @Value("${app.mensagem-boas-vindas}")
    private String mensagem;

    @GetMapping("/config")
    public String obterMensagem() {
        return mensagem;
    }
}

12. Organizando o Código: Arquitetura em Camadas

À medida que sua aplicação cresce, é fundamental organizar bem o código. Uma estrutura comum é:

com/exemplo/meuprimeiro/
├── controller/      ← Recebe requisições HTTP
├── service/         ← Contém lógica de negócio
├── repository/      ← Acessa dados (banco, APIs externas)
└── model/           ← Classes de domínio (Tarefa, Usuario, etc)

Essa separação traz vários benefícios:

🧩 Código mais organizado: cada classe tem uma responsabilidade clara
🔄 Facilita manutenção: mudanças em uma camada não afetam as outras
🧪 Testes mais fáceis: você pode testar cada camada isoladamente

13. Próximos Passos na Sua Jornada

Você deu o primeiro passo — e que passo importante! Mas o universo Spring Boot é vasto. Aqui estão algumas direções para explorar:

Banco de Dados com Spring Data JPA

Aprenda a persistir dados de verdade usando JPA e Hibernate. Adicione a dependência spring-boot-starter-data-jpa e um banco H2 para começar.

Segurança com Spring Security

Proteja suas APIs com autenticação e autorização. Spring Security oferece recursos poderosos desde basic auth até OAuth2.

Testes Automatizados

Use @SpringBootTest e @WebMvcTest para garantir que sua aplicação funciona como esperado.

Deploy em Produção

Aprenda a empacotar sua aplicação em um container Docker e fazer deploy em serviços cloud como Heroku, AWS, ou Azure.

Documentação com OpenAPI

Adicione springdoc-openapi para gerar documentação interativa automática da sua API.

14. Dicas de Ouro para Iniciantes

💡 Aprenda aos poucos: Não tente dominar tudo de uma vez. Spring Boot tem muitos recursos, mas você não precisa de todos no começo.

💡 Leia as mensagens de erro: O Spring fornece erros bem descritivos. Leia com atenção — geralmente a solução está ali.

💡 Use o DevTools: Ele reinicia a aplicação automaticamente quando você salva um arquivo. Economiza muito tempo!

💡 Explore a documentação oficial: docs.spring.io/spring-boot é seu melhor amigo.

💡 Pratique, pratique, pratique e pratique mais, mais e mais: Crie projetos pessoais. A melhor forma de aprender é fazendo.

15. Recursos Complementares

📚 Spring Boot Reference Guide: Documentação oficial completa
🎓 Spring Academy: Cursos gratuitos oficiais do Spring
🎥 Spring I/O YouTube: Palestras e tutoriais em vídeo

16. Conclusão

Criar seu primeiro projeto Spring Boot é como aprender a andar de bicicleta: pode parecer complicado no começo, mas depois que você pega o jeito, nunca mais esquece.

Você aprendeu hoje os fundamentos essenciais:

Como estruturar um projeto Spring Boot
O que são controllers e como criar endpoints REST
Como trabalhar com JSON e objetos Java
Conceitos de configuração e organização de código

O mais importante é que você não apenas leu sobre — você fez. Sua aplicação está rodando, respondendo requisições, processando dados. Isso é programação de verdade.

Agora é hora de experimentar, quebrar, consertar e aprender ainda mais. O Spring Boot é uma ferramenta poderosa que está presente em milhares de empresas ao redor do mundo. Dominar essa tecnologia abre muitas portas no mercado de trabalho.

Então continue explorando, continue criando e, acima de tudo, continue se divertindo com código!

Índice#

1. Por Que Spring Boot Mudou o Desenvolvimento Java?#

2. O Que Você Vai Aprender#

3. Preparando o Terreno#

4. Criando o Projeto: Três Caminhos Possíveis#

Caminho 1: Spring Initializr (Recomendado)#

Caminho 2: Via Linha de Comando (Para os Aventureiros)#

Caminho 3: Direto na IDE#

3. Desvendando a Estrutura do Projeto#

Entendendo Cada Parte#

6. A Classe Principal: O Coração da Aplicação#

Desvendando a Anotação @SpringBootApplication#

7. Rodando Pela Primeira Vez#

8. Criando Sua Primeira API REST#

Entendendo o Código#

9. Trabalhando com JSON: O Padrão da Web Moderna#

10. Criando uma Lista de Recursos#

Testando a API de Tarefas#

11. Personalizando Configurações#

12. Organizando o Código: Arquitetura em Camadas#

13. Próximos Passos na Sua Jornada#

Banco de Dados com Spring Data JPA#

Segurança com Spring Security#

Testes Automatizados#

Deploy em Produção#

Documentação com OpenAPI#

14. Dicas de Ouro para Iniciantes#

15. Recursos Complementares#

16. Conclusão#