# Instalar SDKMAN e JDK 21
curl -s "https://get.sdkman.io" | bash
sdk install java 21.0.3-tem
java -version   # Confirma: openjdk 21...

eduspring/
├── src/
│   ├── main/
│   │   ├── java/br/com/dfcode/eduspring/
│   │   │   └── EduspringApplication.java   ← ponto de entrada
│   │   └── resources/
│   │       ├── application.properties      ← configurações
│   │       └── static/                     ← arquivos estáticos
│   └── test/
│       └── java/br/com/dfcode/eduspring/   ← testes
└── pom.xml                                 ← dependências Maven

package br.com.dfcode.eduspring;

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

// @SpringBootApplication é um atalho para três anotações:
// @SpringBootConfiguration  → define esta classe como configuração
// @EnableAutoConfiguration  → ativa a mágica do auto-configure
// @ComponentScan            → escaneia beans no pacote atual e subpacotes
@SpringBootApplication
public class EduspringApplication {

    public static void main(String[] args) {
        // SpringApplication.run inicializa o container IoC,
        // aplica auto-configurações e sobe o servidor Tomcat embutido
        SpringApplication.run(EduspringApplication.class, args);
    }
}

public class MatriculaService {

    // Problema 1: instanciação manual — quem cria o Repository?
    // Problema 2: se AlunoRepository mudar o construtor, tudo quebra
    // Problema 3: impossível substituir por mock nos testes
    private AlunoRepository alunoRepository = new AlunoRepository();
    private CursoRepository cursoRepository = new CursoRepository();

    public void matricular(Long alunoId, Long cursoId) {
        Aluno aluno = alunoRepository.findById(alunoId);
        Curso curso = cursoRepository.findById(cursoId);
        // lógica de matrícula...
    }
}

package br.com.dfcode.eduspring.service;

import org.springframework.stereotype.Service;

// @Service marca esta classe como um bean gerenciado pelo Spring
// Semanticamente indica que contém regras de negócio
@Service
public class MatriculaService {

    private final AlunoRepository alunoRepository;
    private final CursoRepository cursoRepository;

    // Injeção por construtor: preferida!
    // - Imutável (campos final)
    // - Facilita testes (basta chamar new MatriculaService(mockRepo1, mockRepo2))
    // - Deixa dependências explícitas
    // Com Spring Boot 2.2+, @Autowired no construtor é opcional
    public MatriculaService(AlunoRepository alunoRepository,
                            CursoRepository cursoRepository) {
        this.alunoRepository = alunoRepository;
        this.cursoRepository = cursoRepository;
    }

    public void matricular(Long alunoId, Long cursoId) {
        // O Spring já injetou as dependências antes desta linha
        Aluno aluno = alunoRepository.findById(alunoId).orElseThrow();
        Curso curso  = cursoRepository.findById(cursoId).orElseThrow();
        // lógica de matrícula...
    }
}

package br.com.dfcode.eduspring.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

// @Configuration indica que esta classe declara beans
@Configuration
public class InfraConfig {

    // @Bean diz ao Spring: "chame este método e registre o retorno como bean"
    // Ideal para configurar objetos de bibliotecas externas
    @Bean
    public BCryptPasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(12); // fator de custo 12
    }
}

public interface RelatorioExporter { byte[] exportar(List<Matricula> dados); }

@Component("exporterCsv")
public class RelatorioExporterCsv implements RelatorioExporter { /* ... */ }

@Primary
@Component("exporterExcel")
public class RelatorioExporterExcel implements RelatorioExporter { /* ... */ }

@Service
public class RelatorioService {
    private final RelatorioExporter exporterPadrao; // Excel por causa de @Primary

    public RelatorioService(RelatorioExporter exporterPadrao) {
        this.exporterPadrao = exporterPadrao;
    }
}

@Service
public class IntegracaoLegadoService {
    private final RelatorioExporter csvExporter;

    public IntegracaoLegadoService(@Qualifier("exporterCsv") RelatorioExporter csvExporter) {
        this.csvExporter = csvExporter;
    }
}

import org.springframework.beans.factory.annotation.Qualifier;
import java.lang.annotation.*;

@Target({ElementType.FIELD, ElementType.PARAMETER, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public @interface CsvExporter { }

// Uso na implementação:
@Component
@CsvExporter
public class RelatorioExporterCsv implements RelatorioExporter { }

// Uso na injeção:
public IntegracaoLegadoService(@CsvExporter RelatorioExporter csv) { }

@Service
public class PipelineValidacaoAluno {

    private final List<ValidadorAluno> validadores;

    // Spring injeta TODOS os beans que implementam ValidadorAluno (opcional: @Order nos validadores)
    public PipelineValidacaoAluno(List<ValidadorAluno> validadores) {
        this.validadores = validadores;
    }

    public void validar(Aluno a) {
        validadores.forEach(v -> v.validar(a));
    }
}

package br.com.dfcode.eduspring.controller;

import br.com.dfcode.eduspring.dto.CursoRequest;
import br.com.dfcode.eduspring.dto.CursoResponse;
import br.com.dfcode.eduspring.service.CursoService;
import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.net.URI;
import java.util.List;

// @RestController = @Controller + @ResponseBody
// Todo retorno é serializado automaticamente para JSON
@RestController
// Prefixo de todas as rotas deste controller
@RequestMapping("/cursos")
public class CursoController {

    private final CursoService cursoService;

    public CursoController(CursoService cursoService) {
        this.cursoService = cursoService;
    }

    // GET /cursos → lista todos os cursos
    @GetMapping
    public List<CursoResponse> listar() {
        return cursoService.listarTodos();
    }

    // GET /cursos/1 → busca curso por ID
    // @PathVariable extrai o {id} da URL
    @GetMapping("/{id}")
    public CursoResponse buscarPorId(@PathVariable Long id) {
        return cursoService.buscarPorId(id);
    }

    // GET /cursos/buscar?nome=java → filtra por nome
    // @RequestParam lê o parâmetro de query string
    @GetMapping("/buscar")
    public List<CursoResponse> buscarPorNome(@RequestParam String nome) {
        return cursoService.buscarPorNome(nome);
    }

    // POST /cursos → cria novo curso
    // @RequestBody deserializa o JSON do body para CursoRequest
    @PostMapping
    public ResponseEntity<CursoResponse> criar(@Valid @RequestBody CursoRequest request) {
        CursoResponse criado = cursoService.criar(request);
        // Retorna 201 Created com Location header apontando para o novo recurso
        URI location = URI.create("/cursos/" + criado.id());
        return ResponseEntity.created(location).body(criado);
    }

    // PUT /cursos/1 → atualiza completamente o curso
    @PutMapping("/{id}")
    public CursoResponse atualizar(@PathVariable Long id,
                                   @Valid @RequestBody CursoRequest request) {
        return cursoService.atualizar(id, request);
    }

    // DELETE /cursos/1 → remove o curso
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> remover(@PathVariable Long id) {
        cursoService.remover(id);
        return ResponseEntity.noContent().build(); // 204 No Content
    }
}

package br.com.dfcode.eduspring.dto;

import jakarta.validation.constraints.*;

// Record Java (Java 16+): imutável, sem boilerplate, ideal para DTOs de entrada
public record CriarAlunoRequest(

    // Campo obrigatório, não pode ser vazio ou só espaços
    @NotBlank(message = "O nome é obrigatório")
    @Size(min = 2, max = 100, message = "Nome deve ter entre 2 e 100 caracteres")
    String nome,

    // Valida formato de e-mail
    @NotBlank(message = "O e-mail é obrigatório")
    @Email(message = "Formato de e-mail inválido")
    String email,

    // Matrícula deve ser positiva
    @NotNull(message = "A matrícula é obrigatória")
    @Positive(message = "A matrícula deve ser um número positivo")
    Integer matricula,

    // Idade entre 14 e 120 anos
    @Min(value = 14, message = "Idade mínima permitida é 14 anos")
    @Max(value = 120, message = "Idade máxima permitida é 120 anos")
    Integer idade
) {}

// @Valid ativa a validação do objeto anotado com Bean Validation
// Se a validação falhar, Spring lança MethodArgumentNotValidException
// antes mesmo de entrar no método — o código dentro nunca é executado
@PostMapping
public ResponseEntity<AlunoResponse> criar(@Valid @RequestBody CriarAlunoRequest request) {
    AlunoResponse criado = alunoService.criar(request);
    return ResponseEntity.status(HttpStatus.CREATED).body(criado);
}

package br.com.dfcode.eduspring.exception;

import org.springframework.http.*;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.*;
import java.util.*;

// @ControllerAdvice intercepta exceções de qualquer controller
@RestControllerAdvice
public class GlobalExceptionHandler {

    // Intercepta falhas de validação (@Valid)
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.UNPROCESSABLE_ENTITY)  // 422
    public Map<String, Object> handleValidationErrors(
            MethodArgumentNotValidException ex) {

        // Coleta todos os erros de campo
        List<Map<String, String>> erros = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(e -> Map.of(
                "campo", e.getField(),
                "mensagem", e.getDefaultMessage()
            ))
            .toList();

        return Map.of(
            "status", 422,
            "titulo", "Dados inválidos",
            "erros", erros
        );
    }

    // Intercepta recursos não encontrados (lançado nos services)
    @ExceptionHandler(RecursoNaoEncontradoException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)  // 404
    public Map<String, Object> handleNaoEncontrado(
            RecursoNaoEncontradoException ex) {
        return Map.of(
            "status", 404,
            "titulo", "Recurso não encontrado",
            "detalhe", ex.getMessage()
        );
    }
}

{
  "status": 422,
  "titulo": "Dados inválidos",
  "erros": [
    { "campo": "email", "mensagem": "Formato de e-mail inválido" },
    { "campo": "nome",  "mensagem": "O nome é obrigatório" }
  ]
}

import org.springframework.http.*;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.context.request.WebRequest;

import java.net.URI;
import java.util.LinkedHashMap;
import java.util.Map;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ProblemDetail> validacao(MethodArgumentNotValidException ex, WebRequest req) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
            HttpStatus.UNPROCESSABLE_ENTITY, "Um ou mais campos são inválidos");
        pd.setTitle("Dados inválidos");
        pd.setType(URI.create("https://api.eduspring.local/problems/validation-error"));
        pd.setInstance(URI.create(req.getDescription(false).replace("uri=", "")));

        Map<String, Object> props = new LinkedHashMap<>();
        props.put("erros", ex.getBindingResult().getFieldErrors().stream()
            .map(e -> Map.of("campo", e.getField(), "mensagem", e.getDefaultMessage()))
            .toList());
        pd.setProperties(props);
        return ResponseEntity.unprocessableEntity().body(pd);
    }

    @ExceptionHandler(RecursoNaoEncontradoException.class)
    public ProblemDetail naoEncontrado(RecursoNaoEncontradoException ex, WebRequest req) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        pd.setTitle("Recurso não encontrado");
        pd.setType(URI.create("https://api.eduspring.local/problems/not-found"));
        return pd;
    }
}

