🚀 Spring Boot REST API - Guia Completo para Iniciantes

Aplicação didática demonstrando as melhores práticas de desenvolvimento REST API com Spring Boot

Documentação • Instalação • Endpoints • Exemplos • Arquitetura

📑 Índice

🎯 Sobre o Projeto

Esta aplicação REST API foi desenvolvida com propósito 100% didático para demonstrar as melhores práticas de desenvolvimento Java com Spring Boot, seguindo os princípios SOLID e Clean Code.

🎓 Objetivos de Aprendizado

✅ Arquitetura em Camadas: Controller → Service → DTO
✅ Validação de Dados: Bean Validation com Jakarta
✅ Tratamento de Exceções: Global Exception Handler
✅ Documentação: JavaDoc completo e README detalhado
✅ Padrões REST: Endpoints semânticos e status HTTP corretos
✅ Clean Code: Código limpo, legível e manutenível
✅ SOLID: Aplicação dos 5 princípios fundamentais
✅ HTTP Headers: Manipulação correta de headers
✅ Request/Response Patterns: DTOs padronizados

🎯 O Que Você Vai Aprender

📦 Body Parameters (Request Body)

Validação de dados com Jakarta Bean Validation
DTOs (Data Transfer Objects) para Request/Response
Anotações: @Valid, @RequestBody, @NotBlank, @Size, @Min

🔗 URL Parameters

Path Variables: Parâmetros na URL (/api/users/{id})
Query Parameters: Parâmetros de consulta (?page=1&size=10)
Validação de tipos e valores

📋 HTTP Headers

Captura de headers específicos e múltiplos
Headers customizados na resposta
Validação de headers obrigatórios

🛡️ Exception Handling

Tratamento centralizado de exceções
Respostas padronizadas de erro
Validação em diferentes camadas

⬆️ Voltar ao Índice

🛠 Tecnologias Utilizadas

Backend Framework
├── Spring Boot 3.5.7        → Framework principal
├── Spring Web               → REST API
├── Spring Validation        → Jakarta Bean Validation
└── Spring Actuator          → Monitoramento e métricas

Build & Dependency Management
├── Maven 3.9+               → Gerenciamento de dependências
└── Java 17                  → Linguagem de programação

Tools & DevOps
├── Spring DevTools          → Hot reload em desenvolvimento
├── Docker                   → Containerização
└── Git                      → Controle de versão

📦 Dependências Principais

<!-- Spring Boot Starter Web -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- Jakarta Bean Validation -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

<!-- Spring Boot Actuator -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

⬆️ Voltar ao Índice

📋 Pré-requisitos

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

Ferramenta	Versão Mínima	Download
Java JDK	17+	Oracle JDK
Maven	3.9+	Apache Maven
Git	2.0+	Git SCM
IDE	-	IntelliJ IDEA ou VS Code

✅ Verificação da Instalação

# Verificar Java
java -version
# Saída esperada: openjdk version "17.x.x"

# Verificar Maven
mvn -version
# Saída esperada: Apache Maven 3.9.x

# Verificar Git
git --version
# Saída esperada: git version 2.x.x

⬆️ Voltar ao Índice

🚀 Instalação Rápida

1️⃣ Clone o Repositório

git clone https://github.com/Cardosofiles/springboot-starter-server.git
cd springboot-starter-server

2️⃣ Instale as Dependências

mvn clean install

3️⃣ Execute a Aplicação

mvn spring-boot:run

4️⃣ Verificar Instalação

A aplicação estará disponível em: http://localhost:8080

# Testar Health Check
curl http://localhost:8080/api/v1/health

⬆️ Voltar ao Índice

▶️ Como Executar

🔥 Modo Desenvolvimento (com Hot Reload)

mvn spring-boot:run

📦 Gerar JAR Executável

# Compilar e gerar JAR
mvn clean package

# Executar JAR
java -jar target/springboot-starter-server-0.0.1.jar

🐳 Com Docker

# Construir imagem
docker build -t springboot-api:latest .

# Executar container
docker run -p 8080:8080 --name api-server springboot-api:latest

# Verificar logs
docker logs -f api-server

🔍 Verificar Status

# Health Check
curl http://localhost:8080/api/v1/health

# Actuator Endpoints
curl http://localhost:8080/actuator
curl http://localhost:8080/actuator/health

