Spring Boot simplifies building Java applications, and query param handling is a common task in almost every web service. This guide walks through practical patterns and configuration options for reading, validating, and binding request parameters.
You will learn how to map query params to method arguments, use validation, and document behavior clearly. The following reference material and examples support quick adoption and help avoid common mistakes.
| Parameter Source | Binding Approach | Validation | Use Case |
|---|---|---|---|
| Request query string | @RequestParam at method or parameter level | Spring Validation, @Min, @Max, @NotBlank | Search filters, pagination controls |
| Path variable combined with query | @PathVariable + @RequestParam in same handler | Custom validator or @Validated on controller | Resource detail with optional filters |
| Repeated query parameters | List |
@Size, @NotEmpty on collection | Multi-select tags, tag filters |
| Complex types from multiple params | Custom argument resolver or Form object | Group validation, cross-field rules | Advanced search with many options |
Binding Query Params with @RequestParam
The @RequestParam annotation maps individual HTTP query parameters to method arguments in a controller. By default, the parameter name is derived from the method argument, matching the request query key.
You can explicitly set the name, require presence, and provide default values. This approach is ideal for simple types such as String, Integer, Boolean, and their wrapper types.
Simple Example with Required and Default
Using required=false makes the query param optional, while defaultValue supplies a fallback when the param is missing. The method remains clean and focused on business logic.
Handling Repeated and Multi-value Parameters
When a query key appears multiple times, bind to List
Validation annotations such as @Size and constraints on the collection help ensure acceptable input. You can combine this approach with other @RequestParam arguments in the same handler.
Path Variable and Query Param Coordination
Many endpoints use a path variable for the resource identifier and optional query params for filtering or sorting. Declare both @PathVariable and @RequestParam in the same method signature.
This structure keeps URLs expressive while allowing flexible queries. You can apply group validation by placing the controller under @Validated and using method-level constraints.
Complex Binding with Form Objects and Custom Resolvers
For advanced scenarios, create a form object that groups multiple query parameters. Use @InitBinder to register a custom editor or configure field-level formatting.
When standard binding is insufficient, implement a HandlerMethodArgumentResolver to transform request parameters into domain-specific types. This centralizes conversion logic and keeps controllers lightweight.
Recommended Practices for Query Params in Spring Boot
- Use @RequestParam for simple, optional filters and required search keys.
- Employ List or array binding for multi-value parameters like tags or statuses.
- Centralize complex conversion logic with custom argument resolvers.
- Apply validation annotations and global error handling for consistent APIs.
- Document defaults and allowed values in your API specification or comments.
FAQ
Reader questions
How do I make all query parameters optional while still binding them?
Set required=false on each @RequestParam and provide sensible defaults. Alternatively, use a form object and apply @Validated only at the method level, avoiding required flags on individual fields.
Can I bind a query param to a non-String target type such as an enum or date?
Yes, Spring converts automatically when the argument type is not String. For enums, use the enum name; for dates, register a custom converter or use @DateTimeFormat to define the pattern.
What happens if a required query param is missing from the request?
Spring returns a 400 Bad Request with a type exception explaining the missing parameter. You can handle this globally with @ControllerAdvice to produce a consistent error response format.
How can I validate combinations of query parameters, such as range checks between two params?
Use a form object with Bean Validation group sequences or a custom validator annotated with @Constraint. Apply @Validated on the controller and invoke the validator in the method body or via an aspect.