import org.springframework.http.*;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

import org.springframework.web.context.request.WebRequest;

@RestControllerAdvice
public class RestExceptionHandler extends ResponseEntityExceptionHandler {

    @Override
    protected ResponseEntity<Object> handleExceptionInternal(
            Exception ex, Object body, HttpHeaders headers, HttpStatusCode status, WebRequest req) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(status, ex.getMessage());
        pd.setTitle(ex.getClass().getSimpleName());
        return ResponseEntity.status(status).headers(headers).body(pd);
    }
}

import com.fasterxml.jackson.databind.exc.InvalidFormatException;
import org.springframework.http.converter.HttpMessageNotReadableException;

@ExceptionHandler(HttpMessageNotReadableException.class)
public ProblemDetail jsonInvalido(HttpMessageNotReadableException ex) {
    Throwable causa = ex.getMostSpecificCause();
    String detalhe = (causa instanceof InvalidFormatException ife)
        ? "Valor inválido para o campo '%s': '%s'".formatted(ife.getPathReference(), ife.getValue())
        : "Corpo da requisição não pôde ser lido";
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, detalhe);
    pd.setTitle("Payload inválido");
    return pd;
}

// 1. Definindo a anotação
@Documented
@Constraint(validatedBy = MatriculaUnicaValidator.class)
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface MatriculaUnica {
    String message() default "Matrícula já cadastrada";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

// 2. Implementando a lógica de validação
@Component
public class MatriculaUnicaValidator
        implements ConstraintValidator<MatriculaUnica, Integer> {

    private final AlunoRepository alunoRepository;

    public MatriculaUnicaValidator(AlunoRepository alunoRepository) {
        this.alunoRepository = alunoRepository;
    }

    @Override
    public boolean isValid(Integer matricula, ConstraintValidatorContext ctx) {
        if (matricula == null) return true; // deixa o @NotNull tratar
        // Retorna true se NÃO existir aluno com esta matrícula
        return !alunoRepository.existsByMatricula(matricula);
    }
}

// 200 OK com body
return ResponseEntity.ok(cursoResponse);

// 201 Created com Location header
URI location = URI.create("/cursos/" + curso.getId());
return ResponseEntity.created(location).body(cursoResponse);

// 204 No Content (sem body)
return ResponseEntity.noContent().build();

// 404 Not Found com mensagem
return ResponseEntity.notFound().build();

// Status customizado + headers
return ResponseEntity
    .status(HttpStatus.ACCEPTED)        // 202
    .header("X-Request-Id", requestId)
    .body(resultado);

package br.com.dfcode.eduspring.dto;

import com.fasterxml.jackson.annotation.JsonFormat;
import java.time.LocalDate;

// Record: construtor, getters, equals, hashCode e toString automáticos
public record CursoResponse(
    Long id,
    String nome,
    String descricao,
    Integer cargaHoraria,

    // @JsonFormat controla a serialização da data para o padrão ISO
    @JsonFormat(pattern = "dd/MM/yyyy")
    LocalDate dataInicio,

    Boolean ativo
) {
    // Método de fábrica estático: converte Entidade → DTO
    public static CursoResponse de(Curso curso) {
        return new CursoResponse(
            curso.getId(),
            curso.getNome(),
            curso.getDescricao(),
            curso.getCargaHoraria(),
            curso.getDataInicio(),
            curso.getAtivo()
        );
    }
}

// Exceção base para todas as regras de negócio
public class NegocioException extends RuntimeException {
    public NegocioException(String mensagem) { super(mensagem); }
}

// Lançada quando um recurso não é encontrado → mapeia para 404
public class RecursoNaoEncontradoException extends NegocioException {
    public RecursoNaoEncontradoException(String recurso, Long id) {
        super("%s com id %d não encontrado".formatted(recurso, id));
    }
}

// Lançada quando uma regra de negócio é violada → mapeia para 422
public class RegraVioladaException extends NegocioException {
    public RegraVioladaException(String mensagem) { super(mensagem); }
}

// Uso no service:
public CursoResponse buscarPorId(Long id) {
    return cursoRepository.findById(id)
        .map(CursoResponse::de)
        .orElseThrow(() -> new RecursoNaoEncontradoException("Curso", id));
}

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

@Operation(summary = "Cria um novo curso")
@ApiResponse(responseCode = "201", description = "Curso criado com sucesso")
@ApiResponse(responseCode = "422", description = "Dados inválidos")
@PostMapping
public ResponseEntity<CursoResponse> criar(@Valid @RequestBody CriarCursoRequest request) {
    // ...
}

@GetMapping(value = "/{id}", produces = { MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE })
public CursoResponse buscar(@PathVariable Long id) { ... }

@PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<CursoResponse> criar(@Valid @RequestBody CriarCursoRequest req) { ... }

<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-xml</artifactId>
</dependency>

import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonRootName;

@JsonRootName("curso") // nome do elemento raiz no XML
public record CursoResponse(
    Long id,
    String nome,
    @JsonProperty("desc") String descricao,
    @JsonIgnore Long versaoInterna // nunca serializa
) {}

// Coleções em XML: @JacksonXmlElementWrapper(name = "cursos") + @JacksonXmlProperty em listas
// (requer jackson-dataformat-xml e módulo com.fasterxml.jackson.dataformat.xml.annotation)

public record AtualizarCursoParcialRequest(
    @Size(max = 150) String nome,
    @Min(1) Integer cargaHoraria,
    Boolean ativo   // null = não alterar; false/true = atualizar
) {}

@PatchMapping("/{id}")
public CursoResponse patch(@PathVariable Long id,
        @Valid @RequestBody AtualizarCursoParcialRequest patch) {
    return cursoService.aplicarPatch(id, patch);
}

// No service: copiar apenas campos não-nulos para a entidade
public CursoResponse aplicarPatch(Long id, AtualizarCursoParcialRequest p) {
    Curso c = cursoRepository.findById(id).orElseThrow(...);
    if (p.nome() != null) c.setNome(p.nome());
    if (p.cargaHoraria() != null) c.setCargaHoraria(p.cargaHoraria());
    if (p.ativo() != null) c.setAtivo(p.ativo());
    return CursoResponse.de(cursoRepository.save(c));
}

public class Views {
    public static class Resumo {}
    public static class Detalhe extends Resumo {}
}

// Mesmo conceito do CursoResponse do projeto — aqui com visões para listagem vs detalhe
public record CursoJsonViewDto(
    @JsonView(Views.Resumo.class) Long id,
    @JsonView(Views.Resumo.class) String nome,
    @JsonView(Views.Detalhe.class) String descricaoCompleta,
    @JsonView(Views.Detalhe.class) Integer cargaHoraria
) {}

@GetMapping
@JsonView(Views.Resumo.class)
public List<CursoJsonViewDto> listar() { ... }

@GetMapping("/{id}")
@JsonView(Views.Detalhe.class)
public CursoJsonViewDto buscar(@PathVariable Long id) { ... }

import com.fasterxml.jackson.annotation.JsonFilter;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ser.impl.SimpleBeanPropertyFilter;
import com.fasterxml.jackson.databind.ser.impl.SimpleFilterProvider;

@JsonFilter("cursoFilter")
public record CursoFiltravel(Long id, String nome, String descricao, String codigoInterno) {}

// Em um @ControllerAdvice ou serviço: serializar só id e nome
SimpleFilterProvider fp = new SimpleFilterProvider()
    .addFilter("cursoFilter", SimpleBeanPropertyFilter.filterOutAllExcept("id", "nome"));
ObjectMapper om = new ObjectMapper().setFilterProvider(fp);

import org.modelmapper.ModelMapper;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ModelMapperConfig {
    @Bean
    public ModelMapper modelMapper() {
        ModelMapper mm = new ModelMapper();
        mm.getConfiguration().setAmbiguityIgnored(true);
        return mm;
    }
}

@Service
public class CursoService {
    private final ModelMapper modelMapper;

    public CursoResponse criar(CriarCursoRequest req) {
        Curso entidade = modelMapper.map(req, Curso.class);
        return CursoResponse.de(cursoRepository.save(entidade));
    }
}

import org.springframework.http.CacheControl;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.context.request.WebRequest;

import java.util.concurrent.TimeUnit;

@GetMapping("/{id}")
public ResponseEntity<CursoResponse> buscarComCache(@PathVariable Long id, WebRequest req) {
    CursoResponse body = cursoService.buscarPorId(id);
    String etag = "\"curso-" + id + "-v" + body.hashCode() + "\""; // produção: use version/timestamp do banco

    if (req.checkNotModified(etag)) {
        return ResponseEntity.status(HttpStatus.NOT_MODIFIED).build();
    }
    return ResponseEntity.ok()
        .eTag(etag)
        .cacheControl(CacheControl.maxAge(60, TimeUnit.SECONDS).cachePublic())
        .body(body);
}

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.filter.ShallowEtagHeaderFilter;

@Configuration
public class EtagFilterConfig {
    @Bean
    public ShallowEtagHeaderFilter shallowEtagHeaderFilter() {
        return new ShallowEtagHeaderFilter();
    }
}

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class CorsMvcConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
            .allowedOrigins("http://localhost:3000")
            .allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS")
            .allowedHeaders("*")
            .allowCredentials(true);
    }
}

const r = await fetch('http://localhost:8080/api/cursos', {
  headers: { 'Accept': 'application/json' }
});
const cursos = await r.json();

import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.MediaType;

List<CursoResponse> lista = restClient.get()
    .uri("/cursos")
    .accept(MediaType.APPLICATION_JSON)
    .retrieve()
    .body(new ParameterizedTypeReference<>() {});

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.4.4</version>
    <relativePath/>
  </parent>

  <groupId>br.com.dfcode</groupId>
  <artifactId>eduspring</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <name>EduSpring</name>
  <description>Gestão escolar — exemplo do ebook</description>

  <properties>
    <java.version>21</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

