@RequestParam Query Parameters

In Java web development, Spring MVC serves as the core framework for building RESTful APIs and handling traditional forms. Its data binding capabilities are crucial among them. Among these, @RequestParam is one of the most commonly used and efficient annotation tools for extracting HTTP request parameters (Query Parameters). It allows developers to automatically map query strings in URLs to Java Bean properties or method arguments in a declarative manner, significantly simplifying controller layer code logic.

Basic Usage: Direct Binding to Method Arguments

The fundamental functionality of @RequestParam is to extract key-value pairs from the URI request path (e.g., ?key=value&other=123) and assign them to corresponding method arguments. Spring MVC automatically parses the URL and populates these variables, eliminating the need for manual string concatenation or regular expression matching code.

Below is a typical Controller example demonstrating how to receive multiple query parameters:

@RestController
public class UserController {

    @GetMapping("/users")
    public List<UserDTO> getUsers(
            @RequestParam String name, 
            @RequestParam Integer age, 
            @RequestParam(required = false) Boolean active
    ) {
        // Retrieve the list of users from the database or cache based on query conditions
        return userRepository.findAllByCondition(name, age);
    }

    private static class UserDTO {
        private Long id;
        private String name;
        private Integer age;
        private boolean active;
        
        // Getter/Setter methods omitted...
    }
}

In the code above, the @RequestParam annotation explicitly instructs Spring MVC to extract data from HTTP request headers or URL query strings. If a parameter is named name, it corresponds to ?name=Tom in the URL; if this parameter is not provided, Spring will throw an exception unless paired with the required = false attribute to allow missing values.

Advanced Features: Default Values, Naming Conventions, and Type Conversion

In actual development scenarios, handling query parameters often involves more complexity, such as setting default values to handle request loss caused by network fluctuations or requiring finer control over specific parameters. In such cases, utilizing advanced attributes of @RequestParam can significantly enhance code robustness.

1. Specify Default Values

When a client fails to pass a required parameter, the system should gracefully degrade rather than throwing an error directly. This can be achieved by setting defaultValue:

@GetMapping("/search")
public String search(
    @RequestParam(defaultValue = "Java", name = "language") 
) {
    return "Searching for: " + language;
}

Here, even if the URL does not pass ?name=..., the method argument will be automatically initialized to the string "Java".

2. Handling Multiple Values and Naming Conflicts

The HTTP protocol allows a key name to appear multiple times (e.g., ?id=1&id=2&type=A&type=B). In such cases, Spring MVC's default behavior is to collect these values into an array or collection rather than overwriting previous ones. Additionally, if the URL contains different parameters with the same name prefix but distinct names (for example, both having a parameter starting with name), they can be distinguished by setting different annotation names:

@GetMapping("/profile")
public Profile getProfile(
    @RequestParam("id") Long userId, 
    @RequestParam String name // This attempts to match the query item named "name", not username
) { ... }

3. Type Conversion and Collection Mapping

@RequestParam supports automatic type inference. If a string "10" is passed in the URL while the method argument type is Integer, Spring MVC will automatically perform implicit conversion. For list-type parameters (e.g., receiving multiple IDs), you can use List.class or specific generic types:

@GetMapping("/items")
public List<Item> getItems(
    @RequestParam String ids // Spring attempts to split "1,2,3" into a string array and then convert it to Integer[]
) { ... }

If you need to receive multiple independent query parameters directly into a collection, use @RequestParam in combination with specific types.

Precautions: Naming Conventions and Potential Pitfalls

Although the functionality of @RequestParam is powerful, certain details must be observed during actual usage to avoid potential runtime errors or logical confusion.

Firstly, the order of parameters does not matter. Spring MVC matches based on parameter names entirely when parsing; therefore, the arrangement order of method formal parameters does not affect the final binding result. Secondly, if a URL lacks a parameter marked as required = true (default value), the controller will throw a MissingRequestParameterException, causing request failure.

Furthermore, when dealing with special characters or complex data structures, it is recommended to manually specify parameter names to avoid ambiguity. For example:

@GetMapping("/data")
public Data getData(
    @RequestParam("filter.age") Integer age, 
    @RequestParam("category.name") String categoryName
) { ... }

Finally, note the difference between @PathVariable and @RequestParam. The former is used to extract parameters from the path (e.g., /users/{id}), while the latter specifically refers to parts of the URL query string. They do not conflict in Spring MVC; however, developers must clearly distinguish usage scenarios to ensure code semantic accuracy.

By reasonably using @RequestParam, Spring MVC can handle complex HTTP request data binding requirements in a concise and type-safe manner, serving as one of the indispensable infrastructures for modern Java web development.