@RestController vs @Controller: Spring Boot에서 헷갈리는 어노테이션 완벽 정리

안녕하세요. IT 기술 블로거입니다.

Spring Boot로 웹 애플리케이션을 개발하다 보면 가장 먼저 접하게 되는 어노테이션이 바로 @Controller와 @RestController입니다. 둘 다 클라이언트의 요청을 처리하는 역할을 하지만, 동작 방식과 결과물을 내놓는 형태가 완전히 다릅니다.

특히 최근의 백엔드 개발은 대부분 JSON 데이터를 주고받는 API 형태이기 때문에, 이 두 어노테이션의 차이를 정확히 아는 것이 매우 중요합니다. 오늘은 이 둘의 내부 동작 원리부터 어떤 상황에서 무엇을 써야 하는지까지 낱낱이 파헤쳐 보겠습니다.

1. @Controller: 전통적인 웹 페이지의 지배자

@Controller는 주로 전통적인 Spring MVC에서 뷰(View, HTML)를 반환할 때 사용합니다.

동작 원리

1. 클라이언트의 요청이 오면 컨트롤러가 요청을 가로챕니다.
2. 메서드가 수행된 후 문자열(View Name)을 반환합니다.
3. View Resolver가 이 문자열을 가지고 해당 HTML 파일을 찾아 렌더링하여 클라이언트에게 전달합니다.

만약 @Controller를 사용하면서 JSON 데이터를 반환하고 싶다면, 메서드 위에 별도의 @ResponseBody 어노테이션을 일일이 붙여줘야 합니다.

2. @RestController: 현대적인 REST API의 핵심

@RestController는 이름에서 알 수 있듯이 RESTful 웹 서비스를 위해 설계되었습니다. Spring 4.0에서 등장했으며, 핵심은 다음과 같습니다.

@RestController = @Controller + @ResponseBody

동작 원리

1. 메서드가 반환하는 객체(Object)를 그대로 응답 본문(Body)에 담습니다.
2. 이때 HttpMessageConverter가 작동하여 객체를 JSON이나 XML 같은 데이터 형식으로 자동 변환합니다.
3. 뷰를 찾지 않고 데이터 그 자체를 반환하므로 API 서버 구축에 최적화되어 있습니다.

3. 코드 비교로 보는 결정적 차이

예제 1: @Controller를 사용한 HTML 반환

@Controller
public class WebController {

    @GetMapping("/home")
    public String homePage() {
        // "home"이라는 이름의 뷰(home.html 등)를 찾아서 반환합니다.
        return "home"; 
    }

    @GetMapping("/api/data")
    @ResponseBody // 데이터 반환을 위해 명시적으로 추가해야 함
    public Member getData() {
        return new Member("Kama", 20);
    }
}

예제 2: @RestController를 사용한 JSON 반환

@RestController
@RequestMapping("/api/v1")
public class ApiController {

    @GetMapping("/member")
    public Member getMember() {
        // 객체를 반환하면 자동으로 JSON으로 변환됩니다.
        // 별도의 @ResponseBody가 필요 없습니다.
        return new Member("Kama", 20);
    }
}

4. 언제 어떤 것을 사용해야 할까?

사실 정답은 명확합니다.

• @Controller: Thymeleaf, Mustache, JSP 등을 사용하여 HTML 페이지를 직접 서빙해야 하는 서비스일 때 사용합니다.
• @RestController: React, Vue 같은 프론트엔드 프레임워크와 통신하거나 모바일 앱에 데이터(JSON)만 제공하는 API 서버일 때 사용합니다.

최근에는 프론트엔드와 백엔드가 완전히 분리된 아키텍처가 대세이기 때문에, 백엔드 개발자의 실무에서는 90% 이상 @RestController를 사용하게 됩니다.

결론

@Controller와 @RestController의 가장 큰 차이점은 “응답을 어떻게 처리하느냐”에 있습니다. 뷰 리졸버를 통해 화면을 보여줄 것인가, 아니면 메시지 컨버터를 통해 데이터 그 자체를 전달할 것인가의 차이입니다.

현대적인 백엔드 개발자라면 @RestController의 동작 방식인 JSON 직렬화(Serialization) 과정을 잘 이해하고 있어야 합니다. 이 개념은 다음 주제인 “JSON 데이터 자동 변환 원리”에서 더 자세히 다루도록 하겠습니다.

이 글이 여러분의 Spring Boot 학습에 명확한 이정표가 되길 바랍니다. 궁금한 점은 댓글로 남겨주세요!