// Esta classe existe dentro do spring-boot-autoconfigure
// Você nunca escreve isso — é gerado pela infraestrutura do Boot
@Configuration
// Só configura se Tomcat estiver no classpath
@ConditionalOnClass(Tomcat.class)
// Só configura se NÃO existir um EmbeddedServletContainerFactory definido pelo usuário
@ConditionalOnMissingBean(EmbeddedServletContainerFactory.class)
public class EmbeddedTomcatAutoConfiguration {

    @Bean
    public TomcatEmbeddedServletContainerFactory tomcat() {
        return new TomcatEmbeddedServletContainerFactory();
    }
}

spring:
  application:
    name: eduspring

  datasource:
    url: jdbc:postgresql://localhost:5432/eduspring
    username: ${DB_USER:postgres}      # lê variável de ambiente, default: postgres
    password: ${DB_PASS:postgres}

  jpa:
    hibernate:
      ddl-auto: validate               # nunca use 'create' em produção!
    show-sql: false
    properties:
      hibernate:
        format_sql: true

server:
  port: 8080
  servlet:
    context-path: /api                 # prefixo global: /api/cursos, /api/alunos

# Configurações personalizadas da aplicação
app:
  upload:
    diretorio: ${UPLOAD_DIR:/tmp/eduspring/uploads}
    tamanho-maximo-mb: 5

spring.application.name=eduspring
spring.datasource.url=jdbc:postgresql://localhost:5432/eduspring
spring.datasource.username=${DB_USER:postgres}
spring.datasource.password=${DB_PASS:postgres}
server.port=8080

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;

@Service
public class MatriculaPolicyService {

    private final int diasPrazoPagamento;
    private final String ambiente;

    public MatriculaPolicyService(
            @Value("${app.matricula.dias-prazo-pagamento:5}") int diasPrazoPagamento,
            @Value("${spring.profiles.active:default}") String ambiente) {
        this.diasPrazoPagamento = diasPrazoPagamento;
        this.ambiente = ambiente;
    }
}

import jakarta.annotation.PostConstruct;
import jakarta.annotation.PreDestroy;
import org.springframework.beans.factory.DisposableBean;
import org.springframework.beans.factory.InitializingBean;
import org.springframework.stereotype.Component;

@Component
public class CacheWarmup implements InitializingBean, DisposableBean {

    @PostConstruct
    public void aposInjecao() {
        // roda depois do construtor e depois de todas as dependências injetadas
    }

    @Override
    public void afterPropertiesSet() {
        // alternativa “Spring clássica” ao @PostConstruct
    }

    @PreDestroy
    public void antesEncerrar() {
        // chamado no shutdown do contexto (exceto kill -9)
    }

    @Override
    public void destroy() {
        // alternativa a @PreDestroy
    }
}

@Bean(initMethod = "abrir", destroyMethod = "fechar")
public MeuClienteGrpc meuCliente() {
    return new MeuClienteGrpc();
}

package br.com.dfcode.eduspring.config;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.nio.file.Path;

// Mapeia automaticamente as propriedades app.upload.* para este objeto
// Vantagem: tipagem, validação e autocomplete na IDE
@Component
@ConfigurationProperties(prefix = "app.upload")
public class UploadProperties {

    private Path diretorio;
    private int tamanhoMaximoMb;

    // getters e setters obrigatórios (ou use Record com @ConfigurationProperties no construtor)
    public Path getDiretorio() { return diretorio; }
    public void setDiretorio(Path diretorio) { this.diretorio = diretorio; }
    public int getTamanhoMaximoMb() { return tamanhoMaximoMb; }
    public void setTamanhoMaximoMb(int t) { this.tamanhoMaximoMb = t; }
}

spring:
  datasource:
    url: jdbc:h2:mem:eduspring_dev     # banco em memória, zerado a cada restart
    driver-class-name: org.h2.Driver
  h2:
    console:
      enabled: true                    # acesso em /h2-console
  jpa:
    show-sql: true                     # loga todas as queries no console

logging:
  level:
    br.com.dfcode: DEBUG               # log detalhado do nosso código

spring:
  datasource:
    url: ${DATABASE_URL}               # obrigatório via variável de ambiente
    username: ${DATABASE_USER}
    password: ${DATABASE_PASSWORD}
    hikari:
      maximum-pool-size: 10
      minimum-idle: 5
  jpa:
    show-sql: false

logging:
  level:
    root: WARN
    br.com.dfcode: INFO

// Interface comum
public interface EmailService {
    void enviar(String destinatario, String assunto, String corpo);
}

// Implementação de desenvolvimento: apenas loga, não envia
@Service
@Profile("dev")  // só ativo com spring.profiles.active=dev
public class EmailServiceFake implements EmailService {
    private static final Logger log = LoggerFactory.getLogger(EmailServiceFake.class);

    @Override
    public void enviar(String dest, String assunto, String corpo) {
        log.info("[FAKE EMAIL] Para: {} | Assunto: {}", dest, assunto);
        // não envia nada — ideal para dev e testes
    }
}

// Implementação de produção: envia de verdade via JavaMail
@Service
@Profile("prod")  // só ativo em produção
public class EmailServiceSmtp implements EmailService {
    // implementação com JavaMailSender
}

# 1. No application.yml (padrão para desenvolvimento)
# spring.profiles.active=dev

# 2. Variável de ambiente (recomendado para produção)
export SPRING_PROFILES_ACTIVE=prod
java -jar eduspring.jar

# 3. Argumento na linha de comando
java -jar eduspring.jar --spring.profiles.active=prod

# 4. No Docker Compose
environment:
  - SPRING_PROFILES_ACTIVE=prod

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

management:
  endpoints:
    web:
      exposure:
        # Expõe apenas health e info publicamente
        # Em produção, nunca exponha 'env' ou 'beans' sem autenticação!
        include: health,info,metrics
  endpoint:
    health:
      show-details: when-authorized  # detalhes só para usuários autenticados

info:
  app:
    nome: EduSpring
    versao: "@project.version@"      # lido automaticamente do pom.xml
    ambiente: ${SPRING_PROFILES_ACTIVE:dev}

package br.com.dfcode.eduspring.health;

import org.springframework.boot.actuate.health.*;
import org.springframework.stereotype.Component;

// Implementar HealthIndicator adiciona uma verificação ao /actuator/health
@Component
public class CursosAtivosHealthIndicator implements HealthIndicator {

    private final CursoRepository cursoRepository;

    public CursosAtivosHealthIndicator(CursoRepository cursoRepository) {
        this.cursoRepository = cursoRepository;
    }

    @Override
    public Health health() {
        long cursosAtivos = cursoRepository.countByAtivoTrue();

        if (cursosAtivos == 0) {
            // DOWN indica que algo está errado que precisa de atenção
            return Health.down()
                .withDetail("motivo", "Nenhum curso ativo cadastrado")
                .withDetail("cursosAtivos", 0)
                .build();
        }

        return Health.up()
            .withDetail("cursosAtivos", cursosAtivos)
            .build();
    }
}

package br.com.dfcode.eduspring.model;

import jakarta.persistence.*;
import lombok.*;
import java.time.LocalDate;

// @Entity indica que esta classe é gerenciada pelo JPA
// Cada instância corresponde a uma linha na tabela
@Entity
// @Table define o nome da tabela no banco (opcional se igual ao nome da classe)
@Table(name = "alunos")
// Lombok gera getters, setters, equals, hashCode e toString
// Atenção: NÃO use @Data em entidades — causa problemas com lazy loading
@Getter @Setter
@NoArgsConstructor  // JPA exige construtor sem argumentos
@AllArgsConstructor
@Builder            // permite construção fluente: Aluno.builder().nome("...").build()
public class Aluno {

    @Id
    // IDENTITY delega a geração de ID para o banco (auto_increment / serial)
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // @Column permite customizar nome, tamanho, nullable
    @Column(nullable = false, length = 100)
    private String nome;

    @Column(nullable = false, unique = true, length = 150)
    private String email;

    @Column(nullable = false, unique = true)
    private Integer matricula;

    @Column(name = "data_nascimento")
    private LocalDate dataNascimento;

    @Column(nullable = false)
    private Boolean ativo = true;
}

spring:
  jpa:
    hibernate:
      # validate: valida o schema sem modificar — use em produção com Flyway
      # create-drop: recria o banco ao iniciar/parar — use apenas em testes
      # update: atualiza o schema — NUNCA use em produção
      ddl-auto: create-drop
    show-sql: true
    properties:
      hibernate:
        format_sql: true               # SQL formatado e legível no log
        use_sql_comments: true         # adiciona comentário com o tipo de operação

package br.com.dfcode.eduspring.repository;

import br.com.dfcode.eduspring.model.Curso;
import org.springframework.data.domain.*;
import org.springframework.data.jpa.repository.*;
import org.springframework.data.repository.query.Param;
import java.util.List;
import java.util.Optional;

// JpaRepository já inclui todos os métodos CRUD — sem código adicional
// Spring Data gera a implementação em runtime
public interface CursoRepository extends JpaRepository<Curso, Long> {

    // 1. Query Method por convenção de nome
    // Spring traduz para: SELECT * FROM cursos WHERE ativo = true
    List<Curso> findAllByAtivoTrue();

    // 2. Busca por nome contendo texto (case-insensitive)
    // Gera: WHERE LOWER(nome) LIKE LOWER('%?%')
    List<Curso> findByNomeContainingIgnoreCase(String nome);

    // 3. Múltiplos critérios
    Optional<Curso> findByNomeAndAtivoTrue(String nome);

    // 4. @Query com JPQL (orientado a objetos — usa nome da classe, não da tabela)
    @Query("SELECT c FROM Curso c WHERE c.cargaHoraria >= :minimo AND c.ativo = true")
    List<Curso> buscarComCargaMinima(@Param("minimo") Integer cargaMinima);

    // 5. @Query com SQL nativo (usa nome da tabela real)
    @Query(value = "SELECT * FROM cursos WHERE data_inicio = CURRENT_DATE", nativeQuery = true)
    List<Curso> buscarComInicioHoje();

    // 6. Paginação — Pageable permite page, size e sort na requisição
    Page<Curso> findByAtivoTrue(Pageable pageable);

