Controller vs RestController no Spring Boot: Qual a Diferença?

Resposta rápida: se você está criando uma API REST no Spring Boot, use @RestController. O @Controller faz mais sentido quando a classe devolve páginas HTML, views ou telas renderizadas.

Na prática, a dúvida entre controller vs restcontroller spring boot aparece porque os dois parecem parecidos, mas o comportamento deles é diferente. E essa diferença muda totalmente o resultado da sua rota.

Antes de continuar

Se o seu foco for entender melhor como a API responde ao cliente, vale complementar com o guia de Status HTTP em API REST com Spring Boot: Guia Completo. Ele ajuda a fechar a parte de respostas, códigos HTTP e boas práticas.

O que é o @Controller no Spring Boot?

O @Controller é usado em aplicações web tradicionais, normalmente quando o objetivo é renderizar uma página. Ele faz parte do modelo MVC e costuma trabalhar com templates como Thymeleaf, JSP ou Freemarker.

Quando um método de um @Controller retorna uma string, o Spring interpreta esse retorno como o nome da view, e não como texto puro ou JSON.

@Controller
public class HomeController {

  @GetMapping("/")
  public String home() {
    return "index";
  }
}

No exemplo acima, o Spring vai procurar uma view chamada index. Isso é útil em uma aplicação que gera HTML no backend, mas não é o comportamento ideal para uma API REST.

O que é o @RestController no Spring Boot?

O @RestController foi criado para simplificar a criação de APIs REST. Ele junta duas anotações em uma só:

@Controller
@ResponseBody

Isso significa que o retorno dos métodos é enviado diretamente na resposta HTTP, geralmente em JSON, sem tentativa de renderizar uma view.

@RestController
@RequestMapping("/api/usuarios")
public class UsuarioController {

  @GetMapping
  public List<String> listarUsuarios() {
    return List.of("Ana", "Carlos", "João");
  }
}

Se você chamar essa rota, o cliente recebe os dados no corpo da resposta. Esse é o comportamento esperado em uma API REST.

Diferença entre Controller e RestController

Característica	@Controller	@RestController
Retorno padrão	View HTML	Dados na resposta HTTP
Uso principal	Aplicações MVC	APIs REST
Precisa de @ResponseBody?	Sim, se quiser retornar JSON/texto	Não
Mais comum em projetos modernos de API	Não	Sim

Exemplo real: quando o comportamento muda de verdade

Imagine dois cenários bem comuns:

1. Site com página inicial

Você quer mostrar uma tela com HTML. Nesse caso, @Controller faz sentido porque o retorno será uma view.

2. API para app mobile ou frontend React

Agora você quer entregar uma lista de usuários em JSON. Aqui o correto é usar @RestController, porque o cliente precisa dos dados, não de uma página.

Esse é o ponto central da comparação entre controller vs restcontroller spring boot: não é só uma diferença de anotação, é uma diferença de finalidade.

Quando usar Controller?

Use @Controller quando a sua aplicação precisa renderizar conteúdo visual, como:

páginas HTML;
telas com Thymeleaf;
fluxos MVC tradicionais;
formulários que retornam uma nova página.

Exemplo prático:

@Controller
public class ProdutoController {

  @GetMapping("/produtos")
  public String listarProdutos(Model model) {
    model.addAttribute("produtos", List.of("Notebook", "Mouse", "Teclado"));
    return "produtos";
  }
}

Aqui a classe prepara dados para uma view. Não é API REST.

Quando usar RestController?

Use @RestController quando o objetivo for expor dados para consumo externo, como:

frontend em React, Angular ou Vue;
aplicativo mobile;
integração entre serviços;
qualquer API REST em Spring Boot.

Exemplo prático:

@RestController
@RequestMapping("/api/produtos")
public class ProdutoRestController {

  @GetMapping
  public List<String> listarProdutos() {
    return List.of("Notebook", "Mouse", "Teclado");
  }
}

Esse formato é direto, simples e deixa claro que a rota responde dados, não HTML.

Bloco prático: como escolher sem errar

Uma forma rápida de decidir:

Se a rota devolve uma página, use @Controller;
Se a rota devolve JSON, use @RestController;
Se você está criando uma API, comece com @RestController por padrão;
Se precisar de HTML e API no mesmo projeto, separe os controladores por responsabilidade.

Isso evita mistura de papéis dentro da mesma classe e deixa o projeto mais fácil de manter.

Erro comum ao usar Controller e RestController

Erro comum: usar @Controller esperando que o método retorne JSON automaticamente.

Esse erro aparece bastante em quem está começando. O desenvolvedor cria um método assim:

@Controller
@RequestMapping("/api/usuarios")
public class UsuarioController {

  @GetMapping
  public List<String> listar() {
    return List.of("Ana", "Carlos");
  }
}

Mas, como a classe está anotada com @Controller, o Spring pode tentar interpretar a saída como view. O resultado normalmente não é o esperado para uma API.

Se a intenção é REST, troque para @RestController ou adicione @ResponseBody no método específico.

Controller vs RestController com ResponseEntity

Em APIs REST, é muito comum combinar @RestController com ResponseEntity no Spring Boot. Isso ajuda a controlar status HTTP, headers e corpo da resposta.

@RestController
@RequestMapping("/api/clientes")
public class ClienteController {

  @GetMapping("/{id}")
  public ResponseEntity<String> buscarPorId(@PathVariable Long id) {
    if (id == 1L) {
      return ResponseEntity.ok("Cliente encontrado");
    }

    return ResponseEntity.notFound().build();
  }
}

Esse tipo de abordagem é muito comum em APIs bem estruturadas, porque deixa a resposta explícita e ajuda no tratamento correto dos status HTTP em APIs REST com Spring Boot.

Resumo rápido da diferença

@Controller → foco em views e páginas HTML;
@RestController → foco em JSON e APIs REST;
Para APIs modernas, @RestController é a escolha mais natural;
Para aplicações web com templates, @Controller ainda é o caminho certo.

Perguntas frequentes sobre Controller e RestController

Posso usar @Controller em uma API REST?

Pode, mas não é a melhor escolha. Você precisaria usar @ResponseBody nos métodos que devem retornar dados. O @RestController já resolve isso de forma mais limpa.

@RestController funciona com ResponseEntity?

Sim. Na prática, essa é uma combinação muito usada em APIs REST no Spring Boot.

Qual devo usar em um projeto novo?

Se o projeto é uma API, use @RestController. Se o projeto renderiza páginas HTML, use @Controller.

O @RestController substitui totalmente o @Controller?

Não. Eles servem para contextos diferentes. O @Controller continua sendo útil em aplicações web com interface server-side.

Preciso configurar JSON manualmente com @RestController?

Não normalmente. O Spring Boot já faz isso por padrão com Jackson, desde que a dependência esteja disponível e a configuração esteja correta.

Conteúdos relacionados

Conclusão

A diferença entre controller vs restcontroller spring boot é simples quando você olha para o objetivo da rota: @Controller entrega views, enquanto @RestController entrega dados para consumo em API REST.

Se sua aplicação precisa expor endpoints JSON, o caminho mais direto e organizado é usar @RestController. Isso reduz configuração, deixa o código mais legível e evita erros comuns de retorno de view em lugar de dados.

Próximos passos: depois de entender essa diferença, aprofunde o estudo em ResponseEntity, status HTTP e tratamento de erros. Esses três pontos fazem sua API ficar muito mais profissional.

Leitura complementar

Se você quiser aprofundar esse assunto com um material mais atual, leia também Spring security cors csrf preflight aplicacao: evite erros em.

Controller vs RestController no Spring Boot: qual usar em APIs REST?