Spring Web MVC, @Controller 어노테이션 정리

클래스 레벨

Spring Web MVC의 @Controller 클래스에서 클래스 레벨에 명시 가능한 어노테이션은 아래와 같다.

• @ResponseBody: 모든 메써드의 리턴 오브젝트를 적절한 형태로 변환 후 HTTP 응답 메시지의 바디에 담아 반환한다. (오브젝트에서 바디로의 실제 변환은 HttpMessageConverter 인터페이스의 각 구현 클래스들이 수행한다. 예를 들면 String 리턴 타입은 StringHttpMessageConverter가 변환을 담당한다.) 클래스 레벨에 명시하면 View로의 반환을 완전히 배제하기 때문에 REST API 구현시 적합하다.




• @RestController: @Controller에 위에 설명한 @ResponseBody를 추가한 효과를 가진다. REST API 구현을 염두한 축약형 어노테이션이다.




• @RequestMapping: 응답을 수행할 HTTP 요청을 명시할 수 있다.

  • path (String, String[]): 요청 URI를 명시한다. 배열을 통한 복수개의 요청 URI를 지정할 수 있다. 클래스 레벨에 명시한 값은 모든 메써드 레벨에 명시한 path 값 앞에 붙어 접두어 역할을 한다.

@RequestMapping("/v1/players")

• @PropertySource: 프라퍼티 소스를 명시할 수 있다. 필드 레벨에서 @Value 등을 통해 클래스 레벨에서 명시한 프라퍼티 소스의 값을 주입할 수 있다.

// ROOT CLASSPATH(/src/main/java/resources)에 위치한 some.properties를 프라퍼티 소스로 명시한다.
@PropertySource("classpath:/some.properties")

클래스 필드 레벨

필드 레벨에 명시 가능한 어노테이션은 아래와 같다.

• @Autowired: 적합한 이름의 스프링 빈을 자동으로 주입한다. 명백하게 1개의 스프링 빈만 존재할 경우 사용한다.
• @Resource: 지정한 이름의 스프링 빈을 주입한다. 같은 타입의 스프링 빈이 2개 이상 존재할 경우 사용한다.
  • name (String): 주입할 스프링 빈의 이름이다.
• @Value: 시스템 환경 변수, Java 환경 변수, Spring 환경 변수, 프라퍼티 리소스 상수 등의 값을 주입한다.

메써드 레벨

• @RequestMapping: 메써드가 어떤 HTTP 요청을 처리할 것인가를 작성한다. (최근에는 요청 메써드에 따라 축약형인 @GetMapping, @PostMapping, @PutMapping, @DeleleMapping을 더 선호하는 편이다.) 구체적인 작성 예는 아래와 같다.

@RequestMapping(

  // HTTP URI가 "/users"인 것만 처리한다. 만약 앞서 클래스 레벨에서 "/v1"이 명시되었다면 "/v1/users"를 처리하게 된다.
  path = "/users",

  // 시스템 환경 변수, Java 환경 변수, Spring 환경 변수, 프라퍼티 리소스 상수 로부터 group 파라메터를 받아 요청 주소를 완성한다.
  // @Value 와 동일한 효과를 가진다.
  path = "\${group}/users",

  // HTTP 요청 메써드가 "POST"인 것만 처리한다.
  method = RequestMethod.POST,

  /**
   * HTTP 요청 헤더가 "Content-Type: application/json;charset=UTF-8"인 것만 처리한다.
   * 다른 값이 들어올 경우 org.springframework.web.HttpMediaTypeNotSupportedException을 발생시킨다.
   * HTTP 요청 헤더에 명시된 Content-Type은 HTTP 요청 바디의 형식을 의미한다. 즉, 서버에서는 JSON 형식의 바디만 처리하겠다는 의미이다.
   * 참고로 GET 요청은 바디를 가지지 않으므로 아래 파라메터를 명시할 필요가 없다.
   */
  consumes = MediaType.APPLICATION_JSON_UTF8_VALUE,

  /**
   * HTTP 응답 헤더로 "Content-Type: application/json;charset=UTF-8"을 반환한다.
   * 생략할 경우 메써드 리턴 타입에 따라 Content-Type을 자동으로 판단하여 반환한다.
   */
  produces = MediaType.APPLICATION_JSON_UTF8_VALUE
)

메써드 아규먼트 레벨

• 특정 어노테이션 없이 POJO 클래스를 아규먼트로 명시하면 HTTP 요청 메시지의 QueryString 문자열을 변환하여 저장한다.


• @Valid: JSR-303 (Bean Validation) 스펙에 명시된 어노테이션으로 요청 파라메터에 대한 유효성 검사가 가능하다. 유효성 검사 실패시 org.springframework.validation.BindException이 발생한다. 대상 아규먼트는 기본 타입 및 POJO 타입 모두 가능하다.


• @RequestBody: HTTP 요청 메시지의 BODY를 변환하여 담을 아규먼트 앞에 명시한다. HTTP 스펙에 따라 GET 이외의 메써드에서만 명시 가능하다. (무시하고 명시할 경우 org.springframework.http.converter.HttpMessageNotReadableException이 발생한다.) 한편 앞서 설명한 @Valid를 추가로 명시할 수 있다. 유효성 검사 실패시 org.springframework.web.bind.MethodArgumentNotValidException을 발생시킨다.