    // 7. Projeção com interface — retorna apenas campos necessários
    List<CursoResumo> findAllProjectedBy();

    // 8. Contagem
    long countByAtivoTrue();

    // 9. Verificação de existência
    boolean existsByMatricula(Integer matricula);
}

// Interface de projeção — Spring gera a implementação automaticamente
interface CursoResumo {
    Long getId();
    String getNome();
    Integer getCargaHoraria();
}

// DTO como interface: getters devem bater com alias da query (case-sensitive no PostgreSQL com aspas)
public interface CursoMatriculaResumoDto {
    Long getCursoId();
    String getNomeCurso();
    Long getTotalMatriculas();
}

public interface RelatorioCursoRepository extends JpaRepository<Curso, Long> {

    // Os aliases (AS curso_id, nome_curso...) devem seguir o padrão JavaBean: cursoId -> getCursoId()
    @Query(value = """
        SELECT c.id AS curso_id,
               c.nome AS nome_curso,
               COUNT(m.id) AS total_matriculas
        FROM cursos c
        LEFT JOIN matriculas m ON m.curso_id = c.id
        WHERE c.ativo = true
        GROUP BY c.id, c.nome
        ORDER BY total_matriculas DESC
        """, nativeQuery = true)
    List<CursoMatriculaResumoDto> relatorioMatriculasPorCurso();
}

// Alternativa com Record + construtor (Spring Data 3.2+ / Hibernate 6):
// @Query(... nativeQuery = true)
// List<MeuRecord> buscar();  // colunas = parâmetros do record na mesma ordem

-- Exemplo: procedure que retorna quantidade de vagas disponíveis
CREATE OR REPLACE PROCEDURE sp_atualizar_vagas_curso(IN p_curso_id BIGINT)
LANGUAGE plpgsql AS $$
BEGIN
  UPDATE cursos SET vagas = vagas - 1 WHERE id = p_curso_id AND vagas > 0;
END;
$$;

// Na entidade Curso (opcional, para nome catalogado):
// @NamedStoredProcedureQuery(
//   name = "Curso.atualizarVagas",
//   procedureName = "sp_atualizar_vagas_curso",
//   parameters = @StoredProcedureParameter(name = "p_curso_id", type = Long.class, mode = ParameterMode.IN))

public interface CursoRepository extends JpaRepository<Curso, Long> {

    // Mapeia pelo nome do procedimento no banco
    @Procedure(procedureName = "sp_atualizar_vagas_curso")
    void atualizarVagasProcedure(@Param("p_curso_id") Long cursoId);

    // Para FUNCTION que retorna valor, use @Query com nativeQuery:
    // @Query(value = "SELECT fn_total_alunos_curso(:id)", nativeQuery = true)
    // Long totalAlunos(@Param("id") Long cursoId);
}

import org.hibernate.annotations.Immutable;
import jakarta.persistence.*;

@Entity
@Immutable                    // Hibernate: entidade somente leitura
@Table(name = "vw_curso_resumo")  // nome exato da VIEW no PostgreSQL
public class VwCursoResumo {

    @Id
    private Long cursoId;

    private String nome;
    private Long totalMatriculas;
    // getters ...
}

public interface VwCursoResumoRepository extends JpaRepository<VwCursoResumo, Long> {
    List<VwCursoResumo> findByTotalMatriculasGreaterThan(long minimo);
}

@Service
public class MatriculaService {

    // Propagation.REQUIRED é o default — não precisa anotar
    @Transactional
    public void matricular(Long alunoId, Long cursoId) {
        // tudo aqui roda na MESMA transação:
        // se qualquer save() falhar, TUDO faz rollback
        alunoRepository.findById(alunoId).orElseThrow();
        cursoRepository.findById(cursoId).orElseThrow();
        matriculaRepository.save(new Matricula(alunoId, cursoId));
    }
}

@Service
public class MatriculaService {

    private final MatriculaRepository matriculaRepository;
    private final CursoRepository cursoRepository;

    @Transactional
    public void matricularComReservaDeVaga(Long alunoId, Long cursoId) {
        Curso curso = cursoRepository.findByIdForUpdate(cursoId)
            .orElseThrow(() -> new RecursoNaoEncontradoException("Curso", cursoId));
        // decrementa vaga — ainda na mesma transação
        curso.decrementarVaga();
        cursoRepository.save(curso);

        matriculaRepository.save(new Matricula(alunoId, cursoId));

        // Qualquer RuntimeException após os saves: Hibernate/JPA marca a TX para rollback
        if (curso.getVagas() < 0) {
            throw new RegraVioladaException("Vagas inconsistentes — rollback de curso + matrícula");
        }
        // Se este throw ocorrer, NADA do método é commitado no banco.
    }
}

@Service
public class CursoService {

    // Por padrão, IOException NÃO daria rollback — rollbackFor corrige isso
    @Transactional(rollbackFor = Exception.class)
    public void importarCursosDeArquivo(Path arquivo) throws IOException {
        List<Curso> linhas = lerLinhas(arquivo);
        for (Curso c : linhas) {
            cursoRepository.save(c);
        }
        // Se IOException for lançada dentro do método, a transação inteira desfaz os saves
    }
}

import org.springframework.transaction.annotation.Transactional;
import org.springframework.transaction.interceptor.TransactionAspectSupport;

@Service
public class MatriculaService {

    @Transactional
    public void matricularComValidacaoExterna(Long alunoId, Long cursoId, boolean aprovadoPeloAntiFraude) {
        matriculaRepository.save(new Matricula(alunoId, cursoId));
        if (!aprovadoPeloAntiFraude) {
            // Marca a transação atual para rollback; ao sair do método, commit não ocorre
            TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();
            return;
        }
        // ... continua o fluxo feliz
    }
}

import org.springframework.stereotype.Component;
import org.springframework.transaction.support.TransactionTemplate;

/**
 * Fachada que concentra gravações de matrícula com transação explícita.
 * Útil quando a lógica não cabe em um único método @Transactional ou vem de código externo.
 */
@Component
public class MatriculaPersistenceFacade {

    private final TransactionTemplate transactionTemplate;
    private final MatriculaRepository matriculaRepository;
    private final CursoRepository cursoRepository;

    public MatriculaPersistenceFacade(
            TransactionTemplate transactionTemplate,
            MatriculaRepository matriculaRepository,
            CursoRepository cursoRepository) {
        this.transactionTemplate = transactionTemplate;
        this.matriculaRepository = matriculaRepository;
        this.cursoRepository = cursoRepository;
    }

    public Matricula salvarMatriculaComAtualizacaoDeVaga(Long alunoId, Long cursoId) {
        // execute abre TX, commita se o callback terminar sem rollback; senão rollback
        return transactionTemplate.execute(status -> {
            Curso curso = cursoRepository.findById(cursoId)
                .orElseThrow(() -> new RecursoNaoEncontradoException("Curso", cursoId));
            curso.decrementarVaga();
            cursoRepository.save(curso);
            return matriculaRepository.save(new Matricula(alunoId, cursoId));
        });
    }
}

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.transaction.support.TransactionTemplate;

@Configuration
public class TransactionConfig {

    @Bean
    public TransactionTemplate transactionTemplate(PlatformTransactionManager txManager) {
        return new TransactionTemplate(txManager);
    }
}

@Service
public class AuditoriaService {

    // Nova transação independente: commit mesmo se a transação "pai" der rollback
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void registrarTentativaFalha(String operacao, String detalhe) {
        logEventoRepository.save(new LogEvento(operacao, detalhe, Instant.now()));
    }
}

@Service
public class MatriculaService {
    private final AuditoriaService auditoria;

    @Transactional
    public void matricular(Long alunoId, Long cursoId) {
        try {
            // lógica principal...
        } catch (Exception e) {
            auditoria.registrarTentativaFalha("MATRICULA", e.getMessage());
            throw e; // rollback da transação principal, mas o log já foi commitado em REQUIRES_NEW
        }
    }
}

// No Controller: Spring MVC popula o Pageable automaticamente a partir dos query params
// GET /cursos?page=0&size=10&sort=nome,asc
@GetMapping
public Page<CursoResponse> listar(
        @RequestParam(defaultValue = "") String nome,
        Pageable pageable) {                    // injetado automaticamente pelo Spring MVC
    return cursoRepository
        .findByNomeContainingIgnoreCaseAndAtivoTrue(nome, pageable)
        .map(CursoResponse::de);              // transforma Page<Curso> em Page<CursoResponse>
}

// No Repository:
Page<Curso> findByNomeContainingIgnoreCaseAndAtivoTrue(String nome, Pageable pageable);

{
  "content": [ {"id":1,"nome":"Java Básico"}, ... ],
  "pageable": { "pageNumber": 0, "pageSize": 10 },
  "totalElements": 47,
  "totalPages": 5,
  "last": false,
  "first": true
}

@MappedSuperclass  // campos herdados pelas entidades filhas
@EntityListeners(AuditingEntityListener.class) // ativa a auditoria JPA
public abstract class EntidadeAuditavel {

    @CreatedDate
    @Column(updatable = false)
    private LocalDateTime criadoEm;

    @LastModifiedDate
    private LocalDateTime atualizadoEm;
}

// Entidade que herda auditoria
@Entity
public class Curso extends EntidadeAuditavel {
    // ... outros campos
}

// Habilitar no @SpringBootApplication
@SpringBootApplication
@EnableJpaAuditing  // ativa os listeners de auditoria
public class EduspringApplication { ... }

// pom.xml: adicionar spring-boot-starter-cache e com.github.ben-manes.caffeine:caffeine

@Service
public class CursoService {

    // @Cacheable: na primeira chamada busca no banco e armazena no cache
    // nas chamadas seguintes com mesmo 'id', retorna do cache sem ir ao banco
    @Cacheable(value = "cursos", key = "#id")
    public CursoResponse buscarPorId(Long id) {
        return cursoRepository.findById(id)
            .map(CursoResponse::de)
            .orElseThrow(() -> new RecursoNaoEncontradoException("Curso", id));
    }

    // @CacheEvict: limpa o cache quando o curso é atualizado
    @CacheEvict(value = "cursos", key = "#id")
    public CursoResponse atualizar(Long id, CriarCursoRequest request) {
        // ...
    }
}

// Desde o Spring 4.2 o evento pode ser qualquer POJO (não precisa estender ApplicationEvent)
public record MatriculaRealizadaEvent(Long matriculaId, String emailAluno, String nomeCurso) {}

