3、鉴权拦截器设计模式：Spring Boot Interceptor/Filter原理、自定义注解实现鉴权、拦截器链的执行顺序与异常处理

在Redis缓存后端鉴权架构中，拦截器（Interceptor）与过滤器（Filter）是承载鉴权逻辑的核心入口。本章深入剖析两者的底层原理、执行顺序、自定义注解鉴权实现，以及拦截器链中的异常处理策略，帮助你在高并发场景下构建稳定、可扩展的鉴权拦截层。

3.1 Filter与Interceptor：核心原理与差异对比

Filter基于Servlet规范，由Servlet容器管理，作用于Web请求的最外层；Interceptor基于Spring AOP，由Spring IoC容器管理，作用于Handler执行前后。两者在鉴权场景中的职责边界如下：

3.2 自定义注解鉴权：从定义到解析

通过自定义注解 + Interceptor的组合，可以实现声明式鉴权，避免在每个Controller方法中重复编写鉴权代码。以下为完整实现链路：

3.2.1 定义鉴权注解

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface RequireAuth {
    String[] roles() default {};
    boolean checkRedisToken() default true;
    long tokenExpireSeconds() default 3600;
}

3.2.2 实现鉴权拦截器

@Component
public class AuthInterceptor implements HandlerInterceptor {

    @Autowired
    private RedisTemplate<String, Object> redisTemplate;

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {
        if (!(handler instanceof HandlerMethod)) {
            return true; // 静态资源直接放行
        }
        HandlerMethod method = (HandlerMethod) handler;
        RequireAuth annotation = method.getMethodAnnotation(RequireAuth.class);
        if (annotation == null) {
            annotation = method.getBeanType().getAnnotation(RequireAuth.class);
        }
        if (annotation == null) {
            return true; // 无注解则放行
        }
        // 1. 从请求头提取Token
        String token = request.getHeader("Authorization");
        if (token == null || token.isEmpty()) {
            throw new AuthException("缺少鉴权令牌");
        }
        // 2. 校验Redis中Token有效性
        String redisKey = "auth:token:" + token;
        if (Boolean.FALSE.equals(redisTemplate.hasKey(redisKey))) {
            throw new AuthException("令牌已过期或无效");
        }
        // 3. 角色校验（若注解指定了角色）
        if (annotation.roles().length > 0) {
            String userRole = (String) redisTemplate.opsForValue()
                .get("auth:role:" + token);
            boolean matched = Arrays.stream(annotation.roles())
                .anyMatch(role -> role.equals(userRole));
            if (!matched) {
                throw new AuthException("权限不足");
            }
        }
        // 4. 续期Token（滑动过期策略）
        if (annotation.checkRedisToken()) {
            redisTemplate.expire(redisKey,
                annotation.tokenExpireSeconds(), TimeUnit.SECONDS);
        }
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request,
                                HttpServletResponse response,
                                Object handler, Exception ex) {
        // 清理线程绑定的Redis连接资源
        RedisConnectionUtils.unbindConnection(
            redisTemplate.getConnectionFactory());
    }
}

3.3 拦截器链的执行顺序与异常处理

当系统中存在多个拦截器时，执行顺序由注册顺序决定。以下为典型的多拦截器鉴权链：

3.3.1 执行顺序规则

1. preHandle 正向执行： 按注册顺序依次执行，若某个拦截器返回 false，后续拦截器及 Controller 不再执行。
2. postHandle 逆向执行： Controller 执行完毕后，按注册逆序执行 postHandle。
3. afterCompletion 始终执行： 无论是否发生异常，均按注册逆序执行，适合资源清理。

3.3.2 异常处理策略

在鉴权拦截器中抛出异常时，推荐使用全局异常处理器统一捕获，避免在拦截器内直接处理响应：

@ControllerAdvice
public class GlobalAuthExceptionHandler {

    @ExceptionHandler(AuthException.class)
    @ResponseBody
    public ResponseEntity<Map<String, Object>> handleAuthException(
            AuthException e) {
        Map<String, Object> result = new HashMap<>();
        result.put("code", 401);
        result.put("message", e.getMessage());
        result.put("timestamp", System.currentTimeMillis());
        return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(result);
    }

    @ExceptionHandler(Exception.class)
    @ResponseBody
    public ResponseEntity<Map<String, Object>> handleGenericException(
            Exception e) {
        Map<String, Object> result = new HashMap<>();
        result.put("code", 500);
        result.put("message", "服务器内部错误");
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(result);
    }
}

3.4 注册拦截器与配置顺序

通过实现 WebMvcConfigurer 接口注册拦截器，注册顺序即执行顺序：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Autowired
    private AuthInterceptor authInterceptor;

    @Autowired
    private LogInterceptor logInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 先注册的拦截器先执行 preHandle
        registry.addInterceptor(logInterceptor)
                .addPathPatterns("/api/**")
                .order(1);  // 显式指定顺序

        registry.addInterceptor(authInterceptor)
                .addPathPatterns("/api/**")
                .excludePathPatterns("/api/auth/login", "/api/auth/register")
                .order(2);
    }
}