@RequestParam, @PathVariable 차이 완벽 가이드

1. 개요

Spring Boot에서 컨트롤러를 작성할 때, URL 매개변수를 처리하는 방법으로 @RequestParam과 @PathVariable이 있다. 두 애너테이션 모두 클라이언트로부터 전달된 값을 컨트롤러에서 받아 처리하는 역할을 하지만, 사용 방식과 활용 목적이 다르다. 본 문서는 @RequestParam과 @PathVariable의 차이를 정확히 분석하고, 실무에서 최적의 활용법을 제시한다.

2. @RequestParam과 @PathVariable의 기본 개념

2.1. @RequestParam이란?

@RequestParam은 HTTP 요청에서 쿼리 파라미터(Query Parameter)를 추출하는 데 사용된다. 주로 GET 요청에서 많이 활용되며, URL 뒤에 ?를 사용하여 키-값 쌍으로 전달되는 데이터를 받는다.
예제 코드

@RestController
@RequestMapping("/users")
public class UserController {
    
    @GetMapping("/search")
    public String searchUser(@RequestParam String name) {
        return "검색된 사용자: " + name;
    }
}

사용 예시

GET /users/search?name=kim

출력 결과

검색된 사용자: kim

2.2. @PathVariable이란?

@PathVariable은 RESTful URL의 일부를 변수로 사용하여 데이터를 전달할 때 활용된다. 즉, URL 경로에서 값을 추출하는 방식이다.
예제 코드

@RestController
@RequestMapping("/users")
public class UserController {
    
    @GetMapping("/{id}")
    public String getUserById(@PathVariable Long id) {
        return "사용자 ID: " + id;
    }
}

사용 예시

GET /users/100

출력 결과

사용자 ID: 100

반응형

3. @RequestParam과 @PathVariable의 차이점

비교 항목 @RequestParam @PathVariable

데이터 전달 방식	쿼리 스트링(?key=value)	URL 경로(/{value})
HTTP 메서드 지원	주로 GET, POST	주로 GET, DELETE, PUT
필수 여부 지정	required 속성 사용 가능	@PathVariable(required=false) 설정 가능
다중 값 지원	List<String> 또는 String[] 가능	여러 개의 변수 설정 가능

반응형

4. @RequestParam과 @PathVariable의 사용 시점

4.1. @RequestParam이 적절한 경우

• 필터링, 검색, 정렬 등과 같은 비즈니스 로직에서 선택적 데이터 전달이 필요한 경우
• 다중 매개변수를 처리해야 할 경우 (ex. 여러 개의 검색 조건)
• GET, POST 요청에서 주로 사용

예제

@GetMapping("/products")
public List<Product> getProducts(@RequestParam String category, @RequestParam(required = false) String sort) {
    return productService.getProducts(category, sort);
}

호출 예시

GET /products?category=electronics&sort=price

4.2. @PathVariable이 적절한 경우

• 특정 리소스를 식별하는 고유한 값을 전달할 때 (ex. 사용자 ID, 상품 코드)
• RESTful API 경로에서 변수 값을 활용할 때
• 주로 GET, DELETE, PUT 요청에서 사용

예제

@GetMapping("/products/{id}")
public Product getProductById(@PathVariable Long id) {
    return productService.getProductById(id);
}

호출 예시

GET /products/500

반응형

5. @RequestParam과 @PathVariable의 조합 사용

두 애너테이션은 함께 사용할 수도 있다. 예를 들어, 특정 사용자의 주문을 조회할 때 사용자 ID는 @PathVariable로 전달하고, 필터링 조건은 @RequestParam으로 받을 수 있다.
예제

@GetMapping("/users/{id}/orders")
public List<Order> getUserOrders(@PathVariable Long id, @RequestParam(required = false) String status) {
    return orderService.getOrdersByUserId(id, status);
}

호출 예시

GET /users/123/orders?status=shipped

출력 결과

사용자 123의 배송 완료된 주문 목록 반환

반응형

6. @RequestParam과 @PathVariable의 Best Practice

6.1. URL 설계 원칙

• @PathVariable은 고유 리소스를 나타낼 때 사용해야 한다.
• @RequestParam은 선택적이거나 다중 값을 전달할 때 적절하다.

6.2. RESTful API에서의 활용 기준

• 고유 식별자는 @PathVariable 사용 → GET /users/{id}
• 필터링, 검색, 정렬 등 옵션 전달은 @RequestParam 사용 → GET /users?name=kim
• 조합 사용이 필요한 경우 → GET /users/{id}/orders?status=pending

반응형

7. 실전 프로젝트에서의 적용 예시

대규모 전자상거래 사이트에서 상품 및 주문 정보를 효율적으로 관리하기 위해 @PathVariable과 @RequestParam을 함께 사용하는 REST API를 설계할 수 있다.

7.1. 사용자 주문 조회 API

@RestController
@RequestMapping("/orders")
public class OrderController {

    @GetMapping("/{orderId}")
    public Order getOrderById(@PathVariable Long orderId) {
        return orderService.findOrderById(orderId);
    }

    @GetMapping
    public List<Order> getOrders(@RequestParam(required = false) String status) {
        return orderService.findOrdersByStatus(status);
    }
}

7.2. API 사용 예시

1) 특정 주문 조회

GET /orders/1000

2) 주문 상태별 필터링

GET /orders?status=completed

반응형

8. 결론

Spring Boot에서 @RequestParam과 @PathVariable은 각각 다른 목적과 용도로 사용된다. 올바른 API 설계를 위해서는 이 두 애너테이션을 적절히 활용하여 RESTful API의 가독성과 유지보수성을 높이는 것이 중요하다.