@Service
public class MatriculaService {

    private final ApplicationEventPublisher eventPublisher;
    private final MatriculaRepository matriculaRepository;
    // ...

    @Transactional
    public MatriculaResponse matricular(Long alunoId, Long cursoId) {
        Matricula m = matriculaRepository.save(construirMatricula(alunoId, cursoId));
        String email = m.getAluno().getEmail();
        String nomeCurso = m.getCurso().getNome();

        // 1) Síncrono: listener roda ANTES do commit — use só para lógica que não depende do commit
        // 2) Para efeitos pós-commit (e-mail, fila externa), prefira @TransactionalEventListener(AFTER_COMMIT)
        eventPublisher.publishEvent(new MatriculaRealizadaEvent(m.getId(), email, nomeCurso));

        return MatriculaResponse.de(m);
    }
}

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
import java.util.concurrent.Executor;

@Configuration
@EnableAsync
public class AsyncConfig {

    @Bean(name = "eventTaskExecutor")
    public Executor eventTaskExecutor() {
        ThreadPoolTaskExecutor ex = new ThreadPoolTaskExecutor();
        ex.setCorePoolSize(2);
        ex.setMaxPoolSize(8);
        ex.setQueueCapacity(100);
        ex.setThreadNamePrefix("eventos-");
        ex.initialize();
        return ex;
    }
}

import org.springframework.context.event.EventListener;
import org.springframework.core.annotation.Order;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Component;
import org.springframework.transaction.event.TransactionPhase;
import org.springframework.transaction.event.TransactionalEventListener;

@Component
public class MatriculaEventListener {

    private final EmailService emailService;
    private final MatriculaRepository matriculaRepository;

    // Primeiro: validações baratas na mesma thread (antes ou depois do commit, conforme fase abaixo)
    @Order(1)
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void aposCommitEnviarEmail(MatriculaRealizadaEvent event) {
        // Só roda se a transação do matricular() tiver dado COMMIT — evita e-mail para linha que sofreu rollback
        emailService.enviarConfirmacao(event.emailAluno(), event.nomeCurso());
    }

    @Order(2)
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void aposCommitAuditoriaLeve(MatriculaRealizadaEvent event) {
        // Ex.: gravar em tabela de "eventos processados" — já enxerga dados commitados
    }

    @Async("eventTaskExecutor")
    @EventListener
    @Order(10)
    public void metricasAssincronas(MatriculaRealizadaEvent event) {
        // Roda em paralelo; não bloqueia a resposta HTTP (cuidado: pode executar antes do commit
        // se publicar o evento antes do fim da TX — por isso métricas às vezes combinam com AFTER_COMMIT)
    }

    // Estilo "clássico" ApplicationListener<T> — equivalente a @EventListener
    // @Component
    // public class MatriculaApplicationListener implements ApplicationListener<MatriculaRealizadaEvent> {
    //     public void onApplicationEvent(MatriculaRealizadaEvent e) { ... }
    // }
}

public record MatriculaRealizadaEvent(Long matriculaId, String emailAluno, String nomeCurso) {}

// No listener AFTER_COMMIT:
// var matricula = matriculaRepository.findById(event.matriculaId()).orElseThrow();
// — garante estado persistido e consistente

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

package br.com.dfcode.eduspring.aop;

import java.lang.annotation.*;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface AuditarRest {
    /** Nome lógico da operação (aparece nos logs) */
    String operacao();
}

package br.com.dfcode.eduspring.aop;

import org.aspectj.lang.JoinPoint;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.util.StopWatch;

import java.util.UUID;

@Aspect
@Component
public class RestAuditoriaAspect {

    private static final Logger log = LoggerFactory.getLogger(RestAuditoriaAspect.class);

    // Pointcut nomeado: qualquer método público em controllers do pacote
    @Pointcut("execution(public * br.com.dfcode.eduspring.controller..*(..))")
    public void controllersEduSpring() {}

    // Combina pacote + presença da anotação no método
    @Pointcut("controllersEduSpring() && @annotation(auditar)")
    public void metodosAuditados(AuditarRest auditar) {}

    @Around("metodosAuditados(auditar)")
    public Object auditarTempo(ProceedingJoinPoint pjp, AuditarRest auditar) throws Throwable {
        String traceId = UUID.randomUUID().toString();
        MDC.put("traceId", traceId);
        StopWatch sw = new StopWatch();
        sw.start();
        try {
            log.info("[REST] Início operacao={} metodo={}", auditar.operacao(), pjp.getSignature().toShortString());
            return pjp.proceed();
        } finally {
            sw.stop();
            log.info("[REST] Fim operacao={} tempoMs={}", auditar.operacao(), sw.getTotalTimeMillis());
            MDC.remove("traceId");
        }
    }

    // Só executa se o método retornou sem exceção — útil para registrar sucesso com retorno
    @AfterReturning(pointcut = "metodosAuditados(auditar)", returning = "retorno", argNames = "auditar,retorno")
    public void aposSucesso(AuditarRest auditar, Object retorno) {
        log.debug("[REST] Sucesso operacao={} tipoRetorno={}", auditar.operacao(),
            retorno != null ? retorno.getClass().getSimpleName() : "void");
    }

    @AfterThrowing(pointcut = "metodosAuditados(auditar)", throwing = "ex", argNames = "auditar,ex")
    public void aposErro(AuditarRest auditar, Throwable ex) {
        log.warn("[REST] Falha operacao={} excecao={}", auditar.operacao(), ex.getClass().getSimpleName(), ex);
    }
}

@RestController
@RequestMapping("/cursos")
public class CursoController {

    private final CursoService cursoService;

    @AuditarRest(operacao = "LISTAR_CURSOS")
    @GetMapping
    public List<CursoResponse> listar() {
        return cursoService.listarTodos();
    }

    @AuditarRest(operacao = "CRIAR_CURSO")
    @PostMapping
    public ResponseEntity<CursoResponse> criar(@Valid @RequestBody CriarCursoRequest req) {
        return ResponseEntity.status(HttpStatus.CREATED).body(cursoService.criar(req));
    }
}

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

@Aspect
@Component
public class ServiceMonitoringAspect {

    private static final Logger log = LoggerFactory.getLogger(ServiceMonitoringAspect.class);

    @Around("execution(* br.com.dfcode.eduspring.service..*.*(..))")
    public Object alertarLentidao(ProceedingJoinPoint pjp) throws Throwable {
        long inicio = System.currentTimeMillis();
        try {
            return pjp.proceed();
        } finally {
            long ms = System.currentTimeMillis() - inicio;
            if (ms > 500) {
                log.warn("LENTO {} demorou {} ms", pjp.getSignature().toShortString(), ms);
            }
        }
    }
}

@SpringBootApplication
@EnableAspectJAutoProxy(proxyTargetClass = true) // CGLIB: necessário quando o alvo não tem interface
public class EduspringApplication { ... }

package br.com.dfcode.eduspring.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            // APIs REST são stateless — não usamos sessão HTTP
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))

            // Desabilita CSRF: necessário para APIs stateless com JWT
            // (CSRF protege sessões com cookies — não se aplica a Bearer tokens)
            .csrf(csrf -> csrf.disable())

            // Define quem pode acessar o quê
            .authorizeHttpRequests(auth -> auth
                // Endpoints públicos: documentação e autenticação
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
                .requestMatchers("/actuator/health", "/actuator/info").permitAll()
                .requestMatchers(HttpMethod.POST, "/auth/login", "/auth/registrar").permitAll()

                // Leitura pública de cursos
                .requestMatchers(HttpMethod.GET, "/cursos/**").permitAll()

                // Todo o resto exige autenticação
                .anyRequest().authenticated()
            )

            // Retorna JSON em vez de redirect para login page
            .exceptionHandling(ex -> ex
                .authenticationEntryPoint((req, res, e) -> {
                    res.setContentType("application/json");
                    res.setStatus(401);
                    res.getWriter().write("{\"erro\":\"Token ausente ou inválido\"}");
                })
                .accessDeniedHandler((req, res, e) -> {
                    res.setContentType("application/json");
                    res.setStatus(403);
                    res.getWriter().write("{\"erro\":\"Acesso negado\"}");
                })
            );

        return http.build();
    }
}

@Bean
public PasswordEncoder passwordEncoder() {
    // BCrypt gera um salt aleatório a cada hash — mesma senha = hash diferente
    // Fator 12: ~250ms por hash — lento o suficiente para dificultar força bruta
    return new BCryptPasswordEncoder(12);
}

// Demonstração:
// encoder.encode("minhasenha") → "$2a$12$xyz..." (hash diferente a cada chamada)
// encoder.matches("minhasenha", hash) → true  (verifica sem saber a senha original)

@Entity
@Table(name = "usuarios")
@Getter @Setter @NoArgsConstructor
public class Usuario implements UserDetails {  // contrato do Spring Security

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String email;

    @Column(nullable = false)
    private String senha;  // armazenado como hash BCrypt

    @Enumerated(EnumType.STRING)
    @Column(nullable = false)
    private Role role;

    // UserDetails: retorna as authorities (roles) do usuário
    @Override
    public Collection<? extends GrantedAuthority> getAuthorities() {
        return List.of(new SimpleGrantedAuthority("ROLE_" + role.name()));
    }

    @Override public String getPassword() { return senha; }
    @Override public String getUsername() { return email; } // email como username
    @Override public boolean isAccountNonExpired() { return true; }
    @Override public boolean isAccountNonLocked() { return true; }
    @Override public boolean isCredentialsNonExpired() { return true; }
    @Override public boolean isEnabled() { return true; }
}

// Enum de roles
public enum Role { ADMIN, PROFESSOR, ALUNO }

// Repository
public interface UsuarioRepository extends JpaRepository<Usuario, Long> {
    Optional<Usuario> findByEmail(String email);
    boolean existsByEmail(String email);
}

// UserDetailsService: Spring Security chama loadUserByUsername ao autenticar
@Service
public class UsuarioDetailsServiceImpl implements UserDetailsService {

    private final UsuarioRepository usuarioRepository;

    public UsuarioDetailsServiceImpl(UsuarioRepository usuarioRepository) {
        this.usuarioRepository = usuarioRepository;
    }

    @Override
    public UserDetails loadUserByUsername(String email) throws UsernameNotFoundException {
        return usuarioRepository.findByEmail(email)
            .orElseThrow(() -> new UsernameNotFoundException("Usuário não encontrado: " + email));
    }
}

