SpringBoot @RestController와 @Controller 차이 정리

SpringBoot를 활용한 웹 개발에서 가장 핵심적인 컴포넌트 중 하나는 Controller입니다.
이때 사용하는 어노테이션으로는 @Controller와 @RestController가 있으며,
초보자 입장에서는 두 어노테이션의 차이가 헷갈릴 수 있습니다.
이번 글에서는 SpringBoot에서 사용하는 @Controller와 @RestController의 차이점과 사용 목적을 명확히 정리해 드립니다.

1. 스프링 MVC에서 컨트롤러의 역할

Spring MVC는 사용자의 요청(Request)을 받아 적절한 비즈니스 로직을 수행한 후,
그 결과를 View 또는 JSON 형태로 응답(Response)하는 구조입니다.

이때 Controller는 요청을 받아 처리하는 중심부로서,
어노테이션을 통해 어떤 방식으로 응답을 리턴할지를 정의하게 됩니다.

2. @Controller의 기본 개념과 동작 방식

@Controller는 전통적인 MVC 패턴에서 사용되는 어노테이션입니다.

@Controller
public class PageController {
    @GetMapping("/home")
    public String home() {
        return "home"; // templates/home.html 반환
    }
}

ViewResolver를 통해 String 값을 HTML 템플릿으로 매핑
JSP, Thymeleaf와 같은 템플릿 엔진 기반의 뷰 반환에 사용
@ResponseBody를 함께 사용해야 JSON이나 텍스트 응답 가능

🔍 즉, 기본 동작은 "HTML View 반환"이며, JSON 반환을 원할 경우 별도로 설정이 필요합니다.

3. @RestController의 특징과 용도

@RestController는 @Controller + @ResponseBody의 조합입니다.

@RestController
public class ApiController {
    @GetMapping("/api/data")
    public Map<String, Object> getData() {
        return Map.of("status", "ok", "code", 200);
    }
}

HTTP Response Body에 JSON 형식으로 직접 반환
RESTful API 개발에 최적화된 어노테이션
ViewResolver가 아닌 HttpMessageConverter가 응답 처리 담당

✅ API 서버나 프론트엔드와의 통신(React, Vue 등)에서 주로 사용됩니다.

4. 두 어노테이션의 핵심 차이 비교

항목	@Controller	@RestController
반환 방식	View 이름 반환	JSON, XML 등 객체 반환
기본 응답	HTML 페이지	응답 본문(Response Body)
@ResponseBody 필요 여부	필요	불필요 (자동 포함)
사용 용도	템플릿 기반 웹 페이지	REST API 서버
구성 방식	단독 사용	@Controller + @ResponseBody 조합

📌 @RestController는 템플릿 렌더링이 아닌, 데이터만 반환해야 할 때 사용합니다.

5. 실무에서의 선택 기준과 팁

템플릿 기반 웹 페이지 제공: @Controller + Thymeleaf
JSON API 응답 (모바일/SPA 연동): @RestController
테스트 시에는 JSON 응답이 직관적이므로 @RestController가 편리함
필요 시 @Controller에도 특정 메서드만 @ResponseBody를 붙여 조합 가능

@Controller
public class MixedController {
    @GetMapping("/view")
    public String viewPage() {
        return "page";
    }

    @GetMapping("/json")
    @ResponseBody
    public String jsonData() {
        return "{\"status\":\"ok\"}";
    }
}

✅ 마무리

SpringBoot에서 @Controller와 @RestController는 역할과 반환 방식이 다르며,
애플리케이션의 목적에 따라 정확히 구분하여 사용하는 것이 중요합니다.
템플릿 기반 화면을 구성하려면 @Controller, JSON 기반 API를 제공하려면 @RestController를 사용해야 클린하고 유지보수 가능한 코드 구조를 만들 수 있습니다.

기록기록