[JAVA] @RestController vs @Controller – Spring MVC에서의 차이 완전 정리

Spring Boot 또는 Spring MVC 기반 프로젝트를 하다 보면 @Controller와 @RestController 중 어떤 걸 써야 할지 혼란스러울 수 있습니다. 둘 다 웹 요청을 처리하는 데 사용되지만, 내부적으로 작동하는 방식은 분명한 차이가 있습니다. 그 차이를 명확하게 짚어보고, 언제 어떤 어노테이션을 사용해야 할지를 정리해보겠습니다.

 

1. @Controller란 무엇인가?

@Controller는 전통적인 Spring MVC에서 사용하는 어노테이션으로, HTML 기반의 View(ViewResolver)를 반환할 때 사용됩니다. 즉, JSP나 Thymeleaf와 같은 템플릿 엔진을 통해 사용자에게 UI를 제공할 때 주로 사용됩니다.

@Controller
public class PageController {

    @GetMapping("/hello")
    public String hello(Model model) {
        model.addAttribute("message", "Hello World");
        return "hello";  // hello.html 또는 hello.jsp 로 랜더링됨
    }
}

View의 이름을 문자열로 반환하고, Spring은 이를 ViewResolver를 통해 실제 뷰로 변환하여 클라이언트에 HTML을 렌더링합니다.

 

2. @RestController란 무엇인가?

@RestController는 RESTful API를 만들기 위해 도입된 어노테이션입니다. 내부적으로 @Controller + @ResponseBody가 결합된 형태입니다. 즉, 반환되는 값은 View가 아니라 JSON, XML, 문자열과 같은 HTTP 응답 Body로 직렬화됩니다.

@RestController
public class ApiController {

    @GetMapping("/api/hello")
    public Map<String, String> hello() {
        return Map.of("message", "Hello World");
    }
}

이 경우 반환된 Map은 Jackson 같은 메시지 컨버터에 의해 JSON으로 변환되어 응답됩니다.

 

3. 핵심 차이 정리

항목	@Controller	@RestController
기본 반환 방식	View 이름 (템플릿 엔진)	HTTP Body (JSON, XML 등)
주 사용 목적	웹 페이지 렌더링	REST API 응답
@ResponseBody 필요 여부	직접 지정 필요	자동 포함
템플릿 엔진 필요	예 (Thymeleaf, JSP 등)	아니오

 

4. 실무에서의 선택 기준

• 웹 페이지가 필요한 경우: @Controller를 사용하고 View를 반환
• 프론트엔드가 React, Vue 등 SPA이고, 백엔드는 API 서버인 경우: @RestController 사용
• API와 View를 혼합 사용해야 할 경우: @Controller를 기본으로 쓰고, 필요한 메서드에만 @ResponseBody 사용

 

5. 혼용은 가능할까?

물론입니다. 하나의 프로젝트 안에서 @Controller와 @RestController를 모두 사용하는 것은 전혀 문제되지 않습니다. 다만, 서로의 목적이 다르기 때문에 역할에 따라 명확하게 분리 해서 사용하는 것이 유지보수에 좋습니다.

 

마무리

Spring에서는 다양한 아키텍처에 맞춰 개발할 수 있도록 @Controller와 @RestController 두 가지 방식을 제공하고 있습니다. 프로젝트가 웹 페이지 중심인지, API 중심인지에 따라 적절한 선택을 하시기 바랍니다. 그것이야말로 구조적인 코드와 생산성 있는 개발을 위한 첫 걸음입니다.