@RestController와 @Controller의 차이점은 무엇인가요?

728x90

@RestController vs @Controller 완벽 비교! Spring 개발자라면 꼭 알아야 할 핵심 차이점

Spring MVC를 사용하다 보면 꼭 한번 마주치는 질문!

“@Controller랑 @RestController 도대체 뭐가 다른 거죠?”
“왜 어떤 프로젝트는 @RestController만 쓰고, 어떤 곳은 @Controller만 쓰죠?”
“둘 중 어떤 걸 언제 써야 할까요?”

이번 포스트에서는 이 둘의 차이점, 용도, 실전 예시를 통해 완벽하게 정리해드립니다.

1. @RestController와 @Controller란? 주요 개념과 특징

어노테이션	특징
@Controller	View를 반환하는 전통적인 웹 컨트롤러
@RestController	데이터(JSON/XML)를 반환하는 API 컨트롤러

@Controller: 전통적인 웹 MVC 방식

주로 JSP, Thymeleaf 등 HTML 페이지를 반환할 때 사용
메서드에서 String을 반환하면 View 이름으로 인식
필요한 경우 @ResponseBody를 붙여 JSON도 반환 가능

@Controller
public class PageController {

    @GetMapping("/home")
    public String homePage(Model model) {
        model.addAttribute("message", "Hello, Spring!");
        return "home"; // → /WEB-INF/views/home.jsp 렌더링
    }
}

@RestController: RESTful API 응답을 위한 컨트롤러

Spring 4.0부터 추가
내부적으로 @Controller + @ResponseBody 조합
View를 사용하지 않고 JSON/XML 등 객체 데이터를 바로 응답

@RestController
public class ApiController {

    @GetMapping("/api/hello")
    public String hello() {
        return "Hello, API!";
    }
}

🧠 @ResponseBody는 메서드의 리턴 값을 HTTP Response Body에 직접 넣어준다는 의미입니다.

🔍 비교 정리

항목	@Controller	@RestController
반환값 처리	View 이름으로 처리	HTTP Body에 그대로 반환
HTML 뷰 렌더링	가능	불가능 (데이터만 응답)
API 응답 (JSON 등)	@ResponseBody 필요	자동 처리 (@ResponseBody 포함)
주 사용처	웹 페이지 제공	REST API 서버 개발
Spring 버전	Spring MVC 초기부터	Spring 4.0 이상

2. 예시 및 코드 설명

예시 1: @Controller로 뷰 반환

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class PageController {
    @GetMapping("/home")
    public String home(Model model) {
        model.addAttribute("message", "Welcome to Spring MVC!");
        return "home"; // 뷰 이름 반환
    }
}

// home.jsp (/WEB-INF/views/home.jsp)
<%@ page language="java" contentType="text/html; charset=UTF-8" %>
<html>
<body>
    <h1><%= request.getAttribute("message") %></h1>
</body>
</html>

/home 요청 시 home 문자열을 반환.
ViewResolver가 /WEB-INF/views/home.jsp로 매핑해 렌더링.
결과: HTML 페이지 출력.

예시 2: @RestController로 데이터 반환

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ApiController {
    @GetMapping("/api/data")
    public String getData() {
        return "Hello from REST API!";
    }
}

/api/data 요청 시 "Hello from REST API!"가 JSON 문자열로 응답.
@ResponseBody가 포함되어 별도 뷰 없이 데이터 전송.

예시 3: @Controller에 @ResponseBody 추가

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseBody;

@Controller
public class MixedController {
    @GetMapping("/mixed/data")
    @ResponseBody
    public String getMixedData() {
        return "Data from Controller!";
    }
}

@ResponseBody로 메서드 단위에서 데이터 반환.
@RestController와 동일한 결과지만, 메서드별로 적용.

실행 결과 비교

GET /home: <h1>Welcome to Spring MVC!</h1> (HTML).
GET /api/data: "Hello from REST API!" (JSON).
GET /mixed/data: "Data from Controller!" (JSON).

3. 실무에서 활용 사례

사례 1: @Controller - 관리자 대시보드

@Controller
@RequestMapping("/admin")
public class AdminController {
    @GetMapping("/dashboard")
    public String dashboard(Model model) {
        model.addAttribute("stats", "주문 수: 100");
        return "dashboard"; // Thymeleaf 뷰
    }
}

활용 이유: 관리자 페이지처럼 뷰 렌더링이 필요한 경우 사용.

사례 2: @RestController - REST API

@RestController
@RequestMapping("/api/users")
public class UserApiController {
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return new User(id, "John Doe"); // JSON 반환
    }
}

활용 이유: 모바일 앱이나 프론트엔드(React, Vue)와 데이터 통신 시 사용.

4. 장단점 및 주의사항

@Controller

✅ 장점:
- 뷰 기반 웹 애플리케이션에 최적화.
- 유연성(메서드별 @ResponseBody로 데이터 반환 가능).
❌ 단점:
- API 응답 시 매번 @ResponseBody 추가 필요.
- 설정이 복잡할 수 있음(예: ViewResolver).

@RestController

✅ 장점:
- REST API 개발이 간편하고 직관적.
- 코드 간결성(별도 어노테이션 불필요).
❌ 단점:
- 뷰 반환 불가(API 전용).
- 혼합 사용 시 역할 혼동 가능.

주의사항

용도 혼동: @RestController를 뷰 반환에 사용하면 에러 발생.
- 해결책: 용도에 맞게 선택.
성능: 뷰 렌더링(@Controller)은 API 응답보다 느릴 수 있음.
- 해결책: API와 UI 분리 고려.

5. 결론: 언제 무엇을 써야 할까?

@Controller는 전통적인 웹 애플리케이션, @RestController는 RESTful API에 적합합니다. 프로젝트 요구사항에 따라 적절히 선택하면 효율적인 개발이 가능합니다.

웹 페이지를 반환하는 경우 👉 @Controller
JSON, XML 등 데이터만 반환하는 경우 👉 @RestController

✔ 최근에는 대부분 프론트엔드(Vue, React)와 분리된 백엔드 구조를 사용하기 때문에
@RestController 사용 빈도가 압도적으로 많아지고 있습니다.