Spring Boot에서 @RequestParam으로 배열과 리스트 받는 방법 완벽 정리

 

Spring Boot 애플리케이션을 개발하다 보면, 클라이언트로부터 다수의 값을 한 번에 받아야 하는 경우가 종종 발생합니다. 예를 들어, 검색 필터로 여러 개의 카테고리를 선택하거나, 특정 ID 목록을 넘겨받아야 할 때 말이죠. 이럴 때 유용하게 사용할 수 있는 것이 바로 @RequestParam입니다.

이번 포스팅에서는 Spring에서 @RequestParam을 이용해 배열(Array) 또는 리스트(List) 형태의 데이터를 처리하는 방법을 예제 중심으로 자세히 알아보겠습니다. 또한 실무에서 자주 마주치는 문제 상황과 해결 팁도 함께 소개합니다.

---

📌 1. @RequestParam이란?

먼저 @RequestParam에 대해 간단히 짚고 넘어가겠습니다.

Spring MVC에서 @RequestParam은 HTTP 요청의 쿼리 파라미터, 폼 데이터 등을 메서드 파라미터로 바인딩할 때 사용하는 어노테이션입니다. 기본적으로 GET, POST 메서드 모두에서 사용 가능하며, 단일 값뿐 아니라 복수의 값(즉, 배열이나 리스트)도 처리할 수 있습니다.

예:

@GetMapping("/example")
public String example(@RequestParam String name) {
    return "이름은: " + name;
}

요청: GET /example?name=홍길동

---

📌 2. 배열 형태로 @RequestParam 값 받기

여러 개의 값을 배열로 받아야 하는 상황은 아주 흔합니다. 예를 들어, 체크박스로 여러 값을 선택하거나 특정 ID 목록을 배열로 전달받고자 할 때입니다.

✅ 예제 코드: 배열로 받기

@GetMapping("/request-param")
public String getRequestParamArray(@RequestParam String[] values) {
    return Arrays.toString(values);
}

위 메서드는 values라는 이름의 파라미터를 배열로 받아 처리합니다. 이때 values는 쿼리 파라미터에서 동일한 키를 여러 번 사용하여 전달됩니다.

🧪 요청 예시

GET http://localhost:8080/request-param?values=123&values=456&values=789

이 요청은 서버에서 다음과 같이 처리됩니다:

[123, 456, 789]

⚠️ 주의사항

• 파라미터 이름을 메서드의 @RequestParam 변수명과 일치시켜야 합니다.
• 순서는 클라이언트가 전달한 순서를 유지합니다.
• 값이 하나일 경우도 배열로 처리됩니다. (?values=100 → [100])

---

📌 3. 리스트 형태로 @RequestParam 값 받기

Spring에서는 배열뿐 아니라 List 형태로도 바로 파라미터를 받을 수 있습니다. 타입은 제네릭을 통해 String, Integer, Long 등 다양한 형태로 지정 가능합니다.

✅ 예제 코드: 리스트로 받기

@GetMapping("/request-param/list")
public String getRequestParamList(@RequestParam List<String> values) {
    return values.toString();
}

🧪 요청 예시

GET http://localhost:8080/request-param/list?values=apple&values=banana&values=orange

결과:

[apple, banana, orange]

✅ Integer 타입으로 받기

@GetMapping("/request-param/ints")
public String getRequestParamIntList(@RequestParam List<Integer> ids) {
    return ids.toString();
}

GET /request-param/ints?ids=1&ids=2&ids=3
→ [1, 2, 3]

---

🧠 실무에서 유용한 팁 5가지

1. 파라미터 이름이 다를 때는 name 속성 지정

@GetMapping("/filter")
public String filter(@RequestParam(name = "category") List<String> categories) {
    return categories.toString();
}

→ 요청: GET /filter?category=book&category=movie

2. 파라미터가 누락됐을 경우 디폴트 값 지정하기

@GetMapping("/default")
public String defaultValue(@RequestParam(defaultValue = "none") String name) {
    return name;
}

→ GET /default 요청 시 "none" 반환

3. 값이 없으면 예외 발생 방지 (required = false)

@GetMapping("/optional")
public String optional(@RequestParam(required = false) List<String> tags) {
    return tags != null ? tags.toString() : "태그 없음";
}

→ GET /optional 요청 시 에러 없이 처리 가능

4. 리스트의 길이가 너무 길면?

쿼리 파라미터의 길이에 제한이 있을 수 있으므로, 긴 리스트를 전달할 땐 POST 방식 + @RequestBody를 사용하는 것이 더 안정적입니다.

@PostMapping("/submit")
public String submit(@RequestBody List<String> items) {
    return items.toString();
}

5. List 대신 Set도 가능

중복값을 허용하지 않아야 하는 경우, Set으로 받는 것도 가능합니다.

@GetMapping("/set")
public String getSet(@RequestParam Set<String> names) {
    return names.toString();
}

---

📦 추가: 프론트엔드에서 배열 보내는 방법

✅ JavaScript (Axios 예제)

axios.get('/request-param', {
  params: {
    values: ['one', 'two', 'three']
  }
});

요청 URL:

GET /request-param?values=one&values=two&values=three

---

🔍 요약 정리

구분 코드 예시 요청 예시

배열	String[] values	?values=1&values=2
리스트	List<String> values	?values=a&values=b
정수 리스트	List<Integer> ids	?ids=100&ids=200
세트	Set<String> keywords	?keywords=java&keywords=spring

---

✨ 마무리하며

Spring의 @RequestParam은 간단한 쿼리 파라미터부터 다중 선택 값 처리까지 아주 유용한 기능입니다. 배열이나 리스트로 파라미터를 받을 때는 단순히 타입만 맞춰주면 Spring이 자동으로 바인딩해주기 때문에, 복잡한 파싱 로직 없이도 개발 효율을 높일 수 있습니다.

단, 값이 많아질 경우에는 GET 방식의 한계점도 고려해야 하며, 적절히 POST + @RequestBody 방식과 병행해 사용하는 것이 좋습니다.