Spring @RequestParam으로 요청 파라미터 받기 정리

@RequestParam은 무엇을 받는가

Spring 컨트롤러에서 화면이나 URL로 넘어온 값을 메서드 파라미터로 받을 때 쓰는 것이 @RequestParam이다. 쿼리스트링(?keyword=spring)이나 폼 전송(<input name="keyword">)으로 들어온 값을 자바 변수에 연결해 준다. Spring @RequestParam 사용법의 출발점은 "요청 파라미터 이름과 받을 변수를 어떻게 연결하느냐"다.

검색 화면을 떠올리면 쉽다. 사용자가 검색어를 입력하고 페이지 번호를 넘기면, 그 값들이 keyword, page 같은 이름으로 서버에 전달된다. 컨트롤러는 이 값을 받아 서비스에 넘긴다. 이때 @RequestParam이 다리 역할을 한다.

속성 한눈에 보기

속성	역할	비고
value / name	받을 요청 파라미터 이름	변수명과 다를 때 지정
required	필수 여부 (기본 true)	true인데 값 없으면 400
defaultValue	값이 없을 때 기본값	지정 시 required는 사실상 false

기본 사용법

1. 파라미터명과 변수명이 같을 때

가장 단순한 형태다. 요청 파라미터 이름과 받을 변수 이름이 같으면 그대로 연결된다.

@Controller
public class SearchController {

    // GET /search?keyword=spring
    @GetMapping("/search")
    public String search(@RequestParam String keyword, Model model) {
        model.addAttribute("result", searchService.find(keyword));
        return "search/result";
    }
}

요청의 keyword 값이 메서드의 keyword 변수에 들어온다. 참고로 최근 Spring 버전에서는 이름이 같으면 @RequestParam 자체를 생략해도 동작하는 경우가 있지만, 의도를 명확히 드러내기 위해 붙여 주는 편이 읽기 좋다.

2. 파라미터명과 변수명이 다를 때

요청 이름과 변수명을 다르게 쓰고 싶으면 value(또는 name)로 받을 이름을 지정한다.

// 요청은 search_word 인데 변수는 keyword 로 받고 싶을 때
@GetMapping("/search")
public String search(
        @RequestParam(value = "search_word") String keyword,
        Model model) {
    model.addAttribute("result", searchService.find(keyword));
    return "search/result";
}

이 매핑을 빠뜨리면 값이 안 들어오거나 400 에러가 난다. 화면의 name 속성과 컨트롤러의 받는 이름이 맞는지 확인하는 게 첫 점검 포인트다.

required와 defaultValue로 값 없을 때 처리

1. required로 필수 여부 지정

@RequestParam은 기본적으로 필수다(required=true). 즉 값을 안 보내면 400 에러가 난다. 선택적 파라미터라면 required = false로 풀어 준다.

@GetMapping("/list")
public String list(
        @RequestParam(required = false) String category,
        Model model) {
    // category 가 없으면 null 로 들어옴 → null 체크 필요
    model.addAttribute("items", itemService.find(category));
    return "item/list";
}

required=false로 두면 값이 없을 때 null이 들어온다. 그래서 받는 쪽에서 null 체크가 필요하다. null을 그대로 서비스에 넘겨 NullPointerException이 나는 실수가 자주 나온다.

2. defaultValue로 기본값 주기

값이 없을 때 null 대신 기본값을 넣고 싶으면 defaultValue를 쓴다. 페이지 번호처럼 기본값이 자연스러운 경우에 적합하다.

@GetMapping("/list")
public String list(
        @RequestParam(defaultValue = "1") int page,
        @RequestParam(defaultValue = "10") int size,
        Model model) {
    // page, size 를 안 보내도 1, 10 으로 처리됨
    model.addAttribute("items", itemService.find(page, size));
    return "item/list";
}

defaultValue를 지정하면 값이 없어도 에러가 나지 않고 기본값이 들어가므로, required를 따로 false로 둘 필요가 없다. 숫자 타입(int 등)으로 받을 때는 값이 비거나 숫자가 아니면 형변환 에러가 날 수 있으니, 기본값을 두거나 검증을 함께 고려한다.

여러 값 한 번에 받기 (List, Map)