⬆️ Voltar ao Índice

🏗 Arquitetura do Projeto

Este projeto segue uma arquitetura em camadas (Layered Architecture) aplicando princípios SOLID e Clean Code.

┌─────────────────────────────────────────────────────────┐
│                      CLIENT LAYER                        │
│            (Browser, Mobile App, Postman)                │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                   CONTROLLER LAYER                       │
│  • Recebe requisições HTTP                               │
│  • Valida entrada com @Valid                             │
│  • Delega para Service Layer                             │
│  • Retorna ResponseEntity com DTOs                       │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                    SERVICE LAYER                         │
│  • Contém lógica de negócio                              │
│  • Processa dados                                        │
│  • Coordena operações                                    │
│  • Independente de framework                             │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                      DTO LAYER                           │
│  • Request DTOs (entrada)                                │
│  • Response DTOs (saída)                                 │
│  • Validações com Jakarta Bean Validation                │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                  EXCEPTION HANDLER                       │
│  • Tratamento centralizado de erros                      │
│  • Respostas padronizadas                                │
│  • @RestControllerAdvice                                 │
└─────────────────────────────────────────────────────────┘

🎯 Princípios SOLID Aplicados

Princípio	Aplicação no Projeto
Single Responsibility	Cada classe tem uma única responsabilidade
Open/Closed	Extensível via herança, fechado para modificação
Liskov Substitution	DTOs e Services são substituíveis
Interface Segregation	Interfaces específicas para cada contexto
Dependency Inversion	Controllers dependem de abstrações (Services)

⬆️ Voltar ao Índice

📁 Estrutura de Diretórios

springboot-starter-server/
│
├── src/
│   ├── main/
│   │   ├── java/com/cardosofiles/
│   │   │   │
│   │   │   ├── controller/                    # 🎮 Camada de Controllers
│   │   │   │   ├── BodyRequestController.java      → Requisições POST/PUT
│   │   │   │   ├── UrlParamsController.java        → Path Variables & Query Params
│   │   │   │   ├── HeaderParamsController.java     → HTTP Headers
│   │   │   │   └── HealthCheckController.java      → Health Check
│   │   │   │
│   │   │   ├── service/                       # 💼 Camada de Serviços
│   │   │   │   ├── UserService.java               → Lógica de usuários
│   │   │   │   ├── UrlParamsService.java          → Processamento de params
│   │   │   │   └── HeaderService.java             → Processamento de headers
│   │   │   │
│   │   │   ├── dto/                          # 📦 Data Transfer Objects
│   │   │   │   ├── request/
│   │   │   │   │   └── UserRequest.java           → DTO de entrada
│   │   │   │   └── response/
│   │   │   │       ├── ApiResponse.java           → DTO genérico de resposta
│   │   │   │       ├── HealthResponse.java        → DTO health check
│   │   │   │       ├── QueryParamsResponse.java   → DTO query params
│   │   │   │       └── HeaderInfoResponse.java    → DTO headers
│   │   │   │
│   │   │   ├── exception/                    # 🛡️ Tratamento de Exceções
│   │   │   │   └── GlobalExceptionHandler.java    → Handler global
│   │   │   │
│   │   │   └── SpringbootStarterServerApplication.java  # 🚀 Classe Principal
│   │   │
│   │   └── resources/
│   │       ├── application.properties         # ⚙️ Configurações
│   │       └── application.yml                # ⚙️ Configurações (alternativo)
│   │
│   └── test/                                 # 🧪 Testes Unitários
│       └── java/com/cardosofiles/
│
├── .github/
│   └── copilot-instructions.md               # 🤖 Instruções Copilot
│
├── pom.xml                                   # 📦 Dependências Maven
├── Dockerfile                                # 🐳 Configuração Docker
├── .gitignore                                # 🚫 Arquivos ignorados
└── README.md                                 # 📖 Documentação (este arquivo)

📝 Descrição das Camadas

🎮 Controller Layer

Responsável por:

Receber requisições HTTP
Validar entrada com @Valid
Delegar processamento para Services
Retornar respostas padronizadas

💼 Service Layer

Responsável por:

Implementar lógica de negócio
Processar dados
Coordenar operações
Ser independente de framework

📦 DTO Layer

Responsável por:

Definir estrutura de dados
Aplicar validações
Documentar contratos de API

🛡️ Exception Handler

Responsável por:

Capturar exceções globalmente
Padronizar respostas de erro
Retornar status HTTP apropriados

⬆️ Voltar ao Índice

🌐 Endpoints da API

📊 Visão Geral

Categoria	Endpoint Base	Descrição
👤 Usuários	`/api/v1/users`	Operações com body parameters
🔗 Parâmetros	`/api/v1/params`	Path variables e query params
📋 Headers	`/api/v1/headers`	Manipulação de HTTP headers
❤️ Health	`/api/v1/health`	Status da aplicação

👤 Body Parameters (Usuários)

POST `/api/v1/users`

Cria um novo usuário.

Request Body:

{
  "username": "john_doe",
  "age": 25
}

Response (201 Created):

{
  "success": true,
  "message": "Usuário criado com sucesso",
  "data": {
    "username": "john_doe",
    "age": 25
  },
  "timestamp": "2024-01-15T10:30:00"
}

Validações:

username: obrigatório, 3-50 caracteres, alfanumérico
age: obrigatório, >= 0

PUT `/api/v1/users`

Atualiza dados de um usuário.

Request Body:

{
  "username": "john_updated",
  "age": 26
}

Response (200 OK):

{
  "success": true,
  "message": "Usuário atualizado com sucesso",
  "data": {
    "username": "john_updated",
    "age": 26
  },
  "timestamp": "2024-01-15T10:35:00"
}

🔗 URL Parameters

GET `/api/v1/params/path/{id}`

Busca recurso por ID via path variable.

Exemplo:

GET /api/v1/params/path/123

Response (200 OK):

{
  "success": true,
  "message": "Recurso encontrado",
  "data": "Recurso com ID: 123",
  "timestamp": "2024-01-15T10:40:00"
}

Validações:

id: deve ser um número positivo

GET `/api/v1/params/query`

Busca com query parameter simples.

Exemplo:

GET /api/v1/params/query?search=spring

Response (200 OK):

{
  "success": true,
  "message": "Busca realizada com sucesso",
  "data": "Resultado da busca por: spring",
  "timestamp": "2024-01-15T10:45:00"
}

GET `/api/v1/params/query/paginated`

Busca paginada com múltiplos query params.

Exemplo:

GET /api/v1/params/query/paginated?page=1&size=20&sort=name

Response (200 OK):

{
  "success": true,
  "message": "Listagem realizada com sucesso",
  "data": {
    "page": 1,
    "size": 20,
    "sort": "name",
    "message": "Página 1 com 20 itens, ordenado por: name"
  },
  "timestamp": "2024-01-15T10:50:00"
}

Parâmetros:

page (opcional, padrão: 0): número da página
size (opcional, padrão: 10): itens por página
sort (opcional): campo de ordenação

GET `/api/v1/params/query/all`

Captura todos os query parameters dinamicamente.

Exemplo:

GET /api/v1/params/query/all?filter=active&status=published&category=tech

Response (200 OK):

{
  "success": true,
  "message": "Parâmetros processados com sucesso",
  "data": {
    "filter": "Processado: active",
    "status": "Processado: published",
    "category": "Processado: tech"
  },
  "timestamp": "2024-01-15T10:55:00"
}

📋 HTTP Headers

GET `/api/v1/headers/single`

Captura um header específico.

Request Headers:

X-API-Key: abc123def456

Response (200 OK):

{
  "success": true,
  "message": "Header processado com sucesso",
  "data": "API Key validada: abc123de...",
  "timestamp": "2024-01-15T11:00:00"
}

GET `/api/v1/headers/multiple`

Captura múltiplos headers.

Request Headers:

User-Agent: Mozilla/5.0
Authorization: Bearer token123
Content-Type: application/json

Response (200 OK):

{
  "success": true,
  "message": "Headers processados com sucesso",
  "data": {
    "userAgent": "Mozilla/5.0",
    "authorization": "Bearer ***",
    "contentType": "application/json",
    "allHeaders": null
  },
  "timestamp": "2024-01-15T11:05:00"
}

GET `/api/v1/headers/all`

Captura todos os headers da requisição.

Response (200 OK):