// Service de registro
@Service
public class AuthService {
    private final UsuarioRepository usuarioRepository;
    private final PasswordEncoder passwordEncoder;

    public void registrar(RegistrarRequest request) {
        if (usuarioRepository.existsByEmail(request.email())) {
            throw new RegraVioladaException("E-mail já cadastrado");
        }
        var usuario = new Usuario();
        usuario.setEmail(request.email());
        // SEMPRE hash antes de salvar — nunca salve a senha original
        usuario.setSenha(passwordEncoder.encode(request.senha()));
        usuario.setRole(Role.ALUNO);  // role padrão para novos usuários
        usuarioRepository.save(usuario);
    }
}

.authorizeHttpRequests(auth -> auth
    // Público: documentação e autenticação
    .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
    .requestMatchers(HttpMethod.POST, "/auth/**").permitAll()

    // Somente ADMIN pode criar, editar e remover cursos
    .requestMatchers(HttpMethod.POST,   "/cursos/**").hasRole("ADMIN")
    .requestMatchers(HttpMethod.PUT,    "/cursos/**").hasRole("ADMIN")
    .requestMatchers(HttpMethod.DELETE, "/cursos/**").hasRole("ADMIN")

    // ADMIN e PROFESSOR podem gerenciar matrículas
    .requestMatchers("/matriculas/**").hasAnyRole("ADMIN", "PROFESSOR")

    // Qualquer autenticado pode ler
    .requestMatchers(HttpMethod.GET, "/cursos/**").authenticated()

    // Tudo mais: autenticado
    .anyRequest().authenticated()
)

// Habilitar no SecurityConfig (ou na classe principal):
// @EnableMethodSecurity

@RestController
@RequestMapping("/matriculas")
public class MatriculaController {

    // Apenas ADMIN pode listar todas as matrículas
    @PreAuthorize("hasRole('ADMIN')")
    @GetMapping
    public List<MatriculaResponse> listarTodas() { ... }

    // ALUNO só pode ver suas próprias matrículas
    // #authentication é o objeto de autenticação atual
    // principal.username é o e-mail do usuário logado
    @PreAuthorize("hasRole('ADMIN') or #email == authentication.principal.username")
    @GetMapping("/aluno/{email}")
    public List<MatriculaResponse> listarDoAluno(@PathVariable String email) { ... }

    // ADMIN ou PROFESSOR podem criar matrículas
    @PreAuthorize("hasAnyRole('ADMIN', 'PROFESSOR')")
    @PostMapping
    public ResponseEntity<MatriculaResponse> criar(@Valid @RequestBody CriarMatriculaRequest req) { ... }
}

// HEADER: algoritmo de assinatura
{ "alg": "HS256", "typ": "JWT" }

// PAYLOAD: dados do usuário (claims)
{
  "sub": "usuario@email.com",
  "role": "ADMIN",
  "iat": 1704067200,   // issued at (emitido em)
  "exp": 1704153600    // expiration (expira em — 24h depois)
}

// SIGNATURE: HMACSHA256(base64(header) + "." + base64(payload), SECRET_KEY)
// Garante que o token não foi adulterado

<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>0.12.5</version>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-impl</artifactId>
    <version>0.12.5</version>
    <scope>runtime</scope>
</dependency>

@Service
public class JwtService {

    // Chave secreta — NUNCA no código-fonte; use variável de ambiente
    @Value("${app.jwt.secret}")
    private String secret;

    @Value("${app.jwt.expiracao-horas:24}")
    private Long expiracaoHoras;

    // Gera um token JWT para o usuário
    public String gerarToken(UserDetails usuario) {
        return Jwts.builder()
            .subject(usuario.getUsername())          // email como subject
            .claim("role", extrairRole(usuario))     // adiciona a role como claim
            .issuedAt(new Date())                    // momento de criação
            .expiration(calcularExpiracao())         // momento de expiração
            .signWith(chaveSecreta())                // assina com HMAC-SHA256
            .compact();
    }

    // Extrai o username (email) do token
    public String extrairUsername(String token) {
        return extrairClaim(token, Claims::getSubject);
    }

    // Verifica se o token é válido para o usuário
    public boolean isTokenValido(String token, UserDetails usuario) {
        String username = extrairUsername(token);
        return username.equals(usuario.getUsername()) && !isTokenExpirado(token);
    }

    private boolean isTokenExpirado(String token) {
        return extrairClaim(token, Claims::getExpiration).before(new Date());
    }

    private <T> T extrairClaim(String token, Function<Claims, T> resolver) {
        Claims claims = Jwts.parser()
            .verifyWith(chaveSecreta())
            .build()
            .parseSignedClaims(token)
            .getPayload();
        return resolver.apply(claims);
    }

    private SecretKey chaveSecreta() {
        byte[] keyBytes = Decoders.BASE64.decode(secret);
        return Keys.hmacShaKeyFor(keyBytes);
    }

    private Date calcularExpiracao() {
        long agora = System.currentTimeMillis();
        return new Date(agora + expiracaoHoras * 3600 * 1000);
    }

    private String extrairRole(UserDetails usuario) {
        return usuario.getAuthorities().stream()
            .findFirst()
            .map(GrantedAuthority::getAuthority)
            .orElse("");
    }
}

@Component
public class JwtAuthFilter extends OncePerRequestFilter {

    private final JwtService jwtService;
    private final UserDetailsService userDetailsService;

    // ... construtor

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {

        String authHeader = request.getHeader("Authorization");

        // Se não tem header Authorization ou não começa com "Bearer ", pula
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            filterChain.doFilter(request, response);
            return;
        }

        String token = authHeader.substring(7); // remove "Bearer "
        String username = jwtService.extrairUsername(token);

        // Só processa se tem username e contexto ainda não autenticado
        if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {
            UserDetails usuario = userDetailsService.loadUserByUsername(username);

            if (jwtService.isTokenValido(token, usuario)) {
                // Cria o objeto de autenticação e seta no contexto
                UsernamePasswordAuthenticationToken auth =
                    new UsernamePasswordAuthenticationToken(usuario, null, usuario.getAuthorities());
                auth.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
                SecurityContextHolder.getContext().setAuthentication(auth);
            }
        }

        filterChain.doFilter(request, response);  // continua a cadeia
    }
}

@ExtendWith(MockitoExtension.class)  // ativa Mockito — sem Spring Context
class MatriculaServiceTest {

    @Mock  // cria um mock (objeto falso) do repositório
    private MatriculaRepository matriculaRepository;

    @Mock
    private CursoRepository cursoRepository;

    @InjectMocks  // injeta os mocks no service
    private MatriculaService matriculaService;

    @Test
    @DisplayName("Deve lançar exceção ao tentar matricular em curso sem vagas")
    void deveRejeitarMatriculaEmCursoSemVagas() {
        // GIVEN: cenário inicial
        Curso cursoSemVagas = Curso.builder()
            .id(1L).nome("Java Avançado").vagas(0).ativo(true).build();

        // Configura o mock para retornar o curso quando chamado
        given(cursoRepository.findById(1L)).willReturn(Optional.of(cursoSemVagas));

        // WHEN + THEN: executa e verifica a exceção
        assertThatThrownBy(() -> matriculaService.matricular(10L, 1L))
            .isInstanceOf(RegraVioladaException.class)
            .hasMessageContaining("sem vagas");

        // Verifica que o repositório de matrículas NÃO foi chamado
        verify(matriculaRepository, never()).save(any());
    }

    @Test
    @DisplayName("Deve criar matrícula com sucesso quando há vagas")
    void deveCriarMatriculaComSucesso() {
        // GIVEN
        Aluno aluno = Aluno.builder().id(10L).nome("João").ativo(true).build();
        Curso curso  = Curso.builder().id(1L).nome("Java").vagas(30).ativo(true).build();

        given(cursoRepository.findById(1L)).willReturn(Optional.of(curso));
        given(matriculaRepository.existsByAlunoIdAndCursoId(10L, 1L)).willReturn(false);
        given(matriculaRepository.save(any())).willAnswer(inv -> inv.getArgument(0));

        // WHEN
        matriculaService.matricular(10L, 1L);

        // THEN: verifica que save foi chamado exatamente uma vez
        verify(matriculaRepository, times(1)).save(any(Matricula.class));
    }
}

