HTTP 요청 메시지 - 단순 텍스트

HTTP message body에 직접 데이터를 담아 요청하는 방식은 HTTP API에서 주로 사용하는 방식으로, JSON, XML, TEXT 등 거의 모든 데이터를 전송할 수 있다. 주로 JSON 형식의 데이터를 주고 받는다.

요청 파라미터와는 다르게, HTTP 메시지 바디를 통해 데이터가 직접 넘어오는 경우는 HTML Form 형식을 제외하곤 @RequestParam, @ModelAttribute를 사용할 수 없다.

@Slf4j
@Controller
public class RequestBodyStringController {

    @PostMapping("/request-body-string-v1")
    public void requestBodyString(HttpServletRequest request, HttpServletResponse response) throws IOException {
        ServletInputStream inputStream = request.getInputStream();
        String messageBody = StreamUtils.copyToString(inputStream, StandardCharsets.UTF_8);

        log.info("messageBody={}", messageBody);

        response.getWriter().write("ok");
    }
    
    /**
     * InputStream(Reader): HTTP 요청 메시지 바디의 내용을 직접 조회
     * OutputStream(Writer): HTTP 응답 메시지의 바디에 직접 결과 출력
     */
    @PostMapping("/request-body-string-v2")
    public void requestBodyStringV2(InputStream inputStream, Writer responseWriter) throws IOException {

        String messageBody = StreamUtils.copyToString(inputStream, StandardCharsets.UTF_8);
        log.info("messageBody={}", messageBody);
        responseWriter.write("ok");
    }

    /**
     * HttpEntity: HTTP header, body 정보를 편리하게 조회
     * - 메시지 바디 정보를 직접 조회(@RequestParam, @ModelAttribute 사용 x)
     * - HttpMessageConverter 사용 -> StringHttpMessageConverter 적용
     * 
     * 응답에서도 사용 가능
     * - 메시지 바디 정보 직접 반환(view 조회 x), 헤더 정보 포함 가능
     * - HttpMessageConverter 사용 -> StringHttpMessageConverter 적용
     */
    @PostMapping("/request-body-string-v3")
    public HttpEntity<String> requestBodyStringV3(HttpEntity<String> httpEntity) throws IOException {

        String messageBody = httpEntity.getBody();
        log.info("messageBody={}", messageBody);

        return new HttpEntity<>("ok");
    }

    // 실무에서 이걸 가장 많이 씀.
    @ResponseBody
    @PostMapping("/request-body-string-v4")
    public String requestBodyStringV4(@RequestBody String messageBody) { // HTTP 메시지 바디를 직접 조회
        log.info("messageBody={}", messageBody);
        return "ok";
    }
}

• requestBodyString(): HTTP message body의 데이터를 InputStream을 사용해서 직접 읽을 수 있다.
• requestBodyStringV2(): 매개변수에서 바로 InputStream, Writer를 받을 수 있다.
• requestBodyStringV3(): HttpEntity를 사용하여 HTTP header, body 정보를 편리하게 조회할 수 있다.
• requestBodyStringV4(): @RequestBody, @ResponseBody로 더 간단하게 요청 메시지 바디를 받고 응답 결과를 전달한다.

@RequestBody

HTTP 메시지 바디 정보를 편리하게 조회할 수 있는 애노테이션이다. 바디가 아닌 헤더 정보가 필요하다면 HttpEntity나 @RequestHeader를 사용하면 된다.

메시지 바디를 직접 조회하는 이 기능은 요청 파라미터를 조회하는 @RequestParam, @ModelAttribute와는 전혀 관계가 없다.

@ResponseBody

@ResponseBody를 통해 응답 결과를 HTTP 메시지 바디에 직접 담아서 전달할 수 있다. 이 경우 view를 사용하진 않는다.

HTTP 요청 메시지 - JSON

@PostMapping("/request-body-json-v1")
public void requestBodyJsonV1(HttpServletRequest request, HttpServletResponse response) throws IOException {
    ServletInputStream inputStream = request.getInputStream();
    String messageBody = StreamUtils.copyToString(inputStream, StandardCharsets.UTF_8);

    log.info("messageBody={}", messageBody);
    HelloData helloData = objectMapper.readValue(messageBody, HelloData.class);
    log.info("username={}, age={}", helloData.getUsername(), helloData.getAge());

    response.getWriter().write("ok");
}

• 서블릿의 HttpServletRequest를 사용해서 직접 HTTP 메시지 바디에서 데이터를 읽어와 문자로 변환한다.
• 문자로 된 JSON 데이터를 Jackson 라이브러리인 ObjectMapper를 사용해 자바 객체로 변환한다.
• StreamUtils 까지 사용하는 등 JSON을 받아서 처리하려는 기본적인 과정이 복잡하다.