{
  "success": true,
  "message": "Todos os headers capturados",
  "data": {
    "userAgent": "PostmanRuntime/7.32.0",
    "authorization": null,
    "contentType": "application/json",
    "allHeaders": {
      "host": "localhost:8080",
      "connection": "keep-alive",
      "user-agent": "PostmanRuntime/7.32.0",
      "accept": "*/*"
    }
  },
  "timestamp": "2024-01-15T11:10:00"
}

POST `/api/v1/headers/response`

Define headers customizados na resposta.

Exemplo:

POST /api/v1/headers/response?customValue=myvalue

Response Headers:

X-Custom-Header: myvalue
X-Response-Time: 1705318200000

Response (200 OK):

{
  "success": true,
  "message": "Header de resposta configurado",
  "data": "Valor customizado processado: myvalue",
  "timestamp": "2024-01-15T11:15:00"
}

❤️ Health Check

GET `/api/v1/health`

Verifica o status da aplicação.

Response (200 OK):

{
  "success": true,
  "message": "Aplicação está funcionando corretamente",
  "data": {
    "status": "UP",
    "timestamp": "2024-01-15T11:20:00",
    "version": "1.0.0"
  },
  "timestamp": "2024-01-15T11:20:00"
}

⬆️ Voltar ao Índice

💡 Exemplos de Uso

🔧 Usando cURL

Criar Usuário

curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "age": 25
  }'

Buscar por ID

curl http://localhost:8080/api/v1/params/path/123

Busca com Query Params

curl "http://localhost:8080/api/v1/params/query/paginated?page=1&size=10&sort=name"

Enviar Header Customizado

curl http://localhost:8080/api/v1/headers/single \
  -H "X-API-Key: my-secret-key-123"

📮 Usando Postman

Importar Coleção
- Crie uma nova coleção chamada "Spring Boot API"
- Configure a variável {{baseUrl}} = http://localhost:8080

Exemplo POST Request

Method: POST
URL: {{baseUrl}}/api/v1/users
Headers:
  Content-Type: application/json
Body (raw JSON):
  {
    "username": "testuser",
    "age": 30
  }

Exemplo GET com Headers

Method: GET
URL: {{baseUrl}}/api/v1/headers/multiple
Headers:
  User-Agent: Postman/10.0
  Authorization: Bearer mytoken123
  Content-Type: application/json

🐍 Usando Python (requests)

import requests

# URL base
BASE_URL = "http://localhost:8080/api/v1"

# Criar usuário
def create_user():
    response = requests.post(
        f"{BASE_URL}/users",
        json={"username": "pythonuser", "age": 28}
    )
    print(response.json())

# Buscar com query params
def search_paginated():
    params = {"page": 1, "size": 10, "sort": "name"}
    response = requests.get(f"{BASE_URL}/params/query/paginated", params=params)
    print(response.json())

# Enviar headers customizados
def send_headers():
    headers = {"X-API-Key": "python-key-123"}
    response = requests.get(f"{BASE_URL}/headers/single", headers=headers)
    print(response.json())

if __name__ == "__main__":
    create_user()
    search_paginated()
    send_headers()

☕ Usando Java (RestTemplate)

import org.springframework.web.client.RestTemplate;
import org.springframework.http.*;

public class ApiClient {
    private static final String BASE_URL = "http://localhost:8080/api/v1";
    private final RestTemplate restTemplate = new RestTemplate();

    // Criar usuário
    public void createUser() {
        String url = BASE_URL + "/users";

        UserRequest request = new UserRequest("javauser", 30);

        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);

        HttpEntity<UserRequest> entity = new HttpEntity<>(request, headers);

        ResponseEntity<ApiResponse> response = restTemplate.postForEntity(
            url, entity, ApiResponse.class
        );

        System.out.println(response.getBody());
    }

    // Buscar com path variable
    public void getById() {
        String url = BASE_URL + "/params/path/123";

        ResponseEntity<ApiResponse> response = restTemplate.getForEntity(
            url, ApiResponse.class
        );

        System.out.println(response.getBody());
    }
}

⬆️ Voltar ao Índice

✅ Validações Implementadas

📋 Validações de Body Parameters