체크박스처럼 같은 이름으로 여러 값이 넘어오는 경우 List로 받을 수 있다.

// 요청: /delete?ids=1&ids=2&ids=3
@PostMapping("/delete")
public String delete(@RequestParam List<String> ids) {
    itemService.deleteByIds(ids); // [1, 2, 3]
    return "redirect:/item/list";
}

파라미터가 동적으로 여러 개이고 이름을 미리 알 수 없다면 Map으로 한 번에 받을 수도 있다.

// 전달된 모든 파라미터를 Map 으로
@GetMapping("/search")
public String search(@RequestParam Map<String, String> params) {
    // params.get("keyword"), params.get("page") ...
    return "search/result";
}

다만 Map으로 받으면 어떤 파라미터가 들어오는지 코드만으로는 드러나지 않아 가독성이 떨어진다. 받을 값이 정해져 있다면 명시적으로 하나씩 받거나, 뒤에서 다룰 객체 바인딩(@ModelAttribute)을 쓰는 편이 낫다.

@ModelAttribute와의 차이

파라미터가 많아지면 @RequestParam을 일일이 나열하기 번거롭다. 이때 VO/DTO 객체에 한 번에 담는 @ModelAttribute(또는 커맨드 객체)가 대안이다. @RequestParam은 값을 하나씩 받을 때, @ModelAttribute는 폼 전체를 객체로 묶어 받을 때 적합하다. 검색 조건이 두세 개면 @RequestParam, 회원가입 폼처럼 필드가 많으면 객체 바인딩이 깔끔하다. 둘은 용도가 다르므로 상황에 맞춰 고른다.

값이 안 들어오거나 400이 날 때

• 400 Bad Request — required=true인 파라미터를 안 보낸 경우. 선택값이면 required=false나 defaultValue로 푼다.
• 값이 null로만 들어옴 — 화면의 name과 @RequestParam 이름이 다른 경우. 양쪽 이름을 맞춘다.
• 형변환 에러 — int로 받는데 빈 문자열이나 숫자가 아닌 값이 온 경우. defaultValue를 주거나 String으로 받아 검증한다.
• 한글 값 깨짐 — 요청 인코딩 문제. 필터(CharacterEncodingFilter) 등 인코딩 설정을 확인한다.
• List가 안 채워짐 — 같은 name으로 여러 값을 보내는 구조인지 확인한다.

FAQ

Q1. @RequestParam을 안 보내면 왜 400 에러가 나나요?

기본값이 required=true라서 값이 없으면 잘못된 요청으로 처리된다. 선택적 파라미터면 required = false나 defaultValue를 지정한다.

Q2. 파라미터명과 변수명이 달라도 되나요?

된다. @RequestParam(value = "요청이름")으로 받을 파라미터 이름을 지정하면 변수명은 자유롭게 둘 수 있다.

Q3. required=false와 defaultValue를 같이 써야 하나요?

defaultValue를 지정하면 값이 없어도 기본값이 들어가므로 required를 따로 false로 둘 필요가 없다.

Q4. @RequestParam과 @ModelAttribute는 언제 나눠 쓰나요?

값이 두세 개면 @RequestParam으로 하나씩, 폼 필드가 많으면 @ModelAttribute로 객체에 한 번에 담는 게 깔끔하다.

Q5. 체크박스로 여러 값을 받으려면요?

같은 name으로 여러 값을 보내고 @RequestParam List<String>로 받으면 리스트로 들어온다.

정리

Spring @RequestParam 사용법의 핵심은 "요청 파라미터 이름과 받을 변수를 연결하고, 값이 없을 때를 대비하는 것"이다. 이름이 같으면 그대로, 다르면 value로 지정한다. @RequestParam은 기본이 필수라 값을 안 보내면 400이 나므로, 선택값은 required = false나 defaultValue로 풀어 준다. 여러 값은 List나 Map으로 받을 수 있고, 폼 필드가 많으면 @ModelAttribute 객체 바인딩이 더 편하다. 값이 안 들어오면 화면의 name과 받는 이름 일치, required 설정, 인코딩을 순서대로 확인하면 대부분 원인을 좁힐 수 있다.