@ResponseBody
@PostMapping("/request-body-json-v2")
public String requestBodyJsonV2(@RequestBody String messageBody) throws IOException {

    log.info("messageBody={}", messageBody);
    HelloData helloData = objectMapper.readValue(messageBody, HelloData.class);
    log.info("username={}, age={}", helloData.getUsername(), helloData.getAge());

    return "ok";
}

• @RequestBody를 사용해서 메시지 바디를 바로 받아온다.
• 여전히 ObjectMapper를 통해 객체를 변환하는 과정이 번거롭다.

/**
 * @RequestBody 생략 불가능 (@ModelAttribute 가 적용되어 버림)
 * HttpMessageConverter 사용 -> MappingJackson2HttpMessageConverter (content-type: application/json)
 */
@ResponseBody
@PostMapping("/request-body-json-v3")
public String requestBodyJsonV3(@RequestBody HelloData helloData) {
    log.info("username={}, age={}", helloData.getUsername(), helloData.getAge());
    return "ok";
}

• @RequestBody를 사용하면 위처럼 객체를 직접 지정해서 매핑할 수 있다.
• HttpEntity, @RequestBody를 사용하면 HttpMessageConverter가 HTTP 메시지 바디의 내용을 우리가 원하는 문자나 객체 등으로 변환해준다.
• JSON으로 변환도 가능하며 자동으로 처리한다.
• @RequestBody는 생략이 불가능하다. @ModelAttribute가 적용되어 버린다.

content-type은 application/json이어야 한다. 그래야 JSON을 처리할 수 있는 HTTP 메시지 컨버터가 실행된다.

@ResponseBody
@PostMapping("/request-body-json-v4")
public String requestBodyJsonV4(HttpEntity<HelloData> httpEntity) {
    HelloData data = httpEntity.getBody();
    log.info("username={}, age={}", data.getUsername(), data.getAge());
    return "ok";
}

@ResponseBody
@PostMapping("/request-body-json-v5")
public HelloData requestBodyJsonV5(@RequestBody HelloData data) {
    log.info("username={}, age={}", data.getUsername(), data.getAge());
    return data;
}

• HttpEntity를 통해 Generics 타입으로 객체 매핑도 가능하다.
• @RequestBody 요청: JSON 요청 -> HTTP 메시지 컨버터 -> 객체
• @ResponseBody 응답: 객체 -> HTTP 메시지 컨버터 -> JSON 응답

HTTP 응답 - 정적 리소스, 뷰 템플릿

스프링(서버)에서 응답 데이터를 만드는 방법은 크게 3가지이다.

• 정적 리소스: 웹 브라우저에 정적인 HTML, css, js를 제공
• 뷰 템플릿 사용: 웹 브라우저에 동적인 HTML을 제공
• HTTP 메시지 사용: HTTP API를 제공하는 경우 HTML이 아닌 데이터를 전달해야 하기 때문에 HTTP 메시지 바디에 JSON 같은 형식으로 데이터를 실어 보낸다.

정적 리소스

Spring Boot는 클래스패스의 다음 디렉토리에 있는 정적 리소스를 제공한다.

• /static
• /public
• /resources
• /META-INF/resources

src/main/resources는 리소스를 보관하는 곳이며 클래스패스의 시작 경로이다. 이 디렉토리에 리소스를 넣어두면 Spring Boot가 정적 리소스로 서비스를 제공한다. 해당 파일을 변경 없이 그대로 서비스 하는 것이다.

src/main/resources/basic/test.html에 해당 파일이 있다면, 웹 브라우저에서 http://localhost:8080/basic/test.html 처럼 실행하면 된다.

뷰 템플릿

뷰 템플릿을 거쳐서 HTML이 생성되고, 뷰가 응답을 만들어서 전달한다. 일반적으로 HTML을 동적으로 생성하는 용도로 사용하지만, 뷰 템플릿이 만들 수 있다면 다른 것들도 가능하다.

Spring Boot는 기본 뷰 템플릿 경로(src/main/resources/templates)를 제공한다.

• 뷰 템플릿 생성

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
<p th:text="${data}">empty</p>
</body>
</html>

• 뷰 템플릿을 호출하는 컨트롤러

@Controller
public class ResponseViewController {

    @RequestMapping("/response-view-v1")
    public ModelAndView responseViewV1() {
        ModelAndView mav = new ModelAndView("response/hello")
                .addObject("data", "hello!");

        return mav;
    }

