Spring Boot 控制 Controller 接口的4种方式，哪种更适合你?

环境：SpringBoot3.4.2

1. 简介

动态控制接口的可用性是常见的需求，例如灰度发布、功能降级、紧急熔断等场景。基于 Spring Boot 我们可以通过多种灵活的方式来实现Controller接口的动态开关，包括基于AOP和非AOP的方案，以满足不同粒度和实时性的需求。

AOP方案（如自定义注解+切面）适用于方法级别的细粒度控制，结合配置中心（如Nacos）可实现运行时动态调整。非AOP方案（如拦截器、条件装配、动态路由）则适用于请求级或Controller级的控制，其中拦截器适合请求前置处理，条件装配（@ConditionalOnProperty）适用于启动时静态开关，而动态路由则能在URL匹配阶段进行高效拦截。此外，结合Spring Cloud Config或Actuator端点，可实现配置的实时刷新和远程管理。

选择合适的方案需综合考虑动态生效需求、实现复杂度及性能影响。接下来，我将介绍4种实现方案。

2.实战案例

2.1 方案1：基于@ConditionalOnProperty

该方案利用Spring Boot的 @ConditionalOnProperty 条件装配机制，在应用启动时根据配置文件（如application.yml）决定是否注册Controller，适用于无需运行时动态调整的场景。如下示例：

@RestController  
@ConditionalOnProperty(name = "pack.features.users.enabled", havingValue = "true")  
public class UserController {
}  

当配置文件中的
pack.features.users.enabled 配置为true后，Spring才会注册UserController接口。

优点：

• 零编码，直接依赖Spring原生支持
• 启动时确定，避免运行时检查开销

缺点：

• 需重启生效，无法动态调整
• 粒度较粗，仅支持类/Bean级别控制

2.2 基于AOP实现

通过自定义注解（如 @FeatureToggle ）标记需控制的接口，结合AOP动态拦截请求，高级点我们结合配置中心（如Nacos）实时判断是否放行。支持方法级细粒度控制，无需重启即可生效，适合灰度发布、熔断降级等场景。

自定义注解

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface FeatureToggle {


  /**功能名称（用于关联配置）*/
  String featureName() ;
  /**关闭时的提示信息*/
  String defaultError() default "服务不可用" ;
}

定义切面

@Aspect
@Component
public class FeatureToggleAspect {


  private static final String PREFIX = "pack.features." ;
  private static final String SUFFIX = ".enabled" ;


  private final Environment env;
  public FeatureToggleAspect(Environment env) {
    this.env = env;
  }
  @Pointcut(value = "@within(toggle) || @annotation(toggle)")
  public void matchAnnotatedClassOrMethod(FeatureToggle toggle) {}


  @Around("matchAnnotatedClassOrMethod(toggle)")
  public Object checkFeature(ProceedingJoinPoint pjp, FeatureToggle toggle) throws Throwable {
    String propertyKey = null ;
    if (toggle == null) {
      toggle = AopUtils.getTargetClass(pjp.getTarget()).getAnnotation(FeatureToggle.class) ;
    }
    if (toggle == null) {
      return pjp.proceed() ;
    }
    propertyKey = PREFIX + toggle.featureName() + SUFFIX ;
    boolean isEnabled = Boolean.parseBoolean(env.getProperty(propertyKey, "false")) ;
    if (!isEnabled) {
      throw new RuntimeException(toggle.defaultError()) ;
    }
    return pjp.proceed() ;
  }
}

该切面支持类和方法级别的。需要注意的是这里一定要判断toggle是否为空情况。

使用示例：

@RestController
@RequestMapping("/users")
@FeatureToggle(featureName = "user")
public class UserController {
  @FeatureToggle(featureName = "user.query")
  @GetMapping("/query")
  public ResponseEntity<?> query() {
    return ResponseEntity.ok("query...") ;
  }


  @GetMapping("/create")
  public ResponseEntity<?> create() {
    return ResponseEntity.ok("create...") ;
  }
}

配置文件

