@Controller, @RestController
Spring에서 클래스에 컨트롤러를 지정해주기 위한 어노테이션은 @Controller와 @RestController가 있습니다. 둘의 가장 큰 차이는 메서드의 반환값을 어떻게 응답으로 처리하느냐입니다. @RestController는 @Controller + @ResponseBody 조합이라고 할 수 있습니다.
아래 예제는 Spring MVC의 Servlet 환경을 기준으로 작성했습니다. spring-boot-starter-web처럼 Spring Web와 JSON 변환기가 구성된 프로젝트에서 각 클래스를 별도 파일로 만들고, 컴포넌트 스캔 범위 안에 두면 됩니다. 응답 처리의 차이에 집중하려고 DB 조회와 서비스 계층은 생략하고, 전달받은 id를 그대로 돌려주도록 했습니다.
@Controller
전통적인 Spring MVC의 컨트롤러 어노테이션인 @Controller는 주로 View를 반환하기 위해 사용합니다.
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class ViewController {
@GetMapping("/test")
public String test() {
return "test";
}
}
이때 "test"는 응답 본문의 문자열이 아니라 View 이름입니다. 예를 들어 Thymeleaf를 사용한다면 의존성과 함께 src/main/resources/templates/test.html을 준비해야 실제 화면이 나옵니다. 템플릿을 준비하지 않은 상태에서 이 경로를 호출하면 View를 찾지 못할 수 있습니다.
아래 과정을 통해서 Spring MVC Container는 Client 요청으로부터 View를 반환합니다.
본문 이미지원본 이미지를 불러올 수 없어요.
과정
Client는 URL 형식으로 요청을 보낸다.DispatcherServlet이 요청을 위임할Handler Mapping을 찾는다.DispatcherServlet은HandlerAdapter를 통해 해당Controller메서드를 실행한다.Controller는 요청을 처리한 후"test"와 같은 View 이름을 반환한다.- 반환값과 모델 정보가
DispatcherServlet으로 전달된다. DispatcherServlet은ViewResolver로 View를 찾고, View가 렌더링한 결과를Client에게 보낸다.
위 과정을 거치면서 View를 찾아서 렌더링 하는 과정을 거치게 됩니다.
하지만 Spring을 사용하다보면 화면 대신 Data를 반환해야하는 경우가 있을 텐데, 이때 @ResponseBody 어노테이션을 활용해서 반환값을 응답 본문에 쓸 수 있습니다. JSON 변환기가 설정되어 있고 JSON 응답으로 협상되면 객체를 JSON으로 반환합니다.
본문 이미지원본 이미지를 불러올 수 없어요.
과정
Client는 URL 형식으로 요청을 보낸다.DispatcherServlet이 요청을 위임할Handler Mapping을 찾는다.DispatcherServlet은HandlerAdapter를 통해 해당Controller메서드를 실행한다.Controller는 요청을 처리한 후 객체를 반환한다.- 반환되는 객체는 JSON으로 직렬화되어서
Client에게 반환된다.
@ResponseBody가 붙은 반환값은 ViewResolver로 View를 찾는 대신 HttpMessageConverter를 통해 응답 본문으로 변환됩니다. 응답 상태와 헤더도 함께 정하고 싶다면 ResponseEntity를 사용할 수 있습니다.
HttpMessageConverter에는 여러 Converter가 등록되어 있고, 반환하는 데이터에 따라 사용되는 Converter가 달라집니다.
예를 들어 문자열 응답에는 StringHttpMessageConverter가 사용될 수 있고, Spring 6.2의 Jackson 2 구성에서 객체를 JSON으로 응답할 때는 MappingJackson2HttpMessageConverter가 사용됩니다. 데이터의 종류와 설정에 따라 서로 다른 변환기가 작동하게 됩니다.
Spring은 반환값의 타입과 등록된 변환기, 요청의 Accept 헤더, 매핑의 produces 설정 등을 보고 응답 형식과 적합한 HttpMessageConverter를 선택합니다. 때문에 @ResponseBody가 붙었다고 무조건 JSON이 되는 것은 아닙니다.
요청 본문을 @RequestBody로 읽을 때는 요청 메시지를 객체로, @ResponseBody로 응답할 때는 반환값을 응답 메시지로 변환합니다. 지금 예제의 @RequestParam("id")는 요청 본문이 아니라 쿼리 파라미터를 읽습니다.
import java.util.Collections;
import java.util.Map;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
@Controller
public class MemberController {
@GetMapping("/api/controller/member")
@ResponseBody
public Map<String, String> findMember(@RequestParam("id") String id) {
return Collections.singletonMap("id", id);
}
}
위 코드에서 findMember()는 id를 담은 Map을 그대로 반환합니다. @ResponseBody가 있어서 View 이름으로 해석하지 않고, JSON 변환기가 이 값을 응답 본문에 씁니다. 별도의 Member 클래스나 Lombok 설정 없이 응답 처리만 확인할 수 있습니다.
저는 화면을 반환하는 Controller와 데이터를 반환하는 Controller를 분리하면 각 클래스의 역할을 더 쉽게 읽을 수 있다고 생각합니다.
@RestController
@RestController 어노테이션은 Restful Web Service에서 사용되는 컨트롤러 어노테이션입니다.
@Controller + @ResponseBody가 합쳐진 형태라서, 클래스 안의 매핑 메서드에 @ResponseBody를 하나씩 붙이지 않아도 반환값을 응답 본문으로 처리합니다.
import java.util.Collections;
import java.util.Map;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class MemberRestController {
@GetMapping("/api/rest/member")
public Map<String, String> findMember(@RequestParam("id") String id) {
return Collections.singletonMap("id", id);
}
@GetMapping("/api/rest/member-response")
public ResponseEntity<Map<String, String>> findMemberResponseEntity(
@RequestParam("id") String id) {
if (id.trim().isEmpty()) {
return ResponseEntity.badRequest().build();
}
return ResponseEntity.ok(Collections.singletonMap("id", id));
}
}
findMember()는 Map을 그대로 반환하고, 정상 처리되면 기본적으로 200 OK로 응답합니다. findMemberResponseEntity()는 빈 id가 들어오면 400 Bad Request, 값이 있으면 200 OK를 반환하도록 분기했습니다. 두 메서드는 같은 프로젝트에서 함께 등록할 수 있도록 서로 다른 경로를 사용합니다.
객체를 직접 반환해도 @ResponseStatus로 고정 상태 코드를 지정할 수 있습니다. 따라서 상태 코드를 설정하려면 무조건 ResponseEntity로 감싸야 하는 것은 아닙니다. 실행 결과에 따라 상태와 헤더, 본문을 함께 제어하고 싶을 때 ResponseEntity가 편리합니다. 또 ResponseEntity는 반환 타입 자체가 응답 처리를 지정하므로 @Controller 안에서도 @ResponseBody 없이 사용할 수 있습니다.
서버를 기본 포트인 8080에서 실행했다면 아래처럼 비교할 수 있습니다.
curl -i -H 'Accept: application/json' 'http://localhost:8080/api/controller/member?id=junha'
curl -i -H 'Accept: application/json' 'http://localhost:8080/api/rest/member?id=junha'
curl -i -H 'Accept: application/json' 'http://localhost:8080/api/rest/member-response?id=junha'
curl -i -H 'Accept: application/json' 'http://localhost:8080/api/rest/member-response?id='
앞의 세 요청은 200 OK와 {"id":"junha"}를, 마지막 요청은 본문 없는 400 Bad Request를 기대합니다. id 파라미터를 아예 생략하면 @RequestParam의 기본 설정인 required = true에 따라 400으로 처리됩니다.
결론
@Controller와 @RestController의 차이점은 용도의 차이라고 말할 수 있다고 생각합니다.
@Controller 어노테이션은 공식적으로 Spring 2.5버전에서 추가되었고, @RestController는 Spring 4.0 버전에 추가되었습니다.
과거에는 JSP, HTML과 같은 view를 전달해 주었기에 주로 @Controller를 사용하였고, 최근에는 Frontend와 Backend가 나누어져서 개발하는 경우가 많기 때문에 @RestController를 사용합니다.
중요한 것은 최신 어노테이션을 고르는 것이 아니라, 이 메서드가 화면을 반환하는지 데이터를 반환하는지 드러내는 것이라고 생각합니다.
참고한 공식 문서
2026년 11월 4일에 Spring Framework 6.2 공식 문서와 예제의 응답 처리 방식을 대조했습니다.
댓글 · 감정
한마디 남겨주세요 — GitHub 로그인이 필요해요.