Mastering @BindParam in Spring Boot 3: Seamlessly Map Path and Query Parameters

1. Introduction

Spring provides powerful and flexible support for handling interface parameters in Spring MVC and Spring WebFlux, allowing binding via annotations such as @RequestParam, @PathVariable, @RequestHeader, @RequestBody, etc.

@GetMapping("/{type}/{id}")
public Object bind(Param param) {
    return param;
}
public static record Param(Long id, String type) {}

This interface correctly binds the path variables to the Param object.

2. @BindParam Annotation

2.1 Path Parameters

@GetMapping("/{cate}/{id}")
public Object bindData(Param param) {
    return param;
}
public static record Param(Long id, @BindParam("cate") String type) {}

Here @BindParam maps the path variable cate to the constructor argument type.

2.2 Query Parameters

@GetMapping("/q")
public ResponseEntity<Object> q(Param param) {
    return ResponseEntity.ok(param);
}
public static record Param(@BindParam("pid") Long id,
                           @BindParam("cate") String type) {}

Access the endpoint with /q?pid=888&cate=xxxxooo to see the binding in action.

2.3 Support for @ModelAttribute

@GetMapping("/{cate}/{id}")
public ResponseEntity<Object> q(@ModelAttribute Param param) {
    return ResponseEntity.ok(param);
}
public static record Param(Long id, @BindParam("cate") String type) {}

The @BindParam annotation also works on constructor parameters of a method argument annotated with @ModelAttribute.

2.4 Custom Name Resolver

Define a custom resolver to interpret your own annotation:

public class PackParamNameResolver implements NameResolver {
    public String resolveName(MethodParameter parameter) {
        PackParam packParam = parameter.getParameterAnnotation(PackParam.class);
        if (packParam != null && StringUtils.hasText(packParam.value())) {
            return packParam.value();
        }
        return null;
    }
}

Register the resolver (locally in a controller or globally via @ControllerAdvice):

@InitBinder
public void init(WebDataBinder binder) {
    binder.setNameResolver(new PackParamNameResolver());
}

Usage example with a custom annotation:

@GetMapping("/q")
public ResponseEntity<Object> q(Param param) {
    return ResponseEntity.ok(param);
}
public static record Param(Long id,
                           @PackParam("cate") String type) {}

The custom resolver can be extended to support SpEL expressions, e.g., @PackParam("#{${pack.param.name} + '-1'}").