스프링에서 @Controller와 @RestController를 언제 어떻게 구분할까
목차
빠른 답
- HTML 화면을 내려주면 보통 @Controller, JSON API를 만들면 보통 @RestController를 사용합니다.
- @RestController는 사실상 @Controller와 @ResponseBody를 함께 적용한 형태입니다.
- 문자열 반환값이 뷰 이름인지 응답 본문인지 헷갈릴 때는 어노테이션과 @ResponseBody 유무를 먼저 확인하면 됩니다.
- 응답 JSON 변환은 HttpMessageConverter가 담당하므로 헤더와 직렬화 설정도 함께 봐야 합니다.
빠른 답
- HTML 화면을 렌더링해 내려주면 보통
@Controller를, JSON 같은 API 응답을 내려주면 보통@RestController를 사용합니다. @RestController는 사실상@Controller와@ResponseBody를 합친 형태라서 반환값이 뷰 이름이 아니라 HTTP 응답 본문으로 처리됩니다.String을 반환했는데 동작이 기대와 다르면 먼저@ResponseBody유무와 클래스의 어노테이션 종류를 확인하면 됩니다.- JSON 응답은
HttpMessageConverter가 직렬화하므로Content-Type, DTO 구조, Jackson 설정까지 함께 봐야 정확히 이해할 수 있습니다.
왜 두 어노테이션이 나뉘었을까
스프링 MVC의 출발점은 서버가 HTML을 만들어 브라우저에 내려주는 구조였습니다. 이 흐름에서 컨트롤러는 요청을 받고, 필요한 데이터를 준비한 뒤, 어떤 화면을 렌더링할지 결정합니다. 그래서 @Controller는 원래 뷰 렌더링과 잘 맞는 어노테이션입니다.
하지만 지금의 백엔드는 브라우저 화면만 상대하지 않습니다. React나 Vue 같은 프론트엔드, 모바일 앱, 외부 시스템 연동은 보통 HTML이 아니라 JSON 데이터를 기대합니다. 이때는 템플릿을 찾는 것이 아니라 응답 본문에 데이터를 바로 써야 하므로 @RestController가 더 자연스럽습니다.
핵심은 이름 차이가 아니라 반환값의 해석 방식입니다. 같은 메서드, 같은 반환 타입이라도 어떤 어노테이션이 붙어 있느냐에 따라 스프링이 전혀 다르게 처리합니다. 실무에서 헷갈리는 지점도 대부분 여기서 나옵니다.
반환값은 어디로 가는가: 뷰 이름과 응답 본문
입문자가 가장 많이 혼동하는 부분은 "컨트롤러가 값을 반환하면 그다음에 무슨 일이 일어나지?"입니다. 이 질문에 답할 수 있으면 두 어노테이션의 차이는 거의 정리됩니다.
@Controller에서는 반환값이 뷰 렌더링 쪽으로 해석될 가능성이 큽니다. 특히 String을 반환하면 스프링은 이를 응답 본문이 아니라 뷰 이름으로 보는 경우가 많습니다. 예를 들어 "users/detail"을 반환하면 ViewResolver가 이를 템플릿 경로로 해석하고, Thymeleaf나 JSP가 실제 HTML을 생성합니다.
반대로 @RestController에서는 반환값이 응답 본문으로 바로 나갑니다. String이면 문자열 그대로, 객체면 JSON이나 XML로 직렬화된 결과가 본문에 담깁니다. 이 변환은 HttpMessageConverter가 담당하며, Spring Boot에서는 대부분 Jackson이 JSON 처리를 맡습니다.
짧게 정리하면 아래처럼 이해하면 됩니다.
@Controller+String반환: 보통 뷰 이름@Controller+@ResponseBody: 응답 본문@RestController: 메서드 기본 동작이 응답 본문
그래서 "hello"를 반환했는데 브라우저에 hello가 안 보이고 템플릿을 찾으려 한다면, 로직 문제보다 먼저 컨트롤러 어노테이션을 봐야 합니다.
@ResponseBody로 이해하는 핵심 차이
@RestController를 별도의 개념으로 외우기보다, @Controller에 @ResponseBody가 기본 적용된 형태로 이해하면 훨씬 쉽습니다.
화면용 컨트롤러는 보통 이렇게 작성합니다. 모델에 데이터를 담고 뷰 이름을 반환합니다.
package com.example.demo.web;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class PageController {
@GetMapping("/hello-page")
public String helloPage(Model model) {
model.addAttribute("message", "안녕하세요");
return "hello";
}
}
위 코드는 /hello-page 요청이 들어오면 hello라는 템플릿을 찾습니다. 예를 들어 src/main/resources/templates/hello.html이 있으면 해당 파일을 렌더링해 HTML을 응답합니다.
반대로 API 컨트롤러는 보통 응답 객체 자체를 반환합니다. 이 객체는 JSON으로 직렬화되어 본문에 들어갑니다.
package com.example.demo.api;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloApiController {
@GetMapping("/api/hello")
public ResponseEntity<HelloResponse> hello() {
return ResponseEntity.ok(new HelloResponse("안녕하세요", 200));
}
public record HelloResponse(String message, int code) {
}
}
이 경우 응답 본문은 대체로 다음과 같은 JSON이 됩니다.
{"message":"안녕하세요","code":200}
여기서 중요한 점은 @Controller가 화면 전용, @RestController가 API 전용이라는 식으로 너무 딱 잘라 생각할 필요는 없다는 것입니다. @Controller에서도 특정 메서드에 @ResponseBody를 붙이면 JSON 응답을 만들 수 있습니다. 다만 클래스 전체가 API 목적이라면 @RestController가 더 읽기 쉽고 실수를 줄입니다.
Spring Boot에서 화면용과 API용을 나누는 방법
실무에서는 어노테이션 차이만 아는 것보다 구조를 어떻게 나누는지가 더 중요합니다. 화면용 엔드포인트와 API 엔드포인트를 패키지와 URL 규칙으로 분리해두면 유지보수가 쉬워집니다.
예를 들면 이런 식입니다.
com.example.demo.web: 서버 렌더링 화면 담당com.example.demo.api: REST API 담당com.example.demo.service: 비즈니스 로직com.example.demo.domain: 도메인 모델/api/**: API 경로/admin,/products,/users/**: 화면 경로
설정도 두 흐름을 함께 염두에 두고 봐야 합니다. 템플릿 엔진과 JSON 직렬화는 서로 다른 계층에서 동작하기 때문입니다.
spring:
thymeleaf:
prefix: classpath:/templates/
suffix: .html
cache: false
jackson:
serialization:
write-dates-as-timestamps: false
default-property-inclusion: non_null
server:
error:
include-message: always
위 설정에서 thymeleaf는 @Controller가 반환한 뷰 이름을 실제 템플릿 파일로 연결할 때 영향을 주고, jackson은 @RestController가 반환한 객체를 JSON으로 바꿀 때 영향을 줍니다. 같은 애플리케이션 안에서도 응답 흐름이 둘로 나뉜다는 점을 설정에서도 확인할 수 있습니다.
같은 기능을 두 방식으로 구현해보기
예를 들어 "내 정보 보기"라는 기능이 있다고 해보겠습니다. 서버가 HTML 화면을 직접 만들면 화면용 컨트롤러가 되고, 프론트엔드가 데이터를 받아 직접 그리게 하려면 API 컨트롤러가 됩니다.
화면용 컨트롤러는 모델에 값을 넣고 템플릿 이름을 돌려줍니다.
package com.example.demo.web;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class UserPageController {
@GetMapping("/users/me")
public String myPage(Model model) {
model.addAttribute("name", "seji");
model.addAttribute("role", "ADMIN");
return "users/me";
}
}
API 컨트롤러는 데이터를 DTO로 만들어 그대로 반환합니다.
package com.example.demo.api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserApiController {
@GetMapping("/api/users/me")
public UserDto me() {
return new UserDto("seji", "ADMIN");
}
public record UserDto(String name, String role) {
}
}
둘 다 같은 비즈니스 데이터를 사용하지만 표현 방식은 완전히 다릅니다. 그래서 서비스 계층은 공통으로 재사용하되, 어떤 형식으로 응답할지는 컨트롤러에서 명확히 결정하는 편이 좋습니다. 이 구조가 잡혀 있으면 서버 렌더링 화면과 SPA용 API가 공존해도 코드가 덜 꼬입니다.
브라우저와 curl로 바로 확인하는 방법
어노테이션 차이는 설명으로만 보면 감이 약합니다. 가장 확실한 방법은 실제 응답을 보는 것입니다. 특히 상태 코드, 헤더, 본문을 함께 보면 차이가 금방 드러납니다.
먼저 API 응답을 확인해보겠습니다.
curl -i http://localhost:8080/api/hello
curl -i http://localhost:8080/api/users/me
정상이라면 Content-Type은 대체로 application/json으로 보이고, 본문에는 JSON이 들어옵니다. 반면 화면용 엔드포인트를 호출하면 보통 text/html에 가까운 응답이 옵니다.
curl -i http://localhost:8080/hello-page
curl -i http://localhost:8080/users/me
이때 확인할 포인트는 단순합니다.
- 상태 코드가 기대한 값인지
Content-Type이application/json인지text/html인지- 본문이 템플릿 결과인지 JSON인지
- 예상과 다르면 실제 컨트롤러 어노테이션이 무엇인지
브라우저에서 페이지가 잘 보인다고 해서 API도 정상인 것은 아닙니다. API는 본문뿐 아니라 헤더도 계약의 일부이므로, curl -i나 브라우저 개발자 도구 Network 탭으로 확인하는 습관이 중요합니다.
자주 발생하는 실수와 디버깅 포인트
가장 흔한 실수는 @Controller에서 String을 반환해놓고 응답 본문에 문자열이 내려갈 것이라고 기대하는 경우입니다. 이때 스프링은 "ok"를 뷰 이름으로 해석하려고 시도할 수 있고, 결과적으로 템플릿을 찾지 못했다는 오류가 납니다.
또 다른 흔한 오해는 @RestController를 쓰면 JSON이 무조건 잘 나온다고 생각하는 것입니다. 실제로는 반환 객체가 직렬화 가능한 구조여야 하고, 순환 참조나 날짜 포맷 문제도 없어야 합니다. 예를 들어 JPA 엔티티를 그대로 반환하면 연관관계 때문에 Jackson 직렬화가 꼬이는 일이 자주 생깁니다. 그래서 API 응답은 엔티티보다 DTO를 반환하는 쪽이 안전합니다.
문제가 생기면 아래 순서로 확인하면 됩니다.
- 클래스가
@Controller인지@RestController인지 확인한다. - 메서드에
@ResponseBody가 붙었는지 본다. - 반환 타입이
String인지 객체인지 확인한다. - 응답 헤더의
Content-Type을 확인한다. - 로그에
HttpMessageNotWritableException,JsonMappingException같은 Jackson 예외가 있는지 본다.
실무 기준으로는 다음 원칙이 가장 단순하고 효과적입니다.
- HTML을 내려주면
@Controller - JSON API를 내려주면
@RestController - 혼합이 필요하면
@Controller+ 메서드 단위@ResponseBody - 엔티티를 직접 반환하지 말고 DTO를 반환
/api/**같은 URL 규칙으로 역할을 분리
결국 이 선택은 "서버가 최종 화면을 만들 것인가, 데이터만 전달할 것인가"에 대한 선언입니다. 이 기준만 명확하면 @Controller와 @RestController는 어렵지 않습니다.
원문 참고
https://www.maeil-mail.kr/question/12
댓글
댓글 쓰기