    @RequestMapping("/response-view-v2")
    public String responseViewV2(Model model) {
        model.addAttribute("data", "hello!");
        return "response/hello";
    }

    @RequestMapping("/response/hello")
    public void responseViewV3(Model model) {
        model.addAttribute("data", "hello!");
    }
}

• ModelAndView를 반환하는 경우: 객체에서 View를 꺼내 물리적인 뷰 이름으로 완성한 뒤 뷰를 찾아 렌더링한다.
• String을 반환하는 경우
  • @ResponseBody가 없으면 resources/hello로 뷰 리졸버가 실행되어 뷰를 찾고 렌더링한다.
  • @ResponseBody가 있으면 뷰 리졸버를 실행하지 않고, HTTP 메시지 바디에 직접 resources/hello라는 문자가 입력된다.
• void를 반환하는 경우
  • @Controller를 사용하고 HttpServletResponse,OutputStream(Writer)같은 HTTP 메시지 바디를 처리하는 파라미터가 없으면 요청 URL을 참고해서 논리 뷰 이름으로 사용한다.
  • 요청 URL: /response/hello
  • 실행: templates/response/hello.html

// void는 권장하지 않는 방식

HTTP 응답 - HTTP API, 메시지 바디에 직접 입력

HTTP API를 제공하는 경우, HTML이 아닌 데이터를 전달해야 한다. 이 경우, HTTP 메시지 바디에 JSON 같은 형식으로 데이터를 실어 보낸다.

@Slf4j
@RestController
public class ResponseBodyController {

    @GetMapping("/response-body-string-v1")
    public void responseBodyV1(HttpServletResponse response) throws IOException {
        response.getWriter().write("ok");
    }

    @GetMapping("/response-body-string-v2")
    public ResponseEntity<String> responseBodyV2() {
        return new ResponseEntity<>("ok", HttpStatus.OK);
    }

    @ResponseBody
    @GetMapping("/response-body-string-v3")
    public String responseBodyV3() {
        return "ok";
    }

    @GetMapping("/response-body-json-v1")
    public ResponseEntity<HelloData> responseBodyJsonV1() {
        HelloData helloData = new HelloData();
        helloData.setUsername("userA");
        helloData.setAge(20);

        return new ResponseEntity<>(helloData, HttpStatus.OK);
    }

    @ResponseStatus(HttpStatus.OK)
    @ResponseBody
    @GetMapping("/response-body-json-v2")
    public HelloData responseBodyJsonV2() {
        HelloData helloData = new HelloData();
        helloData.setUsername("userA");
        helloData.setAge(20);
        return helloData;
    }
}

• responseBodyV1(): HttpServletResponse를 통해 HTTP 메시지 바디에 직접 응답 메시지를 전달한다.
• responseBodyV2(): HttpEntity를 상속받은 ResponseEntity는 헤더, 바디를 가지며 이에 더해 응답코드를 설정할 수 있다.
• responseBodyV3(): @ResponseBody를 사용하면 view를 사용하지 않고, HTTP 메시지 컨버터를 통해 HTTP 메시지를 직접 입력할 수 있다. ResponseEntity도 같은 방식으로 동작한다.
• responseBodyJsonV1(): ResponseEntity를 반환한다. HTTP 메시지 컨버터를 통해 JSON 형식으로 변환되어 반한된다.
• responseBodyJsonV2()
  • ResponseEntity를 사용하면 HTTP 응답 코드를 설정할 수 있지만, @ResponseBody를 사용하면 설정이 까다롭다. @ResponseStatus(HttpStatus.OK) 처럼 간단하게 설정할 수 있다.
  • 애노테이션이라서 응답 코드를 동적으로 변경할 수는 없다.
  • 프로그램 조건에 따라 동적으로 변경하고자 한다면, ResponseEntity를 사용하면 된다.

@RestController

@Controller 대신 @RestController를 사용하면, 해당 컨트롤러에 모두 @ResponseBody가 적용되는 효과가 있다. 따라서 뷰 템플릿을 사용하는 것이 아닌 HTTP 메시지 바디에 직접 데이터를 입력한다. 이름 그대로 Rest API(HTTP API)를 만들 때 사용하는 컨트롤러이다.

@ResponseBody는 클래스 레벨에 두면 전체 메서드에 적용되는데, @RestController는 내부에 @ResponseBody가 적용되어 있다.

HTTP 메시지 컨버터

여러 애노테이션을 이용해서 JSON, queryString 등을 @RequestBody, @ModelAttribute 등으로 편하게 객체로 변환하여 사용했다. 스프링이 어떻게 객체로 변환을 해주는지는 HTTP 메시지 컨버터에 정답이 있다.

