Spring Boot：控制器类上的自定义@Toggle注解引发处理器映射识别异常

这个问题我之前也遇到过，核心原因是你的自定义注解处理逻辑没有覆盖类级别的场景——要么是注解本身的元注解配置不全，要么是拦截/处理器映射逻辑只处理了方法上的注解，导致DispatcherServlet要么识别不到带类级@Toggle的Controller，要么拦截逻辑没生效。下面分场景给你具体解决方案：

1. 先确认自定义@Toggle注解的元注解配置 #

首先检查你的@Toggle注解是否支持类级别标注，这是基础：

@Target({ElementType.TYPE, ElementType.METHOD}) // 必须包含ElementType.TYPE，支持类级别
@Retention(RetentionPolicy.RUNTIME) // 运行时必须能被反射读取
public @interface Toggle {
    // 示例配置：比如开关状态，可根据你的需求调整
    boolean enabled() default true;
}

如果之前@Target只写了ElementType.METHOD，那类上的注解根本不会被JVM识别，自然会出问题。

2. 针对拦截器场景：同时处理类/方法级别的注解 #

如果你的@Toggle是通过HandlerInterceptor实现请求拦截，那之前的逻辑大概率只检查了方法上的注解，没处理类上的。修改拦截器逻辑，先检查类级别注解，再用方法注解覆盖类注解的配置：

@Component
public class ToggleInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        if (handler instanceof HandlerMethod handlerMethod) {
            // 1. 获取类级别@Toggle注解
            Toggle classToggle = handlerMethod.getBeanType().getAnnotation(Toggle.class);
            // 2. 获取方法级别@Toggle注解（方法注解优先级高于类注解）
            Toggle methodToggle = handlerMethod.getMethodAnnotation(Toggle.class);
            
            // 确定生效的注解：方法注解优先，没有则用类注解
            Toggle effectiveToggle = methodToggle != null ? methodToggle : classToggle;

            if (effectiveToggle != null) {
                // 按你的逻辑判断是否阻止请求：比如enabled为false时返回404/403
                if (!effectiveToggle.enabled()) {
                    response.sendError(HttpServletResponse.SC_SERVICE_UNAVAILABLE, "API is toggled off");
                    return false;
                }
            }
        }
        return true;
    }
}

然后确保拦截器正确注册：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    private final ToggleInterceptor toggleInterceptor;

    public WebMvcConfig(ToggleInterceptor toggleInterceptor) {
        this.toggleInterceptor = toggleInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(toggleInterceptor).addPathPatterns("/**");
    }
}

3. 自定义RequestMappingHandlerMapping场景：不要错误排除类级注解的Controller #

如果你的逻辑是通过重写RequestMappingHandlerMapping来筛选处理器，那可能之前的isHandler方法错误排除了带类级@Toggle的Controller。正确的做法是：保留Spring默认的处理器判断逻辑（类上有@Controller/@RestController），再结合你的@Toggle逻辑：

@Configuration
public class CustomRequestMappingHandlerMapping extends RequestMappingHandlerMapping {

    @Override
    protected boolean isHandler(Class<?> beanType) {
        // 先判断是否是Spring的Controller类
        boolean isSpringController = AnnotationUtils.findAnnotation(beanType, Controller.class) != null
                || AnnotationUtils.findAnnotation(beanType, RestController.class) != null;
        
        // 如果你的逻辑是「只有带@Toggle的Controller才作为处理器」，则加上下面的判断
        // boolean hasToggleAnnotation = AnnotationUtils.findAnnotation(beanType, Toggle.class) != null
        //         || Arrays.stream(beanType.getDeclaredMethods()).anyMatch(m -> AnnotationUtils.findAnnotation(m, Toggle.class) != null);
        // return isSpringController && hasToggleAnnotation;
        
        // 如果你的逻辑是「所有Controller都作为处理器，只是通过@Toggle控制是否拦截」，则直接返回默认判断
        return isSpringController;
    }
}

然后注册这个自定义的HandlerMapping：

@Configuration
public class WebConfig {

    @Bean
    public RequestMappingHandlerMapping customRequestMappingHandlerMapping() {
        return new CustomRequestMappingHandlerMapping();
    }
}

4. 日志排查辅助 #

如果还是有问题，开启Spring Web的DEBUG日志，能清晰看到DispatcherServlet查找处理器的全过程：

# application.yml
logging:
  level:
    org.springframework.web: DEBUG
    org.springframework.web.servlet.mvc.method.annotation: DEBUG

你会看到类似RequestMappingHandlerMapping筛选候选Bean、匹配处理器方法的日志，能快速定位是类没被识别为处理器，还是拦截逻辑没触发。

内容的提问来源于stack exchange，提问作者Karthick Selvaraj