19 de agosto de 2026 • Java

00 - Guia de Anotações do Spring Boot

Visão Geral

Spring Boot usa anotações extensivamente para configurar componentes, definir endpoints HTTP, injetar dependências, validar dados, gerenciar transações e controlar o comportamento da aplicação.

Anotações reduzem o código boilerplate e permitem aos desenvolvedores configurar a aplicação de forma declarativa.

Este guia cobre as anotações Spring Boot mais comuns usadas na construção de REST APIs.

Anotações da Camada Controller

`@Controller`

O que é?

@Controller marca uma classe como um controller Spring MVC.

É usada principalmente em aplicações que retornam views como páginas HTML geradas por Thymeleaf ou JSP.

Exemplo

@Controller
public class EmployeeController {

    @GetMapping("/employees")
    public String employees(Model model) {

        model.addAttribute(
            "employees",
            employeeService.findAll()
        );

        return "employees";
    }
}

O valor de retorno:

return "employees";

é interpretado como um nome de view:

employees.html

Quando usar

Use @Controller para:

Aplicações renderizadas no lado do servidor
Aplicações Thymeleaf
Aplicações JSP
Aplicações MVC tradicionais

Vantagens

Boa integração com a renderização no lado do servidor
Clara separação entre a camada de controller e de apresentação
Útil quando o backend gera páginas HTML

Desvantagens

Não é ideal para REST APIs
Requer configuração adicional para retornar JSON
Menos comum em arquiteturas modernas com frontend/backend separados

`@RestController`

O que é?

@RestController é usado para criar REST APIs.

Ele converte automaticamente objetos Java em respostas HTTP, geralmente JSON.

Internamente:

@RestController = @Controller + @ResponseBody

Exemplo

@RestController
@RequestMapping("/api/employees")
public class EmployeeController {

    @GetMapping("/{id}")
    public Employee findById(
            @PathVariable Long id
    ) {
        return employeeService.findById(id);
    }
}

Resposta:

{
    "id": 1,
    "name": "John"
}

Quando usar

Use @RestController para:

REST APIs
Microsserviços
Backends de aplicações móveis
Integrações frontend
Serviços de backend

Vantagens

Serialização JSON automática
Menos código boilerplate
Abordagem padrão para APIs modernas
Fácil integração com aplicações frontend

Desvantagens

Não foi projetado para retornar páginas HTML
Exige que os clientes consumam respostas da API

Anotações de Mapeamento de Requisições

`@RequestMapping`

O que é?

@RequestMapping define o mapeamento de URL para controllers ou métodos.

Geralmente usado no nível da classe para definir um prefixo de API comum.

Exemplo

@RestController
@RequestMapping("/api/employees")
public class EmployeeController {

}

Todos os endpoints dentro deste controller começam com:

/api/employees

Por que usar?

Sem @RequestMapping:

@GetMapping("/{id}")

Cria:

GET /1

Com:

@RequestMapping("/api/employees")

Cria:

GET /api/employees/1

Vantagens

Organiza endpoints da API
Cria estruturas de URL consistentes
Evita caminhos duplicados
Melhora a legibilidade da API

Desvantagens

Muitos caminhos aninhados podem criar URLs longas

Exemplo:

/api/company/department/employees/active/list

Anotações de Métodos HTTP

Spring oferece versões especializadas de @RequestMapping.

Elas definem qual método HTTP deve ser aceito.

`@GetMapping`

Propósito

Usado para recuperar dados.

Exemplo:

@GetMapping("/{id}")
public Employee findById(
        @PathVariable Long id
) {
}

Requisição:

GET /employees/10

Casos de uso

Recuperar um recurso
Buscar dados
Obter informações

`@PostMapping`

Propósito

Usado para criar novos recursos.

Exemplo:

@PostMapping
public Employee create(
        @RequestBody Employee employee
) {
}

Requisição:

POST /employees

Corpo:

{
    "name": "Bruno",
    "department": "IT"
}

Casos de uso

Criar usuários
Criar pedidos
Enviar formulários

`@PutMapping`

Propósito

Usado para atualizações completas de recursos.

Exemplo:

@PutMapping("/{id}")
public Employee update(
        @PathVariable Long id,
        @RequestBody Employee employee
) {
}

Requisição:

PUT /employees/10

Casos de uso

Substituir um recurso existente completamente.

`@PatchMapping`

Propósito

Usado para atualizações parciais.

Exemplo:

@PatchMapping("/{id}")
public Employee updateEmail(
        @PathVariable Long id,
        @RequestBody EmailRequest request
) {
}

Apenas os campos alterados são enviados.

Vantagens

Envia apenas dados alterados
Mais eficiente para objetos grandes

Desvantagens

Requer implementação cuidadosa

`@DeleteMapping`

Propósito

Exclui recursos.

Exemplo:

@DeleteMapping("/{id}")
public void delete(
        @PathVariable Long id
) {
}

Requisição:

DELETE /employees/10

Anotações de Dados de Requisição