Campo	Validação	Mensagem de Erro
`username`	`@NotBlank`	"O nome de usuário é obrigatório"
`username`	`@Size(min=3, max=50)`	"O nome de usuário deve ter entre 3 e 50 caracteres"
`username`	`@Pattern(regexp="^[a-zA-Z0-9_-]+$")`	"O nome de usuário deve conter apenas letras, números, hífens e underscores"
`age`	`@Min(0)`	"A idade deve ser maior ou igual a 0"

🔗 Validações de URL Parameters

Parâmetro	Validação	Mensagem de Erro
`id`	`@Positive`	"ID deve ser um número positivo"
`search`	`@NotBlank`	"Parâmetro de busca não pode ser vazio"
`page`	`@Positive`	"Página deve ser positiva"
`size`	`@Positive`	"Tamanho deve ser positivo"

📋 Validações de Headers

Header	Validação	Mensagem de Erro
`X-API-Key`	`@NotBlank`	"API Key é obrigatória"

📝 Exemplo de Erro de Validação

Request Inválido:

{
  "username": "ab",
  "age": -5
}

Response (400 Bad Request):

{
  "success": false,
  "message": "Erro de validação nos dados enviados",
  "data": {
    "username": "O nome de usuário deve ter entre 3 e 50 caracteres",
    "age": "A idade deve ser maior ou igual a 0"
  },
  "timestamp": "2024-01-15T11:30:00"
}

⬆️ Voltar ao Índice

🛡️ Tratamento de Erros

O projeto implementa um Global Exception Handler que captura e trata todos os erros de forma centralizada.

🎯 Tipos de Erros Tratados

1. Erro de Validação (400 Bad Request)

Causa: Dados inválidos no body, path variable ou query param

Exemplo:

{
  "success": false,
  "message": "Erro de validação nos dados enviados",
  "data": {
    "username": "O nome de usuário é obrigatório",
    "age": "A idade deve ser maior ou igual a 0"
  },
  "timestamp": "2024-01-15T11:35:00"
}

2. Erro de Tipo Incorreto (400 Bad Request)

Causa: Tipo de dado incompatível (ex: string quando esperado número)

Request:

GET /api/v1/params/path/abc

Response:

{
  "success": false,
  "message": "O parâmetro 'id' deve ser do tipo Long",
  "data": null,
  "timestamp": "2024-01-15T11:40:00"
}

3. Header Obrigatório Ausente (400 Bad Request)

Request sem header:

GET /api/v1/headers/single

Response:

{
  "success": false,
  "message": "Header obrigatório ausente: X-API-Key",
  "data": null,
  "timestamp": "2024-01-15T11:45:00"
}

4. Erro Interno do Servidor (500 Internal Server Error)

Response:

{
  "success": false,
  "message": "Erro interno do servidor",
  "data": "Descrição detalhada do erro",
  "timestamp": "2024-01-15T11:50:00"
}

📊 Status HTTP Utilizados

Status	Código	Significado	Quando Usar
✅ OK	200	Sucesso	GET, PUT bem-sucedidos
✅ Created	201	Criado	POST bem-sucedido
❌ Bad Request	400	Requisição inválida	Erro de validação
❌ Not Found	404	Não encontrado	Recurso inexistente
❌ Internal Server Error	500	Erro no servidor	Erro não tratado

⬆️ Voltar ao Índice

📐 Padrões e Boas Práticas

🎯 Clean Code Principles

✅ Nomes Significativos

// ❌ Evitar
public String m1(String s) { ... }

// ✅ Fazer
public String createUser(String username) { ... }

✅ Funções Pequenas (SRP)

// ❌ Evitar - função faz muitas coisas
public void processUser(UserRequest request) {
    validate(request);
    save(request);
    sendEmail(request);
    log(request);
}

// ✅ Fazer - cada função tem uma responsabilidade
public void processUser(UserRequest request) {
    userService.createUser(request);
}

✅ Comentários Apenas Quando Necessário

// ❌ Evitar comentários óbvios
// Retorna o nome do usuário
public String getUsername() { ... }

// ✅ Fazer - código auto-explicativo
public String getUsername() { ... }

// ✅ Comentar lógica complexa quando necessário
// Aplica algoritmo de criptografia AES-256 com salt aleatório
public String encryptPassword(String password) { ... }

🏛️ SOLID Principles

1. Single Responsibility Principle (SRP)

Cada classe tem uma única responsabilidade.

// ✅ Controller - apenas recebe requisições
@RestController
public class UserController {
    private final UserService userService;
    // ...
}