// @WebMvcTest carrega apenas a camada web (controllers, filters, advice)
// É muito mais rápido que @SpringBootTest
@WebMvcTest(CursoController.class)
class CursoControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private ObjectMapper objectMapper;

    // @MockitoBean substitui o bean real por um mock no contexto Spring (Boot 3.4+)
    @MockitoBean
    private CursoService cursoService;

    @Test
    @DisplayName("GET /cursos deve retornar 200 com lista de cursos")
    void deveListarCursos() throws Exception {
        // GIVEN
        List<CursoResponse> cursos = List.of(
            new CursoResponse(1L, "Java Básico", "...", 40, null, true)
        );
        given(cursoService.listarTodos()).willReturn(cursos);

        // WHEN + THEN
        mockMvc.perform(get("/cursos")
                .contentType(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$", hasSize(1)))
            .andExpect(jsonPath("$[0].nome").value("Java Básico"));
    }

    @Test
    @DisplayName("POST /cursos com dados inválidos deve retornar 422")
    void deveRetornarErroValidacao() throws Exception {
        // Request com nome vazio
        String json = """{"nome": "", "cargaHoraria": 0}""";

        mockMvc.perform(post("/cursos")
                .contentType(MediaType.APPLICATION_JSON)
                .content(json))
            .andExpect(status().isUnprocessableEntity())
            .andExpect(jsonPath("$.erros").isArray());
    }
}

// @DataJpaTest configura apenas a camada JPA com banco H2 em memória
// Muito mais rápido que @SpringBootTest
@DataJpaTest
class CursoRepositoryTest {

    @Autowired
    private CursoRepository cursoRepository;

    @Autowired
    private TestEntityManager entityManager;

    @Test
    @DisplayName("Deve encontrar cursos ativos pelo nome (case insensitive)")
    void deveBuscarPorNomeIgnorandoCase() {
        // GIVEN: persiste dados de teste
        entityManager.persist(Curso.builder().nome("Java Básico").ativo(true).build());
        entityManager.persist(Curso.builder().nome("JAVA Avançado").ativo(true).build());
        entityManager.persist(Curso.builder().nome("Python").ativo(true).build());
        entityManager.flush();

        // WHEN
        List<Curso> resultado = cursoRepository.findByNomeContainingIgnoreCase("java");

        // THEN
        assertThat(resultado).hasSize(2);
        assertThat(resultado).extracting(Curso::getNome)
            .containsExactlyInAnyOrder("Java Básico", "JAVA Avançado");
    }
}

@PostMapping("/{id}/foto")
public ResponseEntity<String> uploadFoto(
        @PathVariable Long id,
        @RequestParam("arquivo") MultipartFile arquivo) {

    // Validações de segurança
    if (arquivo.isEmpty()) {
        throw new RegraVioladaException("Arquivo não pode ser vazio");
    }

    String tipoConteudo = arquivo.getContentType();
    if (!List.of("image/jpeg", "image/png", "image/webp").contains(tipoConteudo)) {
        throw new RegraVioladaException("Apenas imagens JPEG, PNG e WebP são aceitas");
    }

    if (arquivo.getSize() > 5 * 1024 * 1024) {  // 5MB
        throw new RegraVioladaException("Tamanho máximo: 5MB");
    }

    String urlFoto = uploadService.salvar(id, arquivo);
    return ResponseEntity.ok(urlFoto);
}

// application.yml
// spring.servlet.multipart.max-file-size=5MB
// spring.servlet.multipart.max-request-size=10MB

@Service
@Profile("prod")  // versão real só em produção
public class EmailServiceSmtp implements EmailService {

    private final JavaMailSender mailSender;

    public void enviarConfirmacaoMatricula(String destinatario, String nomeCurso) {
        SimpleMailMessage mensagem = new SimpleMailMessage();
        mensagem.setFrom("noreply@dfcode.com.br");
        mensagem.setTo(destinatario);
        mensagem.setSubject("Matrícula confirmada: " + nomeCurso);
        mensagem.setText("""
            Olá!

            Sua matrícula no curso "%s" foi confirmada com sucesso.
            Acesse a plataforma para começar seus estudos.

            Equipe EduSpring
            """.formatted(nomeCurso));

        mailSender.send(mensagem);
    }
}

// application-prod.yml
// spring.mail.host: smtp.gmail.com
// spring.mail.port: 587
// spring.mail.username: ${MAIL_USER}
// spring.mail.password: ${MAIL_PASS}
// spring.mail.properties.mail.smtp.auth: true
// spring.mail.properties.mail.smtp.starttls.enable: true

@Component
// @EnableScheduling deve estar na classe principal ou em uma @Configuration
public class RelatorioScheduler {

    private final MatriculaRepository matriculaRepository;
    private final EmailService emailService;

    // Executa todo dia às 8h (cron: segundo minuto hora diaDoMes mês diaDaSemana)
    @Scheduled(cron = "0 0 8 * * *")
    public void enviarRelatorioMatriculasDiario() {
        LocalDate ontem = LocalDate.now().minusDays(1);
        List<Matricula> novasMatriculas = matriculaRepository.findByDataMatricula(ontem);

        if (!novasMatriculas.isEmpty()) {
            log.info("Enviando relatório: {} novas matrículas ontem", novasMatriculas.size());
            emailService.enviarRelatorioProfessores(novasMatriculas);
        }
    }

    // Executa a cada 30 minutos
    @Scheduled(fixedRate = 30 * 60 * 1000)
    public void limparTokensExpirados() {
        int removidos = tokenRepository.deleteByExpiracaoAntesDe(LocalDateTime.now());
        log.debug("Tokens expirados removidos: {}", removidos);
    }
}

@Service
public class CursoClientRestTemplate {

    private final RestTemplate restTemplate;

    /** RestTemplateBuilder aplica timeouts e message converters do Spring Boot. */
    public CursoClientRestTemplate(RestTemplateBuilder builder,
                                   @Value("${servicos.cursos.url}") String baseUrl) {
        this.restTemplate = builder
            .rootUri(baseUrl)
            .setConnectTimeout(Duration.ofSeconds(2))
            .setReadTimeout(Duration.ofSeconds(3))
            .build();
    }

    public CursoResponse buscarCurso(Long id) {
        try {
            return restTemplate.getForObject("/cursos/{id}", CursoResponse.class, id);
        } catch (HttpClientErrorException.NotFound ex) {
            throw new RecursoNaoEncontradoException("Curso", id);
        }
    }

    public CursoResponse criarCurso(CriarCursoRequest request) {
        return restTemplate.postForObject("/cursos", request, CursoResponse.class);
    }
}

@Service
public class CursoClientService {

    private final RestClient restClient;

    public CursoClientService(RestClient.Builder builder,
                               @Value("${servicos.cursos.url}") String cursoServiceUrl) {
        this.restClient = builder
            .baseUrl(cursoServiceUrl)
            .defaultHeader("Content-Type", "application/json")
            .build();
    }

    // Busca um curso pelo ID no serviço externo
    public CursoResponse buscarCurso(Long id) {
        return restClient.get()
            .uri("/cursos/{id}", id)
            .retrieve()
            .onStatus(status -> status.value() == 404,
                (req, res) -> { throw new RecursoNaoEncontradoException("Curso", id); })
            .body(CursoResponse.class);
    }

    // POST para criar matrícula no serviço externo
    public MatriculaResponse criarMatricula(CriarMatriculaRequest request) {
        return restClient.post()
            .uri("/matriculas")
            .body(request)
            .retrieve()
            .body(MatriculaResponse.class);
    }
}

spring:
  http:
    client:
      connect-timeout: 2s
      read-timeout: 5s

@Service
public class CursoClientWebFlux {

    private final WebClient webClient;

    public CursoClientWebFlux(WebClient.Builder builder,
                               @Value("${servicos.cursos.url}") String url) {
        this.webClient = builder.baseUrl(url).build();
    }

    // Retorna Mono (0 ou 1 resultado) — não-bloqueante
    public Mono<CursoResponse> buscarCurso(Long id) {
        return webClient.get()
            .uri("/cursos/{id}", id)
            .retrieve()
            .bodyToMono(CursoResponse.class);
    }

    // Para usar de forma síncrona (aguarda o resultado):
    public CursoResponse buscarCursoSincrono(Long id) {
        return buscarCurso(id).block();  // bloqueia até receber a resposta
    }
}

// pom.xml: spring-cloud-starter-openfeign

// Habilitar na aplicação principal:
// @EnableFeignClients

// Com Feign, você só declara a interface — Spring gera a implementação
@FeignClient(name = "servico-cursos", url = "${servicos.cursos.url}")
public interface CursoFeignClient {

    // Mapeamento idêntico ao controller do serviço de cursos
    @GetMapping("/cursos/{id}")
    CursoResponse buscarCurso(@PathVariable Long id);

    @PostMapping("/cursos")
    CursoResponse criarCurso(@RequestBody CriarCursoRequest request);

    @GetMapping("/cursos")
    List<CursoResponse> listar(@RequestParam(defaultValue = "") String nome);
}

// Uso no Service — exatamente como um Repository local
@Service
public class MatriculaService {
    private final CursoFeignClient cursoClient;  // injetado normalmente

    public void matricular(Long alunoId, Long cursoId) {
        CursoResponse curso = cursoClient.buscarCurso(cursoId); // chamada HTTP transparente
        // ...
    }
}

<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-spring-boot3</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<!-- Opcional: expor métricas no formato Prometheus -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

spring:
  http:
    client:
      connect-timeout: 2s
      read-timeout: 3s

resilience4j:
  circuitbreaker:
    instances:
      servico-cursos:
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 20
        minimumNumberOfCalls: 10
        failureRateThreshold: 50
        slowCallDurationThreshold: 2s
        slowCallRateThreshold: 50
        waitDurationInOpenState: 30s
        permittedNumberOfCallsInHalfOpenState: 5
        registerHealthIndicator: true
  retry:
    instances:
      servico-cursos:
        maxAttempts: 3
        waitDuration: 400ms
        retryExceptions:
          - org.springframework.web.client.ResourceAccessException
          - java.io.IOException

management:
  endpoints:
    web:
      exposure:
        include: health,circuitbreakers,circuitbreakerevents,metrics,prometheus
  endpoint:
    health:
      show-details: when_authorized
  metrics:
    tags:
      application: eduspring-matriculas

services:
  cursos-api:
    build: ./servico-cursos
    ports: ["8081:8080"]

  matriculas-api:
    build: ./servico-matriculas
    ports: ["8082:8080"]
    environment:
      SERVICOS_CURSOS_URL: http://cursos-api:8080
    depends_on: [cursos-api]

resilience4j:
  bulkhead:
    instances:
      servico-cursos:
        maxConcurrentCalls: 8
        maxWaitDuration: 200ms

@Service
public class CursoClientService {

    private static final Logger log = LoggerFactory.getLogger(CursoClientService.class);
    private final RestClient restClient;

    public CursoClientService(RestClient.Builder builder,
                              @Value("${servicos.cursos.url}") String baseUrl) {
        this.restClient = builder.baseUrl(baseUrl).build();
    }

    @Bulkhead(name = "servico-cursos")
    @CircuitBreaker(name = "servico-cursos", fallbackMethod = "fallbackBuscarCurso")
    @Retry(name = "servico-cursos")
    public CursoResponse buscarCurso(Long id) {
        return restClient.get()
            .uri("/cursos/{id}", id)
            .retrieve()
            .body(CursoResponse.class);
    }

    public CursoResponse fallbackBuscarCurso(Long id, Throwable ex) {
        log.warn("Cursos indisponível id={} — fallback. Causa: {}", id, ex.toString());
        return new CursoResponse(id, "Curso temporariamente indisponível",
            "Tente novamente em instantes", 0, null, false);
    }

    @Bulkhead(name = "servico-cursos")
    @CircuitBreaker(name = "servico-cursos", fallbackMethod = "fallbackListarCursos")
    public List<CursoResponse> listarCursos() {
        return restClient.get()
            .uri("/cursos")
            .retrieve()
            .body(new ParameterizedTypeReference<>() {});
    }

    public List<CursoResponse> fallbackListarCursos(Throwable ex) {
        log.warn("Listagem de cursos em fallback: {}", ex.getMessage());
        return List.of();
    }
}

@Configuration
public class RabbitMQConfig {

    public static final String EXCHANGE = "eduspring.eventos";
    public static final String FILA_CONFIRMACAO = "matriculas.confirmacao";
    public static final String FILA_RELATORIO   = "matriculas.relatorio";
    public static final String FILA_DLQ         = "matriculas.dlq";
    public static final String ROUTING_KEY      = "matricula.criada";

    // Exchange do tipo Topic: roteamento por padrão de routing key
    @Bean
    public TopicExchange exchange() {
        return new TopicExchange(EXCHANGE, true, false);
        // durable=true: sobrevive ao restart do RabbitMQ
    }

    // Fila principal com Dead Letter Queue configurada
    @Bean
    public Queue filaPrincipal() {
        return QueueBuilder.durable(FILA_CONFIRMACAO)
            .withArgument("x-dead-letter-exchange", "")        // usa default exchange
            .withArgument("x-dead-letter-routing-key", FILA_DLQ) // redireciona para DLQ
            .build();
    }

    // Dead Letter Queue: armazena mensagens que falharam
    @Bean
    public Queue filaDlq() {
        return QueueBuilder.durable(FILA_DLQ).build();
    }

    // Binding: conecta o exchange à fila usando o routing key
    @Bean
    public Binding binding(Queue filaPrincipal, TopicExchange exchange) {
        return BindingBuilder.bind(filaPrincipal)
            .to(exchange)
            .with(ROUTING_KEY);
    }

    // Converte objetos Java para JSON automaticamente
    @Bean
    public MessageConverter messageConverter() {
        return new Jackson2JsonMessageConverter();
    }
}

@Service
public class MatriculaEventPublisher {

    private final RabbitTemplate rabbitTemplate;

    public MatriculaEventPublisher(RabbitTemplate rabbitTemplate) {
        this.rabbitTemplate = rabbitTemplate;
    }

    // Publica o evento após a matrícula ser salva no banco
    public void publicarMatriculaCriada(MatriculaResponse matricula) {
        MatriculaCriadaEvent evento = new MatriculaCriadaEvent(
            matricula.id(),
            matricula.alunoEmail(),
            matricula.cursoNome(),
            LocalDateTime.now()
        );

        // Envia para o exchange com o routing key
        // O RabbitMQ roteia para todas as filas com binding compatível
        rabbitTemplate.convertAndSend(
            RabbitMQConfig.EXCHANGE,
            RabbitMQConfig.ROUTING_KEY,
            evento
        );

        log.info("Evento publicado: MatriculaCriada para {}", matricula.alunoEmail());
    }
}

// DTO do evento — deve ser serializável para JSON
public record MatriculaCriadaEvent(
    Long matriculaId,
    String alunoEmail,
    String cursoNome,
    LocalDateTime ocorridoEm
) {}

@Component
public class NotificacaoConsumer {

    private final EmailService emailService;

    // @RabbitListener: fica "escutando" a fila e processa cada mensagem
    // acknowledge-mode: manual = confirma só após processar com sucesso
    @RabbitListener(queues = RabbitMQConfig.FILA_CONFIRMACAO,
                    ackMode = "MANUAL")
    public void processarMatriculaCriada(
            MatriculaCriadaEvent evento,
            Channel channel,
            @Header(AmqpHeaders.DELIVERY_TAG) long deliveryTag) {

        try {
            log.info("Processando matrícula: {} - {}", evento.alunoEmail(), evento.cursoNome());

            emailService.enviarConfirmacaoMatricula(evento.alunoEmail(), evento.cursoNome());

            // ACK: confirma que a mensagem foi processada — removida da fila
            channel.basicAck(deliveryTag, false);

        } catch (Exception e) {
            log.error("Erro ao processar evento de matrícula: {}", e.getMessage());
            try {
                // NACK: rejeita a mensagem — vai para a Dead Letter Queue
                // requeue=false: não volta para a fila principal
                channel.basicNack(deliveryTag, false, false);
            } catch (IOException ioEx) {
                log.error("Erro ao fazer NACK: {}", ioEx.getMessage());
            }
        }
    }
}

# Gera o fat JAR (inclui todas as dependências)
./mvnw clean package -DskipTests

# O JAR gerado em target/ é autossuficiente
java -jar target/eduspring-1.0.0.jar

# Com profile de produção e variáveis de ambiente
SPRING_PROFILES_ACTIVE=prod \
DB_USER=postgres \
DB_PASS=secret \
java -jar target/eduspring-1.0.0.jar

# STAGE 1: Build — usa imagem completa do Maven para compilar
FROM eclipse-temurin:21-jdk-alpine AS build
WORKDIR /app
# Copia pom.xml primeiro para aproveitar cache de dependências
COPY pom.xml .
RUN mvn dependency:go-offline -q
# Copia o código e compila
COPY src ./src
RUN mvn clean package -DskipTests -q

# STAGE 2: Runtime — usa imagem mínima apenas com JRE
# Resultado: imagem final ~150MB (vs 500MB+ com JDK completo)
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app

# Cria usuário não-root (boa prática de segurança)
RUN addgroup -S spring && adduser -S spring -G spring
USER spring

# Copia apenas o JAR do stage anterior
COPY --from=build /app/target/eduspring-*.jar app.jar

EXPOSE 8080

# Executa com opções de JVM otimizadas para container
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75.0", "-jar", "app.jar"]

services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      SPRING_PROFILES_ACTIVE: prod
      DB_USER: ${DB_USER:-postgres}
      DB_PASS: ${DB_PASS:-postgres}
      DATABASE_URL: jdbc:postgresql://postgres:5432/eduspring
      RABBITMQ_HOST: rabbitmq
      APP_JWT_SECRET: ${JWT_SECRET}
    depends_on:
      postgres:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: eduspring
      POSTGRES_USER: ${DB_USER:-postgres}
      POSTGRES_PASSWORD: ${DB_PASS:-postgres}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  rabbitmq:
    image: rabbitmq:3-management-alpine
    ports:
      - "15672:15672"    # UI apenas para desenvolvimento
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

# 1. Instale o Railway CLI
npm install -g @railway/cli

# 2. Login
railway login

# 3. Crie o projeto (na raiz do projeto)
railway init

# 4. Adicione serviços PostgreSQL e RabbitMQ no dashboard Railway

# 5. Configure variáveis de ambiente no dashboard:
# SPRING_PROFILES_ACTIVE = prod
# JWT_SECRET = (gere uma string aleatória segura)
# As variáveis de banco são injetadas automaticamente pelo Railway

# 6. Deploy!
railway up
# Railway detecta o Dockerfile e faz o build automaticamente

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@Service
public class CursoService {

    private static final Logger log = LoggerFactory.getLogger(CursoService.class);

    public Curso buscar(Long id) {
        log.debug("Buscando curso id={}", id);
        // ...
        log.info("Curso encontrado: {}", id);
        return curso;
    }
}

@Configuration
public class JvmExceptionLoggingConfig {

    private static final Logger log = LoggerFactory.getLogger(JvmExceptionLoggingConfig.class);

    @PostConstruct
    void registrarUncaught() {
        Thread.setDefaultUncaughtExceptionHandler((thread, ex) ->
            log.error("Exceção não tratada na thread {}", thread.getName(), ex));
    }
}

<configuration>
  <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
  <springProperty name="LOGGLY_TOKEN" source="loggly.token" />

  <appender name="LOGGLY" class="ch.qos.logback.core.ConsoleAppender">
    <!-- Em produção real: use appender HTTP ou logstash encoder apontando para
         https://logs-01.loggly.com/inputs/SEU_TOKEN/tag/http -->
    <encoder>
      <pattern>%d{ISO8601} %-5level [%thread] %logger - %msg%n</pattern>
    </encoder>
  </appender>

  <springProfile name="prod">
    <root level="INFO">
      <appender-ref ref="CONSOLE"/>
      <appender-ref ref="LOGGLY"/>
    </root>
  </springProfile>
</configuration>

# dev: verboso
logging:
  level:
    root: INFO
    com.dfcode.eduspring: DEBUG

---
# prod: só o necessário
logging:
  level:
    root: WARN
    com.dfcode.eduspring: INFO

@SpringBootApplication
@EnableScheduling
public class EduSpringApplication {
    public static void main(String[] args) {
        SpringApplication.run(EduSpringApplication.class, args);
    }
}

@Component
public class ManutencaoAgendada {

    private static final Logger log = LoggerFactory.getLogger(ManutencaoAgendada.class);
    private final TokenRepository tokenRepository;

    public ManutencaoAgendada(TokenRepository tokenRepository) {
        this.tokenRepository = tokenRepository;
    }

    /** Após cada término, aguarda 10 minutos. */
    @Scheduled(fixedDelay = 10, timeUnit = TimeUnit.MINUTES)
    public void limparTokensExpirados() {
        int n = tokenRepository.deleteExpiradosAntesDe(Instant.now());
        log.info("Tokens removidos: {}", n);
    }

    /** Métricas a cada minuto (relógio entre inícios). */
    @Scheduled(initialDelay = 30, fixedRate = 60, timeUnit = TimeUnit.SECONDS)
    public void publicarMetricasSinteticas() {
        // ex.: incrementar gauge ou enviar heartbeat
    }
}

@Component
public class RelatorioDiarioScheduler {

    @Scheduled(cron = "0 0 8 * * *", zone = "America/Sao_Paulo")
    public void enviarResumoMatriculas() {
        // monta relatório do dia anterior e envia e-mail (cap. 28)
    }
}

spring:
  mail:
    host: smtp.gmail.com
    port: 587
    username: ${MAIL_USER}
    password: ${MAIL_PASS}
    properties:
      mail.smtp.auth: true
      mail.smtp.starttls.enable: true

package br.com.dfcode.eduspring.config;

import org.springframework.cache.annotation.EnableCaching;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableCaching
public class CacheConfig { }

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-cache</artifactId>
</dependency>

import org.springframework.cache.annotation.*;

@Service
public class CursoService {

    @Cacheable(value = "cursos", key = "#id")
    public CursoDto buscarPorId(Long id) {
        return cursoRepository.findById(id).map(CursoDto::from).orElseThrow();
    }

    @CacheEvict(value = "cursos", key = "#dto.id")
    public CursoDto atualizar(CursoDto dto) {
        // 1) mapear dto -> entidade, salvar no repositório, 2) retornar DTO atualizado
        return dto;
    }
}

spring:
  data:
    redis:
      host: localhost
      port: 6379
  cache:
    type: redis
    redis:
      time-to-live: 600000
    cache-names: cursos, alunos