`@PathVariable`

O que é?

Extrai valores diretamente do caminho da URL.

Exemplo

@GetMapping("/employees/{id}")
public Employee find(
        @PathVariable Integer id
) {
}

Requisição:

GET /employees/10

Valor:

id = 10

Quando usar

Use ao identificar um recurso específico.

Exemplos:

GET /users/100
GET /orders/500
GET /products/20

Vantagens

URLs mais RESTful
Fácil de entender
Representa recursos claramente
Melhor comportamento de cache

Desvantagens

Menos flexível para filtragem
Pode se tornar complexo com muitos parâmetros

Exemplo:

/users/10/orders/20/products/30

`@RequestParam`

O que é?

Extrai parâmetros de consulta da URL.

Exemplo

@GetMapping("/employees")
public List<Employee> search(
        @RequestParam String department
) {

}

Requisição:

GET /employees?department=IT

Quando usar

Use para:

Filtragem
Busca
Paginação
Ordenação
Parâmetros opcionais

Exemplo:

GET /employees?department=IT&page=2&size=20

Vantagens

Muito flexível
Suporta valores opcionais
Perfeito para operações de busca

Desvantagens

URLs podem se tornar muito longas
Menos semântico para identificar recursos

`@RequestBody`

O que é?

Mapeia payloads de requisição JSON em objetos Java.

Exemplo

@PostMapping
public Employee create(
        @RequestBody Employee employee
) {
}

JSON:

{
    "name": "John",
    "role": "Developer"
}

Quando usar

Use ao receber objetos complexos.

Exemplos:

Criação de usuários
Atualização de perfis
Processamento de formulários

Vantagens

Design de API limpo
Suporta estruturas complexas
Abordagem REST padrão

Desvantagens

Requer payload JSON
Mais difícil de testar manualmente

Anotações de Injeção de Dependência

`@Autowired`

O que é?

Injeta dependências gerenciadas pelo Spring.

Exemplo:

@Autowired
private EmployeeService service;

Abordagem recomendada

Prefira a injeção por construtor:

private final EmployeeService service;

public EmployeeController(EmployeeService service){
    this.service = service;
}

Vantagens

Acoplamento frouxo
Teste unitário mais fácil
Dependências são explícitas

Desvantagens

A injeção de campo pode ocultar dependências.

Anotações de Componentes

`@Component`

Propósito

Bean Spring genérico.

Exemplo:

@Component
public class EmailValidator {

}

Usado para:

Classes utilitárias
Ajudantes (helpers)
Componentes genéricos gerenciados pelo Spring

`@Service`

Propósito

Representa a camada de lógica de negócios.

Exemplo:

@Service
public class EmployeeService {

}

Responsabilidades:

Regras de negócio
Lógica da aplicação
Processamento de dados

`@Repository`

Propósito

Representa a camada de persistência.

Exemplo:

@Repository
public interface EmployeeRepository {

}

Responsabilidades:

Comunicação com o banco de dados
Operações CRUD
Tradução de exceções

Arquitetura Comum de REST API com Spring Boot

Client
   |
   v
@RestController
   |
   v
@Service
   |
   v
@Repository
   |
   v
Database

Responsabilidades da Camada

Camada	Responsabilidade
Controller	Lidar com requisições e respostas HTTP
Service	Regras de negócio e lógica da aplicação
Repository	Comunicação com o banco de dados
Entity	Representação do banco de dados
DTO	Transferência de dados entre camadas

Melhores Práticas

Identificação de recursos

Use:

@PathVariable

Exemplo:

GET /employees/10

Filtragem e busca

Use:

@RequestParam

Exemplo:

GET /employees?department=IT

Envio de dados complexos

Use:

@RequestBody

Exemplo:

POST /employees

Corpo:

{
    "name": "Bruno"
}

Padrão de Controller de API

@RestController
@RequestMapping("/api/employees")
public class EmployeeController {

    @GetMapping("/{id}")
    public Employee findById(
            @PathVariable Long id
    ) {
    }


    @GetMapping
    public List<Employee> search(
            @RequestParam String department
    ) {
    }


    @PostMapping
    public Employee create(
            @RequestBody Employee employee
    ) {
    }
}

Resumo

Anotação	Propósito
`@RestController`	Cria REST APIs
`@Controller`	Cria controllers MVC
`@RequestMapping`	Define o caminho base da URL
`@GetMapping`	Endpoints HTTP GET
`@PostMapping`	Endpoints HTTP POST
`@PutMapping`	Endpoints HTTP PUT
`@PatchMapping`	Endpoints HTTP PATCH
`@DeleteMapping`	Endpoints HTTP DELETE
`@PathVariable`	Lê valores do caminho da URL
`@RequestParam`	Lê parâmetros de consulta
`@RequestBody`	Lê payload JSON
`@Service`	Lógica de negócios
`@Repository`	Camada de banco de dados
`@Component`	Bean Spring genérico
`@Autowired`	Injeção de dependência