스프링 MVC 응답 처리 이해하기: @ResponseBody, ResponseEntity, 그리고 뷰 반환의 차이

스프링 MVC에서 컨트롤러 메서드는 결국 값을 return합니다. 그런데 같은 return이어도 어떤 경우에는 JSON이 내려가고, 어떤 경우에는 템플릿이 렌더링됩니다. 예를 들어 return "users/detail";는 화면 이름처럼 동작할 수도 있고, 응답 본문에 문자열 그대로 기록될 수도 있습니다.

이 차이는 자바 문법이 아니라 스프링 MVC의 반환값 해석 방식에서 생깁니다. 핵심은 컨트롤러가 무엇을 반환했는지가 아니라, 스프링이 그 반환값을 어떤 의미로 받아들이는지입니다. @ResponseBody가 붙어 있는지, ResponseEntity<T>를 반환하는지, 일반 @Controller인지에 따라 내부 처리 경로가 달라집니다.

왜 같은 return 문인데 결과가 달라질까

가장 먼저 정리할 기준은 이것입니다.

• @ResponseBody가 있으면 반환값은 HTTP 응답 본문으로 처리됩니다.
• ResponseEntity<T>를 반환하면 응답 본문, 상태 코드, 헤더까지 함께 처리됩니다.
• 위 조건이 없고 @Controller에서 String을 반환하면 보통 뷰 이름으로 해석됩니다.

즉, 아래 두 코드는 문법은 비슷하지만 의미가 완전히 다릅니다.

@Controller
public class PageController {

    @GetMapping("/hello-page")
    public String hello() {
        return "hello";
    }
}

이 경우 "hello"는 응답 문자열이 아니라 뷰 이름입니다. 스프링은 hello.html, hello.jsp 같은 실제 뷰를 찾으려 합니다.

반대로 다음 코드는 "hello"를 응답 본문에 직접 씁니다.

@Controller
public class ApiController {

    @GetMapping("/hello-body")
    @ResponseBody
    public String hello() {
        return "hello";
    }
}

브라우저나 curl은 이제 템플릿이 아니라 문자열 hello 자체를 받게 됩니다. 실무에서 많이 헷갈리는 이유가 여기 있습니다. 눈에 보이는 return "hello"는 같지만, 스프링이 읽는 의미는 전혀 다릅니다.

스프링 MVC는 반환값을 어떻게 해석할까

요청이 들어오면 스프링 MVC는 DispatcherServlet을 중심으로 동작합니다. 크게 보면 다음 순서로 흘러갑니다.

1. DispatcherServlet이 요청을 받습니다.
2. HandlerMapping이 어떤 컨트롤러 메서드가 이 요청을 처리할지 찾습니다.
3. HandlerAdapter가 메서드를 실행합니다.
4. 메서드가 반환한 값을 HandlerMethodReturnValueHandler들이 해석합니다.
5. 해석 결과에 따라 HttpMessageConverter 또는 ViewResolver가 동작합니다.

실제로 중요한 분기점은 4번입니다. 이 단계에서 스프링은 다음과 같은 판단을 합니다.

• @ResponseBody가 붙었는가
• 반환 타입이 ResponseEntity, HttpEntity인가
• 반환값이 String, View, ModelAndView인가
• 일반 객체라면 모델 속성으로 취급해야 하는가

여기서 흔히 놓치는 포인트가 하나 있습니다. @Controller 메서드가 일반 DTO를 반환했다고 해서 자동으로 JSON이 되는 것은 아닙니다. @ResponseBody가 없다면 그 객체는 모델 속성으로 추가되고, 이후 뷰 렌더링 단계로 넘어갈 수 있습니다. 그래서 API를 만들고 있다고 생각했는데 템플릿 관련 예외가 터지는 일이 생깁니다.

정리하면 다음처럼 기억하면 됩니다.

• 본문을 내려야 하면 @ResponseBody 또는 ResponseEntity
• 화면을 렌더링해야 하면 뷰 이름 반환
• API 전용 컨트롤러라면 @RestController

HttpMessageConverter와 ViewResolver는 언제 동작할까

두 컴포넌트의 역할을 구분하면 전체 흐름이 훨씬 선명해집니다.

HttpMessageConverter는 응답 본문을 직접 만들어야 할 때 사용됩니다. 보통 다음 경우에 동작합니다.

• @ResponseBody
• @RestController
• ResponseEntity<T>

예를 들어 메서드가 UserResponse 객체를 반환하고 Jackson이 클래스패스에 있으면, 스프링은 적절한 HttpMessageConverter를 선택해 JSON으로 직렬화합니다. 이때 Accept 헤더와 Content-Type도 함께 고려됩니다.