우선 @ResponseBody의 사용 원리는 다음과 같다.

@ResponseBody를 사용하면 HTTP의 body에 문자 내용을 직접 반환하는데, 그림을 보면 viewResolver가 아닌 HttpMessageConverter가 동작한다.

• 기본 문자처리: StringHttpMessageConverter
• 기본 객체처리: MappingJackson2HttpMessageConverter
• byte 처리 등 기타 여러 HttpMessageConverter가 기본으로 등록되어 있다.

여기서 응답할 때 클라이언트의 HTTP Accept 헤더와 서버의 컨트롤러 반환 타입 정보 둘을 조합해서 HttpMessageConverter가 선택된다.

정리하자면, Spring MVC는 다음의 경우 HTTP 메시지 컨버터를 적용한다.

• HTTP 요청: @RequestBody, HttpEntity(RequestEntity)
• HTTP 응답: @ResponseBody, HttpEntity(ResponseEntity)

HTTP 메시지 컨버터 인터페이스

org.springframework.http.converter.HttpMessageConverter

package org.springframework.http.converter;

public interface HttpMessageConverter<T> {
    boolean canRead(Class<?> clazz, @Nullable MediaType mediaType);
    boolean canWrite(Class<?> clazz, @Nullable MediaType mediaType);
    
    List<MediaType> getSupportedMediaTypes();
    
    T read(Class<? extends T> clazz, HttpInputMessage inputMessage) 
                throws IOException, HttpMessageNotReadableException;
    void write(T t, @Nullable MediaType contentType, HttpOutputMessage outputMessage)
                throws IOException, HttpMessageNotWritableException;
}

HTTP 메시지 컨버터는 요청, 응답 둘 다 사용된다.
// 요청 시: JSON -> 객체, 응답 시: 객체 -> JSON

• canRead(), canWrite(): 메시지 컨버터가 해당 클래스, 미디어 타입을 지원하는지 체크
• read(), write(): 메시지 컨버터를 통해서 메시지를 읽고 쓰는 기능

스프링 부트 기본 메시지 컨버터

기본으로 등록되는 컨버터 중 가장 대표적인 것 3가지는 다음과 같다.

0 = ByteArrayHttpMessageConverter
1 = StringHttpMessageConverter
2 = MappingJackson2HttpMessageConverter

스프링 부트는 다양한 메시지 컨버터를 제공하는데, 대상 클래스 타입과 미디어 타입을 체크해서 사용 여부를 결정한다. 만약 만족하지 않으면 다음 메시지 컨버터로 우선순위가 넘어간다.

• ByteArrayHttpMessageConverter: byte[] 데이터를 처리한다.
  • 클래스 타입: byte[], 미디어 타입: */*
  • 요청 예) @RequestBody byte[] data
  • 응답 예) @ResponseBody return byte[] 쓰기 미디어 타입: application/octet-stream
• StringHttpMessageConverter: String 문자로 데이터를 처리한다.
  • 클래스 타입: String, 미디어 타입: */*
  • 요청 예) @RequestBody String data
  • 응답 예) @ResponseBody return "ok" 쓰기 미디어 타입: text/plain
• MappingJackson2HttpMessageConverter: application/json
  • 클래스 타입: 객체 또는 HashMap, 미디어 타입: application/json 관련
  • 요청 예) @RequestBody HelloData data
  • 응답 예) @ResponseBody return helloData 미디어 타입: application/json 관련

HTTP 요청 데이터 읽기

• HTTP 요청이 오면 컨트롤러에서 @RequestBody, HttpEntity 파라미터를 사용한다.
• 메시지 컨버터가 메시지를 읽을 수 있는지 확인하기 위해 canRead()로 지원 여부를 확인한다.
  • 대상 클래스 타입을 지원하는가 (ex. @RequestBody의 대상 클래스 (byte[], String, HelloData))
  • HTTP 요청의 Content-Type 미디어 타입을 지원하는가 (ex. text/plain, application/json, */*)
• canRead() 조건을 만족하면 read() 메소드를 호출해 객체를 생성 및 반환한다.

HTTP 응답 데이터 생성

• 컨트롤러에서 @ResponseBody,HttpEntity로 값이 반환된다.
• 메시지 컨버터가 메시지를 쓸 수 있는지 확인하기 위해 canWrite()를 호출한다.
  • 대상 클래스 타입을 지원하는가 (ex. return의 대상 클래스 (byte[], String, HelloData))
  • HTTP 요청의 Accept 미디어 타입을 지원하는가? 더 정확히는 @RequestMapping의 produces (ex. text/plain, application/json, */*)