// ✅ Service - apenas lógica de negócio
@Service
public class UserService {
    public UserRequest createUser(UserRequest request) {
        // lógica de negócio
    }
}

2. Open/Closed Principle (OCP)

Aberto para extensão, fechado para modificação.

// ✅ Extensível através de herança/interfaces
public abstract class BaseService {
    protected void logOperation(String operation) {
        // implementação base
    }
}

public class UserService extends BaseService {
    // Pode estender sem modificar a base
}

3. Dependency Inversion Principle (DIP)

Dependa de abstrações, não de implementações.

// ✅ Controller depende da abstração (interface/service)
@RestController
public class UserController {
    private final UserService userService; // abstração

    public UserController(UserService userService) {
        this.userService = userService;
    }
}

📋 REST API Best Practices

✅ Verbos HTTP Corretos

Verbo	Uso	Exemplo
GET	Buscar dados	`GET /api/v1/users`
POST	Criar recurso	`POST /api/v1/users`
PUT	Atualizar completo	`PUT /api/v1/users/{id}`
PATCH	Atualizar parcial	`PATCH /api/v1/users/{id}`
DELETE	Remover	`DELETE /api/v1/users/{id}`

✅ URLs Semânticas

# ✅ Fazer
GET /api/v1/users
POST /api/v1/users
GET /api/v1/users/123

# ❌ Evitar
GET /api/v1/getUsers
POST /api/v1/createUser
GET /api/v1/getUserById?id=123

✅ Versionamento

# ✅ Versão na URL
/api/v1/users
/api/v2/users

# ✅ Versão no header
Accept: application/vnd.api.v1+json

✅ Respostas Padronizadas

{
  "success": true,
  "message": "Operação realizada com sucesso",
  "data": {
    /* dados */
  },
  "timestamp": "2024-01-15T12:00:00"
}

⬆️ Voltar ao Índice

⚙️ Configuração do Ambiente

📄 application.properties

# Application
spring.application.name=springboot-starter-server
server.port=8080

# Actuator
management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=always

# Logging
logging.level.root=INFO
logging.level.com.cardosofiles=DEBUG
logging.pattern.console=%d{yyyy-MM-dd HH:mm:ss} - %msg%n

# Encoding
spring.http.encoding.charset=UTF-8
spring.http.encoding.enabled=true

🐳 Dockerfile

# filepath: /home/cardosofiles/www/java/developement/springboot-starter-server/Dockerfile
FROM openjdk:17-jdk-slim

WORKDIR /app

COPY target/springboot-starter-server-0.0.1.jar app.jar

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "app.jar"]

🐳 docker-compose.yml

# filepath: /home/cardosofiles/www/java/developement/springboot-starter-server/docker-compose.yml
version: "3.8"

services:
  api:
    build: .
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
    restart: unless-stopped

⬆️ Voltar ao Índice

🧪 Executando Testes

Executar Todos os Testes

mvn test

Executar Testes com Cobertura

mvn clean test jacoco:report

Relatório de Cobertura

# Abrir relatório no navegador
open target/site/jacoco/index.html

⬆️ Voltar ao Índice

🐳 Deploy com Docker

Build da Imagem

# Compilar aplicação
mvn clean package -DskipTests

# Construir imagem Docker
docker build -t springboot-api:1.0.0 .

# Verificar imagem criada
docker images | grep springboot-api

Executar Container

# Executar em primeiro plano
docker run -p 8080:8080 springboot-api:1.0.0

# Executar em background
docker run -d -p 8080:8080 --name api-server springboot-api:1.0.0

# Ver logs
docker logs -f api-server

# Parar container
docker stop api-server

# Remover container
docker rm api-server

Docker Compose

# Iniciar serviços
docker-compose up -d

# Ver logs
docker-compose logs -f

# Parar serviços
docker-compose down

# Rebuild e restart
docker-compose up -d --build

⬆️ Voltar ao Índice

📚 Referências

📖 Documentação Oficial

🎓 Tutoriais e Guias

📚 Livros Recomendados

Clean Code - Robert C. Martin
Design Patterns - Gang of Four
Spring in Action - Craig Walls
Effective Java - Joshua Bloch

🎥 Cursos e Vídeos

⬆️ Voltar ao Índice

🤝 Contribuindo