반면 ViewResolver는 화면을 만들어야 할 때 동작합니다. 컨트롤러가 "users/detail"을 반환하면 스프링은 이 값을 뷰 이름으로 보고, 설정된 prefix/suffix를 조합해 템플릿 파일을 찾습니다. 그리고 Model에 담긴 값을 템플릿에 전달해 최종 HTML을 만듭니다.

두 역할을 아주 짧게 요약하면 이렇습니다.

• HttpMessageConverter: 자바 값을 HTTP 본문 데이터로 변환
• ViewResolver: 뷰 이름을 실제 템플릿으로 해석

이 구분을 이해하면 왜 화면용 컨트롤러와 API 컨트롤러를 섞을 때 사고가 나는지도 설명됩니다. 하나는 렌더링이 목적이고, 다른 하나는 직렬화가 목적이기 때문입니다.

기본 설정은 어떻게 갖춰야 할까

스프링 부트에서는 대부분 자동 설정이 되지만, 어떤 스타터가 들어가 있느냐에 따라 동작 전제가 달라집니다. JSON 응답을 확인하려면 웹 스타터가 필요하고, 뷰 반환을 확인하려면 템플릿 엔진이 필요합니다.

아래 구성은 두 흐름을 모두 실험하기에 적당한 최소 예시입니다.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

spring-boot-starter-web은 MVC와 기본 메시지 컨버터 구성을 가져오고, spring-boot-starter-thymeleaf는 뷰 이름을 실제 템플릿으로 연결하는 데 필요한 설정을 제공합니다. 만약 화면 렌더링은 필요 없고 API만 제공한다면 템플릿 엔진 의존성은 없어도 됩니다.

로그를 조금만 열어두면 어떤 경로를 탔는지 디버깅하기 쉬워집니다.

spring:
  thymeleaf:
    prefix: classpath:/templates/
    suffix: .html
    cache: false

logging:
  level:
    org.springframework.web.servlet: DEBUG
    org.springframework.web.servlet.mvc.method.annotation: DEBUG

이 설정을 켜두면 뷰 리졸버가 어떤 이름을 찾는지, 메시지 컨버터가 어떤 타입을 쓰는지 로그에서 확인하기 편합니다.

코드로 비교해보면 차이가 더 분명해진다

이제 화면 반환, @ResponseBody, ResponseEntity를 한 컨트롤러에서 비교해보겠습니다.

package com.example.demo.web;

import java.net.URI;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

@Controller
@RequestMapping("/users")
public class UserController {

    @GetMapping("/page")
    public String page(Model model) {
        model.addAttribute("userName", "seji");
        return "users/detail";
    }

    @GetMapping("/body")
    @ResponseBody
    public UserResponse body() {
        return new UserResponse(1L, "seji");
    }

    @GetMapping("/entity")
    public ResponseEntity<UserResponse> entity() {
        UserResponse body = new UserResponse(1L, "seji");

        return ResponseEntity
                .created(URI.create("/users/1"))
                .header(HttpHeaders.CACHE_CONTROL, "no-store")
                .body(body);
    }

    public record UserResponse(Long id, String name) {
    }
}

이 코드의 동작은 각각 다릅니다.

• /users/page는 users/detail 뷰를 찾고, Model의 userName을 템플릿에 전달합니다.
• /users/body는 UserResponse를 JSON으로 직렬화해 응답 본문에 씁니다.
• /users/entity는 JSON 본문뿐 아니라 201 Created, Location, Cache-Control 헤더까지 함께 내려줍니다.

여기서 ResponseEntity에 @ResponseBody가 없는 점을 눈여겨볼 만합니다. ResponseEntity는 스프링이 별도 경로로 처리하는 반환 타입이라, 본문 응답으로 해석됩니다.

템플릿도 간단히 하나 두면 화면 반환 경로를 바로 확인할 수 있습니다.

<!-- src/main/resources/templates/users/detail.html -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<body>
<h1>User Detail</h1>
<p th:text="${userName}">unknown</p>
</body>
</html>

이 상태에서 /users/page로 접근하면 HTML이 렌더링되고, /users/body나 /users/entity로 접근하면 JSON이 내려옵니다.

curl로 확인하면 무엇이 달라질까

브라우저로 볼 때는 차이가 흐릿할 수 있으니 curl로 직접 보는 편이 좋습니다.

curl -i http://localhost:8080/users/page
curl -i http://localhost:8080/users/body
curl -i http://localhost:8080/users/entity

기대 결과는 다음과 같습니다.

• /users/page
• 보통 Content-Type: text/html
• 렌더링된 HTML 응답
• /users/body
• 200 OK
• Content-Type: application/json
• {"id":1,"name":"seji"}
• /users/entity
• 201 Created
• Location: /users/1
• Cache-Control: no-store
• JSON 본문

