Master Custom HandlerMapping in Spring Boot: Header‑Based Routing with getCustomMethodCondition

Environment: SpringBoot 2.7.12

Introduction

In Spring MVC, HandlerMapping maps HTTP requests to handler methods. By overriding getCustomMethodCondition() you can provide custom matching logic, such as checking a header value.

1. Custom Request Matching

Spring MVC allows custom request matching via RequestMappingHandlerMapping#getCustomMethodCondition. The framework already provides several RequestCondition implementations (see image).

2. Custom Matching Condition

public class CustomRequestCondition implements RequestCondition<CustomRequestCondition> {
    private static final String X_TOKEN_NAME = "x-token";
    private Method method;
    public CustomRequestCondition(Method method) {
        this.method = method;
    }
    @Override
    public CustomRequestCondition combine(CustomRequestCondition other) {
        return new CustomRequestCondition(other.method);
    }
    @Override
    public CustomRequestCondition getMatchingCondition(HttpServletRequest request) {
        AKF akf = method.getAnnotation(AKF.class);
        return akf != null ? buildToken(request, akf) : null;
    }
    @Override
    public int compareTo(CustomRequestCondition other, HttpServletRequest request) {
        return 0;
    }
    private CustomRequestCondition buildToken(HttpServletRequest request, AKF akf) {
        String xToken = request.getHeader(X_TOKEN_NAME);
        if (xToken == null || xToken.length() == 0) {
            return null;
        }
        return xToken.equals(akf.value()) ? this : null;
    }
}

3. Configure Custom HandlerMapping

public class CustomMethodConditionRequestHandlerMapping extends RequestMappingHandlerMapping {
    @Override
    protected RequestCondition<?> getCustomMethodCondition(Method method) {
        return new CustomRequestCondition(method);
    }
}

4. Register the Custom Mapping

@Component
public class CustomEndpointConfig implements WebMvcRegistrations {
    @Override
    public RequestMappingHandlerMapping getRequestMappingHandlerMapping() {
        return new CustomMethodConditionRequestHandlerMapping();
    }
}

5. Test Controller

@RestController
@RequestMapping("/conditions")
public class CustomMethodConditionController {
    @GetMapping("/index")
    public Object index() {
        return "custom method condition success";
    }
    @GetMapping("/index")
    @AKF
    public Object x() {
        return "x method invoke";
    }
    @GetMapping("/index")
    @AKF("x1")
    public Object x1() {
        return "x1 method invoke";
    }
    @GetMapping("/index")
    @AKF("x2")
    public Object x2() {
        return "x2 method invoke";
    }
}

Only endpoints annotated with @AKF and whose request header contains a matching x-token value are reachable; others return 404.

6. Underlying Principle

During request processing Spring looks up a HandlerMethod by iterating over registered RequestMappingInfo objects, applying standard conditions (methods, params, headers) and finally the custom condition supplied by CustomRequestCondition. If no condition matches, a 404 response is returned.

By implementing getCustomMethodCondition() you gain fine‑grained control over which requests are handled, enabling header‑based routing or other custom logic.

Done!