Spring MVC 요청 처리 흐름 한눈에 이해하기: DispatcherServlet부터 MessageConverter까지
목차
빠른 답
- Spring MVC 요청의 출발점은 DispatcherServlet이고, 실제 컨트롤러 호출은 HandlerAdapter가 담당합니다.
- HTML 응답은 ViewResolver로, JSON 응답은 HttpMessageConverter로 처리 경로가 갈립니다.
- @RequestBody와 @ResponseBody는 ArgumentResolver와 ReturnValueHandler를 통해 MessageConverter와 연결됩니다.
- 문제가 생기면 URL 매핑, Accept·Content-Type 헤더, 컨버터 선택 로그를 먼저 확인하는 것이 가장 빠릅니다.
빠른 답
- Spring MVC 요청은
DispatcherServlet에서 시작하고, 어떤 컨트롤러를 실행할지는HandlerMapping, 실제 호출은HandlerAdapter가 담당합니다. - HTML 화면을 반환하면
ViewResolver가 뷰를 찾고 렌더링하며, JSON이나 문자열 본문을 반환하면HttpMessageConverter가 응답 본문을 만듭니다. @RequestBody는 요청 본문을 객체로 읽는 과정에서,@ResponseBody와ResponseEntity는 응답 객체를 본문으로 쓰는 과정에서HttpMessageConverter와 연결됩니다.- 문제가 생기면
URL 매핑,HTTP 메서드,Content-Type·Accept헤더, 그리고 실제로 선택된 컨버터 로그부터 확인하는 것이 가장 빠릅니다.
Spring MVC 실행 흐름을 왜 알아야 하는가
Spring MVC는 처음엔 단순해 보입니다. @Controller, @GetMapping, @RestController 정도만 알아도 화면과 API를 금방 만들 수 있기 때문입니다. 하지만 실제 프로젝트에서는 동작 자체보다 “왜 이렇게 동작하는가”를 이해해야 막히는 지점을 빨리 풀 수 있습니다.
예를 들어 이런 문제는 매우 흔합니다. 컨트롤러를 분명 만들었는데 404가 발생하거나, JSON 요청을 보냈는데 415가 뜨거나, 응답은 오는데 원하는 JSON 구조가 아니라는 식입니다. 이럴 때는 어노테이션 이름을 더 외우는 것보다 요청이 어떤 순서로 처리되는지 아는 편이 훨씬 도움이 됩니다.
핵심은 간단합니다. Spring MVC는 요청을 받는 단계, 핸들러를 찾는 단계, 메서드 인자를 만드는 단계, 컨트롤러를 호출하는 단계, 반환값을 해석하는 단계로 나뉘어 동작합니다. 그리고 화면을 반환하는 경우와 API 본문을 반환하는 경우는 마지막 단계에서 갈라집니다. 이 흐름을 잡아 두면 이후의 검증, 예외 처리, 인터셉터, @ControllerAdvice도 자연스럽게 연결됩니다.
DispatcherServlet, HandlerMapping, HandlerAdapter의 역할 먼저 잡기
Spring MVC의 시작점은 DispatcherServlet입니다. 이 서블릿은 프론트 컨트롤러로서 모든 요청을 한곳에서 받습니다. 중요한 점은 DispatcherServlet이 직접 컨트롤러 메서드를 호출하지 않는다는 것입니다. 먼저 누가 이 요청을 처리해야 하는지 찾고, 그다음 그 핸들러를 어떤 방식으로 실행할지 결정합니다.
이때 등장하는 두 축이 HandlerMapping과 HandlerAdapter입니다.
HandlerMapping: 요청 URL, HTTP 메서드, 추가 조건을 기준으로 어떤 핸들러가 맞는지 찾습니다.HandlerAdapter: 찾은 핸들러를 실제로 실행할 수 있도록 맞춰 줍니다.
우리가 보통 사용하는 @GetMapping, @PostMapping, @RequestMapping 기반 컨트롤러는 내부적으로 대개 RequestMappingHandlerMapping과 RequestMappingHandlerAdapter 조합으로 처리됩니다. 즉, “URL과 메서드를 보고 컨트롤러를 찾는다”에서 끝나는 것이 아니라, 그 뒤에 메서드 파라미터 해석과 반환값 처리라는 단계가 붙습니다.
흐름을 단순화하면 다음 순서입니다.
DispatcherServlet이 요청을 받습니다.HandlerMapping이 요청을 처리할 컨트롤러 메서드를 찾습니다.HandlerAdapter가 메서드 파라미터를 준비하고 컨트롤러를 호출합니다.- 반환값 타입에 따라
ViewResolver또는HttpMessageConverter쪽으로 분기합니다.
실무에서 자주 놓치는 지점은 3번과 4번입니다. 대부분의 문제는 컨트롤러 메서드 “앞”의 인자 바인딩이나 “뒤”의 반환값 변환 단계에서 발생합니다.
화면을 반환할 때의 요청 처리 흐름
HTML 화면을 반환하는 전통적인 MVC에서는 컨트롤러가 HTML 문자열 자체를 만드는 것이 아닙니다. 보통 모델 데이터를 채우고, 논리적인 뷰 이름을 반환합니다. 이후 ViewResolver가 그 이름을 실제 템플릿 경로나 JSP 경로로 바꾸고, 최종 View가 렌더링을 수행합니다.
아래 코드는 전형적인 화면 반환 컨트롤러입니다.
@Controller
@RequestMapping("/members")
public class MemberPageController {
private final MemberService memberService;
public MemberPageController(MemberService memberService) {
this.memberService = memberService;
}
@GetMapping("/{id}")
public String detail(@PathVariable Long id, Model model) {
Member member = memberService.findById(id);
model.addAttribute("member", member);
return "members/detail";
}
}
이 요청이 처리되는 순서를 코드 기준으로 따라가면 이해가 훨씬 쉽습니다. GET /members/1 요청이 들어오면 DispatcherServlet이 받고, HandlerMapping이 detail() 메서드를 찾습니다. 그다음 HandlerAdapter가 @PathVariable Long id 값을 만들고 Model 객체를 준비한 뒤 메서드를 호출합니다.
컨트롤러는 서비스 계층에서 데이터를 조회하고 model.addAttribute("member", member)로 뷰에 전달할 값을 담습니다. 마지막으로 "members/detail"을 반환합니다. 이 문자열은 응답 본문이 아니라 뷰 이름입니다. 이후 ViewResolver가 이를 실제 템플릿으로 해석하고, 해당 뷰가 모델 데이터를 사용해 HTML을 렌더링합니다.
여기서 자주 헷갈리는 부분이 하나 있습니다. @Controller에서 String을 반환하면 뷰 이름으로 해석될 수 있지만, @RestController에서 String을 반환하면 보통 응답 본문 문자열로 처리됩니다. 둘은 같은 String이어도 해석 방식이 다릅니다. 이 차이를 모르면 템플릿이 렌더링되지 않고 문자열만 내려오는 상황을 쉽게 만나게 됩니다.
JSON API를 반환할 때는 어디서 달라질까
JSON API도 앞부분은 거의 같습니다. 여전히 DispatcherServlet이 요청을 받고, HandlerMapping이 컨트롤러를 찾고, HandlerAdapter가 실행을 담당합니다. 차이는 메서드 인자와 반환값을 다루는 방식에서 분명하게 나타납니다.
@RequestBody가 붙은 파라미터는 HandlerMethodArgumentResolver가 처리합니다. 이때 HttpMessageConverter가 요청 본문을 읽어 JSON을 자바 객체로 변환합니다. 반대로 @ResponseBody나 ResponseEntity 반환값은 HandlerMethodReturnValueHandler가 처리하고, 다시 HttpMessageConverter가 자바 객체를 JSON 문자열로 직렬화해 응답 본문을 만듭니다.
실제 구현 관점에서 보면 이 흐름은 RequestResponseBodyMethodProcessor 같은 구성 요소를 통해 처리됩니다. 이름이 길어서 어렵게 느껴질 수 있지만, 역할은 명확합니다. 요청 본문을 읽고, 응답 본문을 쓰는 쪽을 담당하는 컴포넌트라고 이해하면 충분합니다.
아래 코드는 @RequestBody와 ResponseEntity를 함께 사용하는 가장 전형적인 예시입니다.
@RestController
@RequestMapping("/api/members")
public class MemberApiController {
private final MemberService memberService;
public MemberApiController(MemberService memberService) {
this.memberService = memberService;
}
@PostMapping(
consumes = MediaType.APPLICATION_JSON_VALUE,
produces = MediaType.APPLICATION_JSON_VALUE
)
public ResponseEntity<MemberResponse> create(@RequestBody CreateMemberRequest request) {
Member member = memberService.create(request.name(), request.email());
MemberResponse response = new MemberResponse(
member.getId(),
member.getName(),
member.getEmail()
);
return ResponseEntity.status(HttpStatus.CREATED).body(response);
}
public record CreateMemberRequest(String name, String email) {}
public record MemberResponse(Long id, String name, String email) {}
}
이 코드에서 요청이 들어오면 Content-Type: application/json 헤더를 보고 JSON 본문을 읽을 수 있는 컨버터가 선택됩니다. Spring Boot 환경에서는 보통 Jackson 라이브러리가 클래스패스에 있으면 MappingJackson2HttpMessageConverter가 등록되어 이 역할을 수행합니다.
그리고 응답을 만들 때는 클라이언트의 Accept 헤더, 컨트롤러 반환 타입, 등록된 컨버터 목록을 함께 보고 어떤 형식으로 내려줄지 결정합니다. 그래서 JSON을 읽고 쓰는 문제는 단순히 “객체를 반환했는데 왜 JSON이 아니지?” 수준이 아니라, Content-Type, Accept, 반환 타입, 등록된 컨버터를 함께 봐야 풀립니다.
ArgumentResolver와 ReturnValueHandler를 같이 이해해야 하는 이유
Spring MVC를 공부할 때 @RequestBody, @PathVariable, @RequestParam, Model, BindingResult가 각각 따로 보이면 이해가 잘 안 됩니다. 하지만 모두 “컨트롤러 메서드 인자를 누가 어떻게 만들어 주는가”라는 관점으로 묶으면 정리가 됩니다.
HandlerMethodArgumentResolver는 메서드 파라미터를 해석하는 전략입니다. 예를 들면 다음과 같습니다.
@PathVariable Long id: URL 경로 변수에서 값을 꺼내 타입 변환@RequestParam String keyword: 쿼리 파라미터에서 값 추출@ModelAttribute: 요청 파라미터를 객체에 바인딩@RequestBody: 요청 본문을HttpMessageConverter로 읽어 객체 생성
반대로 컨트롤러가 값을 반환한 뒤에는 HandlerMethodReturnValueHandler가 동작합니다.
String: 뷰 이름 또는 본문 문자열로 해석ModelAndView: 뷰와 모델을 함께 전달@ResponseBody: 반환 객체를 본문으로 기록ResponseEntity<T>: 상태 코드, 헤더, 본문을 함께 응답
즉, 요청이 컨트롤러 “안으로 들어올 때”는 Argument Resolver가, 컨트롤러 “밖으로 나갈 때”는 Return Value Handler가 처리합니다. 이 둘을 함께 이해하면 @RequestBody와 @ResponseBody가 왜 대칭처럼 보이는지, 그리고 둘 다 HttpMessageConverter와 이어지는 이유도 자연스럽게 보입니다.
Spring Boot에서는 어떤 설정이 기본으로 잡히는가
Spring Boot를 사용하면 MVC 관련 기본 설정이 꽤 많이 자동으로 구성됩니다. DispatcherServlet, 여러 HandlerMapping, HandlerAdapter, 기본 예외 처리기, 그리고 다양한 HttpMessageConverter가 대표적입니다. Jackson이 클래스패스에 있으면 JSON 컨버터도 자동 등록됩니다.
그래서 대부분의 Boot 프로젝트에서는 @EnableWebMvc 없이도 MVC가 잘 동작합니다. 오히려 특별한 이유 없이 @EnableWebMvc를 붙이면 Boot가 제공하던 자동 설정 일부를 직접 챙겨야 할 수 있습니다. 입문 단계에서는 기본 자동 구성을 이해하고 필요한 부분만 덧붙이는 편이 훨씬 안정적입니다.
아래 설정은 화면 반환과 JSON 직렬화, 그리고 디버깅 로그를 한 번에 확인할 수 있는 실전적인 예시입니다.
spring:
mvc:
view:
prefix: /WEB-INF/views/
suffix: .jsp
jackson:
property-naming-strategy: SNAKE_CASE
logging:
level:
org.springframework.web.servlet.DispatcherServlet: DEBUG
org.springframework.web.servlet.mvc.method.annotation.RequestResponseBodyMethodProcessor: TRACE
org.springframework.http.converter: TRACE
이 설정에서 볼 포인트는 세 가지입니다. 첫째, 뷰 이름이 실제 파일 경로로 어떻게 연결되는지 알 수 있습니다. 둘째, Jackson 직렬화 규칙을 전역 설정으로 맞출 수 있습니다. 셋째, 어떤 컨트롤러 메서드가 선택됐고 어떤 컨버터가 요청과 응답에 사용됐는지 로그로 확인할 수 있습니다.
프로젝트가 Thymeleaf를 쓴다면 JSP 설정 대신 Thymeleaf 자동 구성이 동작하고, REST API 중심 프로젝트라면 뷰 리졸버보다 메시지 컨버터 로그가 훨씬 더 중요해집니다. 결국 핵심은 “내 프로젝트가 어떤 응답 방식을 주로 쓰는가”를 기준으로 설정과 로그 포인트를 보는 것입니다.
요청 하나를 끝까지 따라가 보기
실행 흐름은 코드만 봐서는 추상적으로 느껴질 수 있습니다. 그래서 직접 요청을 보내 보는 것이 좋습니다. 특히 curl로 헤더를 명시하면 Content-Type과 Accept가 컨버터 선택에 어떤 영향을 주는지 바로 체감할 수 있습니다.
먼저 JSON 생성 API 요청입니다.
curl -i -X POST http://localhost:8080/api/members \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"name":"kim","email":"kim@example.com"}'
이 요청은 내부적으로 다음 순서로 처리됩니다. DispatcherServlet이 요청을 받고, RequestMappingHandlerMapping이 create() 메서드를 찾습니다. 그다음 RequestMappingHandlerAdapter가 @RequestBody CreateMemberRequest를 해석하고, Jackson 기반 컨버터가 JSON을 객체로 변환합니다. 컨트롤러가 ResponseEntity<MemberResponse>를 반환하면 Return Value Handler가 이를 처리하고, 다시 메시지 컨버터가 JSON 본문으로 직렬화합니다.
화면 조회 요청은 흐름의 마지막 단계가 다릅니다.
curl -i http://localhost:8080/members/1
이 경우에도 앞부분은 동일합니다. 다만 컨트롤러가 "members/detail" 같은 뷰 이름을 반환하면 HttpMessageConverter가 아니라 ViewResolver가 동작합니다. 같은 Spring MVC 안에서도 응답이 HTML인지, JSON인지에 따라 마지막 처리 경로가 갈린다는 점이 핵심입니다.
실무에서 가장 먼저 확인할 디버깅 포인트
Spring MVC 문제는 복잡해 보이지만, 확인 순서는 의외로 정형화되어 있습니다. 먼저 매핑이 맞는지 보고, 그다음 요청과 응답 헤더를 보고, 마지막으로 어떤 컨버터가 선택됐는지를 보면 대부분의 문제가 풀립니다.
가장 자주 만나는 증상은 아래처럼 정리할 수 있습니다.
- 404: URL 경로, 클래스 레벨과 메서드 레벨의
@RequestMapping, 컴포넌트 스캔 범위를 먼저 확인합니다. - 405: URL은 맞지만 HTTP 메서드가 다를 가능성이 큽니다.
GET과POST를 혼동한 경우가 많습니다. - 415: 요청
Content-Type이 컨트롤러가 기대하는 형식과 다르거나, 본문을 읽을 수 있는 컨버터가 없는 경우입니다. - 406:
Accept헤더는 특정 형식을 요구하는데, 서버가 해당 미디어 타입으로 응답할 수 없을 때 발생합니다. - 뷰가 렌더링되지 않고 문자열만 내려옴:
@Controller와@RestController사용 의도가 맞는지 확인해야 합니다. - Boot에서 갑자기 MVC 동작이 달라짐:
@EnableWebMvc추가 여부와 커스텀WebMvcConfigurer설정을 확인하는 편이 좋습니다.
로그도 매우 강력한 힌트입니다. 예를 들어 아래와 같은 로그는 문제 지점을 빠르게 좁히는 데 도움이 됩니다.
Mapped to com.example.MemberApiController#create(CreateMemberRequest)
Read "application/json" to [CreateMemberRequest[name=kim, email=kim@example.com]]
Using 'application/json', given [application/json] and supported [application/json]
Writing [MemberResponse[id=1, name=kim, email=kim@example.com]]
첫 줄은 어떤 컨트롤러 메서드가 선택됐는지 보여줍니다. 두 번째 줄은 요청 본문이 어떤 객체로 변환됐는지 알려 줍니다. 마지막 줄은 응답 객체가 어떤 형식으로 쓰였는지 보여 줍니다. 매핑, 읽기, 쓰기 이 세 단계를 순서대로 확인하면 대부분의 이슈는 훨씬 빨리 정리됩니다.
추가로 Spring Boot Actuator를 사용하고 있다면 /actuator/mappings도 매우 유용합니다. 현재 애플리케이션에 등록된 요청 매핑을 한눈에 볼 수 있어서 “내 컨트롤러가 왜 안 잡히지?” 같은 문제를 푸는 데 큰 도움이 됩니다.
정리
Spring MVC 실행 흐름은 결국 하나의 질문으로 정리할 수 있습니다. “이 요청이 어떤 과정을 거쳐 컨트롤러에 도달하고, 어떤 방식으로 최종 응답이 되는가?”입니다.
앞부분의 공통 흐름은 DispatcherServlet → HandlerMapping → HandlerAdapter입니다. 여기까지는 화면 응답과 JSON 응답이 거의 같습니다. 이후에는 반환값 성격에 따라 두 갈래로 나뉩니다. 뷰 이름을 반환하면 ViewResolver가 동작하고, 응답 본문을 직접 내려주면 HttpMessageConverter가 동작합니다. 그리고 그 사이에서 메서드 인자는 ArgumentResolver, 반환값은 ReturnValueHandler가 해석합니다.
이 구조를 이해하고 나면 Spring MVC는 더 이상 “어노테이션이 알아서 해 주는 프레임워크”가 아니라, 어디서 무엇이 일어나는지 추적 가능한 시스템으로 보이기 시작합니다. 실무에서 중요한 것은 바로 이 지점입니다. 흐름을 알고 있으면 설정도 덜 두렵고, 디버깅도 훨씬 빨라집니다.
원문 참고
https://www.maeil-mail.kr/question/11
댓글
댓글 쓰기