Contribuições são sempre bem-vindas! Este é um projeto didático e melhorias são incentivadas.

📝 Como Contribuir

Fork o projeto

git clone https://github.com/Cardosofiles/springboot-starter-server.git

Crie uma branch para sua feature

git checkout -b feature/nova-funcionalidade

Commit suas mudanças

git commit -m 'feat: adiciona nova funcionalidade'

Push para a branch

git push origin feature/nova-funcionalidade

Abra um Pull Request

📋 Padrão de Commits

Seguimos o Conventional Commits:

feat: nova funcionalidade
fix: correção de bug
docs: documentação
style: formatação
refactor: refatoração
test: testes
chore: tarefas gerais

✅ Checklist do PR

Código segue os padrões do projeto
Testes passando
Documentação atualizada
Commits seguem o padrão

⬆️ Voltar ao Índice

📧 Contato

⬆️ Voltar ao Índice

🙏 Agradecimentos

Spring Team pela excelente documentação
Comunidade Java pelo suporte
Todos que contribuíram com este projeto

⭐ Se este projeto te ajudou, considere dar uma estrela!

📚 Feito com ❤️ para fins educacionais

⬆️ Voltar ao topo

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.mvn/wrapper		.mvn/wrapper
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

🚀 Spring Boot REST API - Guia Completo para Iniciantes

📑 Índice

🎯 Começando

📚 Documentação

💡 Uso Prático

🔧 Desenvolvimento

📖 Recursos Adicionais

🎯 Sobre o Projeto

🎓 Objetivos de Aprendizado

🎯 O Que Você Vai Aprender

📦 Body Parameters (Request Body)

🔗 URL Parameters

📋 HTTP Headers

🛡️ Exception Handling

🛠 Tecnologias Utilizadas

📦 Dependências Principais

📋 Pré-requisitos

✅ Verificação da Instalação

🚀 Instalação Rápida

1️⃣ Clone o Repositório

2️⃣ Instale as Dependências

3️⃣ Execute a Aplicação

4️⃣ Verificar Instalação

▶️ Como Executar

🔥 Modo Desenvolvimento (com Hot Reload)

📦 Gerar JAR Executável

🐳 Com Docker

🔍 Verificar Status

🏗 Arquitetura do Projeto

🎯 Princípios SOLID Aplicados

📁 Estrutura de Diretórios

📝 Descrição das Camadas

🎮 Controller Layer

💼 Service Layer

📦 DTO Layer

🛡️ Exception Handler

🌐 Endpoints da API

📊 Visão Geral

👤 Body Parameters (Usuários)

POST /api/v1/users

PUT /api/v1/users

🔗 URL Parameters

GET /api/v1/params/path/{id}

GET /api/v1/params/query

GET /api/v1/params/query/paginated

GET /api/v1/params/query/all

📋 HTTP Headers

GET /api/v1/headers/single

GET /api/v1/headers/multiple

GET /api/v1/headers/all

POST /api/v1/headers/response

❤️ Health Check

GET /api/v1/health

💡 Exemplos de Uso

🔧 Usando cURL

Criar Usuário

Buscar por ID

Busca com Query Params

Enviar Header Customizado

📮 Usando Postman

🐍 Usando Python (requests)

☕ Usando Java (RestTemplate)

✅ Validações Implementadas

📋 Validações de Body Parameters

🔗 Validações de URL Parameters

📋 Validações de Headers

📝 Exemplo de Erro de Validação

🛡️ Tratamento de Erros

🎯 Tipos de Erros Tratados

1. Erro de Validação (400 Bad Request)

2. Erro de Tipo Incorreto (400 Bad Request)

3. Header Obrigatório Ausente (400 Bad Request)

4. Erro Interno do Servidor (500 Internal Server Error)

📊 Status HTTP Utilizados

📐 Padrões e Boas Práticas

🎯 Clean Code Principles

POST `/api/v1/users`

PUT `/api/v1/users`

GET `/api/v1/params/path/{id}`

GET `/api/v1/params/query`

GET `/api/v1/params/query/paginated`

GET `/api/v1/params/query/all`

GET `/api/v1/headers/single`

GET `/api/v1/headers/multiple`

GET `/api/v1/headers/all`

POST `/api/v1/headers/response`

GET `/api/v1/health`

Packages