Implementing a Generic Appkey Whitelist Validation in Spring Boot: AOP, Interceptor, ArgumentResolver, and Filter Approaches

Preface

Faced with endless business demands, the author was assigned a task that forced a deeper understanding of Java, Tomcat, and Spring, culminating in a new perspective on these technologies. The goal is to add a generic appkey whitelist validation to an internal Spring‑Boot‑based web framework, emphasizing extensibility.

Traditional AOP

The first solution uses Spring AOP. An @Aspect class WhitelistAspect defines a pointcut annotated with a custom @Whitelist annotation, and a @Before advice method checkAppkeyWhitelist performs the whitelist check before controller execution.

@Aspect
public class WhitelistAspect {
    @Before(value = "whitelistPointcut() && @annotation(whitelist)")
    public void checkAppkeyWhitelist(JoinPoint joinPoint, Whitelist whitelist) {
        checkWhitelist();
        // joinPoint.getArgs() can retrieve controller method arguments
        // whitelist variable provides annotation parameters
    }

    @Pointcut("@annotation(com.zhenbianshu.Whitelist)")
    public void whitelistPointCut() {}
}

Controllers are annotated with @Whitelist to trigger the check. The approach can be extended by adding attributes such as uid() to the annotation for additional validation criteria.

Interceptor

Spring's HandlerInterceptor offers another way. A WhitelistInterceptor implements the interface and overrides preHandle to inspect the request and annotation, returning true to continue processing.

@Component
public class WhitelistInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        Whitelist whitelist = ((HandlerMethod) handler).getMethodAnnotation(Whitelist.class);
        // whitelist.values(); // use request and whitelist to validate
        return true;
    }
    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {}
    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {}
}

The interceptor is registered via a WebMvcConfigurerAdapter subclass:

@Configuration
public class MvcConfiguration extends WebMvcConfigurerAdapter {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new WhitelistInterceptor()).addPathPatterns("/*").order(1);
    }
}

ArgumentResolver

A custom HandlerMethodArgumentResolver can create an AuthParam object that encapsulates the appkey and performs whitelist validation before the controller method runs.

@Component
public class AuthParamResolver implements HandlerMethodArgumentResolver {
    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.getParameterType().equals(AuthParam.class);
    }
    @Override
    public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer, NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception {
        Whitelist whitelist = parameter.getMethodAnnotation(Whitelist.class);
        // validate whitelist using webRequest and whitelist annotation
        return new AuthParam();
    }
}

It is added to the MVC configuration:

@Configuration
public class MvcConfiguration extends WebMvcConfigurerAdapter {
    @Override
    public void addArgumentResolvers(List
argumentResolvers) {
        argumentResolvers.add(new AuthParamResolver());
    }
}

Filter

At the servlet level, a javax.servlet.Filter can intercept requests before they reach Spring. The filter must invoke chain.doFilter to continue processing.

public class WhitelistFilter implements javax.servlet.Filter {
    @Override
    public void init(FilterConfig filterConfig) throws ServletException {}
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        // perform whitelist check here
        chain.doFilter(request, response);
    }
    @Override
    public void destroy() {}
}

Filter registration is done via a bean:

@Configuration
public class FilterConfiguration {
    @Bean
    public FilterRegistrationBean someFilterRegistration() {
        FilterRegistrationBean registration = new FilterRegistrationBean();
        registration.setFilter(new WhitelistFilter());
        registration.addUrlPatterns("/*");
        registration.setName("whitelistFilter");
        registration.setOrder(1);
        return registration;
    }
}

Summary

All four mechanisms are viable; their invocation order is determined by the underlying technology stack: the servlet Filter runs first, followed by the Spring Interceptor , then the custom ArgumentResolver , and finally the AOP advice. The author reflects on the similarity between these hook‑based approaches and traditional procedural programming, noting the value of understanding each method's trade‑offs.