이렇게 직접 비교해보면 return 값 자체보다 반환값 처리 전략이 핵심이라는 점이 더 분명해집니다.

@ResponseBody와 ResponseEntity는 무엇이 다를까

둘 다 본문 응답을 만든다는 점에서는 비슷합니다. 하지만 제어 범위가 다릅니다.

@ResponseBody는 응답 본문 중심입니다. 간단한 조회 API라면 이 방식이 가장 읽기 쉽고 코드도 짧습니다.

@GetMapping("/profile")
@ResponseBody
public UserResponse profile() {
    return service.getProfile();
}

반면 ResponseEntity는 HTTP 응답 전체를 다룰 수 있습니다. 상태 코드, 헤더, 본문을 한 번에 결정해야 하면 이쪽이 더 적합합니다.

@DeleteMapping("/users/{id}")
public ResponseEntity<Void> delete(@PathVariable Long id) {
    service.delete(id);
    return ResponseEntity.noContent().build();
}

다음과 같은 상황에서는 ResponseEntity가 특히 유리합니다.

• 생성 성공 시 201 Created와 Location 헤더를 내려야 할 때
• 삭제 성공 시 204 No Content를 반환해야 할 때
• 캐시 제어, 다운로드, 인증 관련 헤더를 추가해야 할 때
• 동일한 메서드에서 성공과 실패에 따라 상태 코드를 나눠야 할 때

실무에서는 "무조건 ResponseEntity를 써야 한다"보다 "HTTP 응답을 얼마나 세밀하게 제어해야 하느냐"를 기준으로 선택하는 편이 낫습니다.

자주 만나는 실수와 디버깅 포인트

이 주제는 개념보다 실수 패턴을 아는 것이 더 도움이 됩니다.

첫째, @Controller에서 DTO를 반환하고 JSON이 내려갈 것이라 기대하는 경우가 많습니다. 하지만 @ResponseBody가 없으면 JSON 응답이 아니라 모델 처리 경로로 들어갈 수 있습니다. API 컨트롤러라면 @RestController를 사용하는 편이 안전합니다.

둘째, @RestController를 화면 반환 컨트롤러에 써버리면 뷰 이름이 렌더링되지 않습니다. return "users/detail";이 템플릿 이름이 아니라 문자열 본문이 되어버립니다.

셋째, Jackson 의존성이 빠져 있거나 직렬화할 수 없는 객체를 반환하면 메시지 컨버터 단계에서 예외가 납니다. 순환 참조가 있는 엔티티를 그대로 반환할 때도 이런 문제가 자주 생깁니다.

넷째, Accept 헤더와 실제 생성 가능한 응답 타입이 맞지 않으면 406 Not Acceptable가 발생할 수 있습니다. 반대로 요청 본문 역직렬화 문제는 415 Unsupported Media Type과 함께 나타나기도 합니다.

다섯째, 뷰 이름은 맞는데 템플릿 파일 위치가 틀리면 렌더링 단계에서 실패합니다. 이때는 컨트롤러 로직보다 템플릿 경로, prefix/suffix, 의존성 구성을 먼저 확인하는 것이 빠릅니다.

디버깅할 때는 항상 한 가지를 먼저 확인하면 됩니다. 지금 스프링이 이 반환값을 데이터로 보고 있는지, 뷰 이름으로 보고 있는지입니다. 이 판단만 맞추면 문제를 좁히는 속도가 훨씬 빨라집니다.

실무에서는 어떻게 구분해서 쓰면 좋을까

가장 단순한 기준은 역할 분리입니다.

• 화면 반환 컨트롤러: @Controller
• API 반환 컨트롤러: @RestController

메서드 단위로 혼합해야 한다면, 화면을 돌려주는 메서드와 본문을 내려주는 메서드를 애노테이션 수준에서 분명히 드러내는 편이 좋습니다. 특히 String 반환은 의미가 쉽게 뒤집히므로 더 조심해야 합니다.

선택 기준도 단순합니다.

• 본문만 내려주면 충분하다면 @ResponseBody 또는 @RestController
• 상태 코드와 헤더까지 함께 제어해야 한다면 ResponseEntity
• HTML 화면을 렌더링해야 한다면 뷰 이름 반환

스프링 MVC의 반환값은 단순히 "무엇을 반환했는가"보다 "스프링이 그것을 어떤 응답 전략으로 해석하는가"가 더 중요합니다. 이 기준만 잡히면 컨트롤러 코드를 읽을 때도, 이상한 응답을 디버깅할 때도 훨씬 덜 헷갈립니다.

원문 참고

https://www.maeil-mail.kr/question/9