• canWrite()를 만족하면 write() 메서드를 호출해 HTTP 응답 메시지 바디에 데이터를 생성한다.

요청 매핑 핸들러 어댑터 구조

스프링 MVC의 구조에서 HTTP 메시지 컨버터는 어디서 사용되는 걸까?

이는 애노테이션 기반의 컨트롤러 @RequestMapping을 처리하는 핸들러 어댑터인 RequestMappingHandlerAdapter (요청 매핑 핸들러 어댑터)에 있다.

RequestMappingHandlerAdapter

ArgumentResolver 인터페이스

스프링 MVC의 애너테이션 기반의 컨트롤러는 HttpServletRequest, Model, @RequestParam, @ModelAttribute, @RequestBody, HttpEntity 까지 다양한 요청 파라미터를 처리하는데 해당 어댑터에선 ArgumentResolver를 호출해서 컨트롤러(핸들러)가 필요로 하는 다양한 파라미터의 값(객체)을 생성한다.

스프링은 30개가 넘는 ArgumentResolver를 기본으로 제공한다.

📌 가능한 파라미터 목록은 다음과 같다. -> Spring Web MVC Method Arguments

ArgumentResolver(HandlerMethodArgumentResolver) 인터페이스는 다음과 같다.

public interface HandlerMethodArgumentResolver {
    boolean supportsParameter(MethodParameter parameter);
    
    @Nullable
    Object resolveArgument(MethodParameter parameter,
                           @Nullable ModelAndViewContainer mavContainer,
                           NativeWebRequest webRequest,
                           @Nullable WebDataBinderFactory binderFactory)
                   throws Exception;
}

1. ArgumentResolver의 supportsParameter() 메소드를 호출해 해당 파라미터를 지원하는지 체크
2. 지원 한다면, resolveArgument() 메소드를 호출해서 실제 객체를 생성한다.
3. 지원하지 않는다면, 다음 ArgumentResolver로 우선순위가 넘어간다.

그리고 직접 이 인터페이스를 확장하여 커스텀한 ArgumentResolver 를 만들 수도 있다.
(ex. login 처리)

ReturnValueHandler

HandlerMethodReturnValueHandler를 줄여서 ReturnValueHandler라 한다. 이 역시 ArgumentResolver와 비슷한데 이것은 응답 값을 변환하고 처리한다.

Controller에서 String으로 뷰 이름을 반환해도 동작하는 이유가 이 ReturnValueHandler 때문이다. 또한 스프링은 10개가 넘는 ReturnValueHandler를 지원한다.
ex) ModelAndView, @ResponseBody, HttpEntity, String

HTTP 메시지 컨버터

HTTP 메시지 컨버터는 어디에 있는걸까? 해당 컨버터가 필요한 상황은 대표적으로 @RequestBody같은 애노테이션인데 다음 구조를 확인해보자. 다음 그림처럼 @RequestBody를 사용하는 컨트롤러가 필요로 하는 파라미터 값에 사용된다.

• 요청의 경우 @RequestBody를 처리하는 ArgumentResolver가 있고, HttpEntity를 처리하는 ArgumentResolver가 있다. 이 ArgumentResolver들이 HTTP 메시지 컨버터를 사용해서 필요한 객체를 생성하는 것이다.
• 응답의 경우 @ResponseBody와 HttpEntity를 처리하는 ReturnValueHandler가 있다. 그리고 여기에서 HTTP 메시지 컨버터를 호출해서 응답 결과를 만든다.

각 사용 케이스는 다음과 같다.

• @RequestBody, @ResponseBody -> RequestResponseBodyMethodProcessor(ArgumentResolver)
• HttpEntity -> HttpEntityMethodProcessor(ArgumentResolver)

확장

스프링은 다음을 모두 인터페이스로 제공한다. 따라서 필요시 언제든지 기능을 확장할 수 있다.

• HandlerMethodArgumentResolver
• HandlerMethodReturnValueHandler
• HttpMessageConverter

대부분은 이미 스프링에서 구현되어 제공하기에 실제로 확장할 일이 많진 않다. 만약 기능 확장을 할 때는 WebMvcConfigurer를 상속받아 스프링 빈으로 등록하면 된다.

@Bean
public WebMvcConfigurer webMvcConfigurer() {
    return new WebMvcConfigurer() {
        @Override
        public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
          // ...
        }
        
        @Override
        public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
          // ...
        }
    
    };
}

References

• 김영한님의 스프링 MVC 1편 - 백엔드 웹 개발 핵심 기술