pack:
  features:
    user:
      enabled: false
    user.query:
      enabled: true

运行结果

此种方式，解耦性好，支持动态刷新，注解配置灵活。如果你需要了解动态刷新功能，那么请参考下面文章：

技术专家！Spring AOP + Nacos + Prometheus 实现动态限流及实时监控

技巧！Spring Boot 动态刷新及实时监控配置文件的变化

2.3 基于拦截器实现

通过实现HandlerInterceptor前置拦截请求，结合配置动态控制接口访问。在请求进入Controller前进行开关判断。

定义配置属性类

@Component
@ConfigurationProperties(prefix = "pack.features")
public class FeatureProperties {
  // 存储所有功能开关状态
  private final Map<String, State> toggle = new ConcurrentHashMap<>();
  // 检查功能是否启用
  public boolean isEnabled(String featureName) {
    State state = toggle.get(featureName) ;
    if (state == null) {
      return false ;
    }
    return state.enabled() ;
  }
  public static record State(Boolean enabled) {}
  public Map<String, State> getToggle() {
    return toggle;
  }
}

配置文件

pack:
  features:
    toggle:
      user:
        enabled: false
      '[user.query]':
        enabled: true

定义拦截器

@Component
public class FeatureToggleInterceptor implements HandlerInterceptor {
  private final FeatureProperties featureProperties ;
  public FeatureToggleInterceptor(FeatureProperties featureProperties) {
    this.featureProperties = featureProperties;
  }
  @Override
  public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
    if (handler instanceof HandlerMethod) {
      HandlerMethod hm = (HandlerMethod) handler;
      // 检查方法或类上的注解
      FeatureToggle toggle = hm.getMethodAnnotation(FeatureToggle.class);
      if (toggle == null) {
        toggle = hm.getBeanType().getAnnotation(FeatureToggle.class);
      }
      if (toggle != null && !featureProperties.isEnabled(toggle.featureName())) {
        throw new RuntimeException(toggle.defaultError()) ;
      }
    }
    return true;
  }
}

注册拦截器

@Component
public class WebConfig implements WebMvcConfigurer {
  private final FeatureToggleInterceptor toggleInterceptor;
  public WebConfig(FeatureToggleInterceptor toggleInterceptor) {
    this.toggleInterceptor = toggleInterceptor;
  }
  @Override
  public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(toggleInterceptor).addPathPatterns("/**") ;
  }
}

最终执行效果与上面的AOP一样。

优点：避免AOP开销，适合URL级管控。

2.4 自定义HandlerMapping

通过自定义
RequestMappingHandlerMapping 在路由匹配阶段动态控制请求，根据配置决定是否返回处理器。相比拦截器更底层，直接在Spring MVC路由层拦截。如下代码示例：

public class PackHandlerMapping extends RequestMappingHandlerMapping {
  private final FeatureProperties featureProperties;
  public PackHandlerMapping(FeatureProperties featureProperties) {
    this.featureProperties = featureProperties;
  }
  @Override
  protected HandlerMethod getHandlerInternal(HttpServletRequest request) throws Exception {
    HandlerMethod handler = super.getHandlerInternal(request);
    if (handler != null) {
      FeatureToggle toggle = handler.getMethodAnnotation(FeatureToggle.class);
      if (toggle == null) {
        toggle = handler.getBeanType().getAnnotation(FeatureToggle.class) ;
      }
      if (toggle != null && !featureProperties.isEnabled(toggle.featureName())) {
        return null ;
      }
    }
    return handler;
  }
}

注册处理器

@Component
public class HandlerConfig implements WebMvcRegistrations {
  private final FeatureProperties featureProperties ;
  public HandlerConfig(FeatureProperties featureProperties) {
    this.featureProperties = featureProperties;
  }
  @Override
  public RequestMappingHandlerMapping getRequestMappingHandlerMapping() {
    return new PackHandlerMapping(featureProperties) ;
  }
}

运行效果

此种方式，在路由匹配阶段控制，性能较好。