@RequestParam

@RequestParam은 스프링 MVC에서 HTTP 요청 파라미터를 메서드의 파라미터로 바인딩할 때 사용하는 어노테이션입니다.

기능

• HTTP 요청의 파라미터 값을 메서드의 파라미터로 받아옵니다.
• 쿼리 문자열, 폼 데이터, multipart 요청 등의 파라미터를 처리할 수 있습니다.
• 기본값 설정, 필수 여부 지정, 이름 매핑 등의 기능을 제공합니다.

사용 방법

기본적인 사용 방법은 다음과 같습니다:

import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @GetMapping("/users")
    public List<User> searchUsers(@RequestParam String name) {
        // name 파라미터를 이용한 사용자 검색 로직
        return userService.searchByName(name);
    }
}

주요 특징

1. 타입 변환: 문자열로 들어온 파라미터 값을 자동으로 지정된 타입으로 변환합니다.
2. 필수 값 지정: required 속성을 통해 필수 여부를 지정할 수 있습니다.
3. 기본값 설정: defaultValue 속성으로 파라미터가 없을 때의 기본값을 지정할 수 있습니다.
4. 이름 매핑: 파라미터 이름과 메서드 파라미터 이름이 다를 경우 매핑할 수 있습니다.

고급 사용법

1. 선택적 파라미터

필수가 아닌 선택적 파라미터 처리:

@GetMapping("/users")
public List<User> searchUsers(@RequestParam(required = false) String name) {
    if (name != null) {
        return userService.searchByName(name);
    } else {
        return userService.getAllUsers();
    }
}

2. 기본값 설정

파라미터가 없을 때 사용할 기본값 설정:

@GetMapping("/users")
public List<User> getUsers(@RequestParam(defaultValue = "10") int limit) {
    return userService.getUsers(limit);
}

3. 이름 매핑

파라미터 이름과 메서드 파라미터 이름이 다를 경우:

@GetMapping("/users")
public User getUser(@RequestParam("user_id") Long id) {
    return userService.getUserById(id);
}

4. 멀티값 파라미터

같은 이름의 파라미터가 여러 개 전달될 때:

@GetMapping("/users")
public List<User> getUsersByRoles(@RequestParam List<String> roles) {
    return userService.getUsersByRoles(roles);
}

5. Map으로 모든 파라미터 받기

모든 파라미터를 Map으로 받아올 때:

@PostMapping("/users")
public User createUser(@RequestParam Map<String, String> params) {
    return userService.createUser(params);
}

예외 처리

필수 파라미터가 없거나 타입 변환에 실패할 경우 MissingServletRequestParameterException 또는 MethodArgumentTypeMismatchException이 발생할 수 있습니다. 이를 전역적으로 처리하려면:

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MissingServletRequestParameterException.class)
    public ResponseEntity<String> handleMissingParams(MissingServletRequestParameterException ex) {
        String name = ex.getParameterName();
        return new ResponseEntity<>(name + " parameter is missing", HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
    public ResponseEntity<String> handleTypeMismatch(MethodArgumentTypeMismatchException ex) {
        String name = ex.getName();
        String type = ex.getRequiredType().getSimpleName();
        Object value = ex.getValue();
        String message = String.format("'%s' should be a valid '%s' and '%s' isn't", 
                                        name, type, value);
        return new ResponseEntity<>(message, HttpStatus.BAD_REQUEST);
    }
}

테스트

@RequestParam이 적용된 컨트롤러 메서드를 테스트할 때:

@WebMvcTest(UserController.class)
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void testSearchUsers() throws Exception {
        mockMvc.perform(get("/users").param("name", "John"))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$[0].name").value("John"));
    }
}

주의사항

1. 필수 파라미터: required = true(기본값)인 경우, 파라미터가 없으면 예외가 발생합니다.
2. 타입 변환: 파라미터 값이 지정된 타입으로 변환될 수 없는 경우 예외가 발생합니다.
3. 보안: 사용자 입력을 직접 사용할 때는 적절한 검증과 이스케이프 처리가 필요합니다.

베스트 프랙티스

1. 명확한 네이밍: 파라미터 이름을 명확하고 의미 있게 지정하세요.
2. 기본값 활용: 가능한 경우 defaultValue를 사용하여 견고한 API를 만드세요.
3. 유효성 검사: 필요한 경우 받아온 값에 대해 추가적인 유효성 검사를 수행하세요.
4. 문서화: API 문서에 각 파라미터의 의미, 타입, 필수 여부 등을 명확히 기술하세요.

결론

@RequestParam은 HTTP 요청의 파라미터를 쉽고 유연하게 처리할 수 있게 해주는 강력한 도구입니다. 쿼리 파라미터, 폼 데이터 등 다양한 형태의 입력을 처리할 수 있으며, 스프링의 자동 타입 변환 기능과 결합하여 편리하게 사용할 수 있습니다. 적절히 사용하면 클라이언트와 서버 간의 데이터 교환을 효율적으로 관리할 수 있으며, 견고하고 사용하기 쉬운 API를 개발할 수 있습니다.

연관 포스팅

@PathVariable
@RequestMapping
@RestController
@GetMapping
@Valid