Spring 拦截器与统一响应异常处理实战

1.2 注册配置

定义好拦截器后，需通过 WebMvcConfigurer 进行注册。这里要注意路径匹配规则，避免误伤静态资源。

@Configuration
public class WebConfig implements WebMvcConfigurer {
    
    @Autowired
    private LoginInterceptor loginInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(loginInterceptor)
                .addPathPatterns("/**") // 拦截所有路径
                .excludePathPatterns("/user/login", "/html/**", "/css/**", "/js/**"); // 排除登录页和静态资源
    }
}

路径匹配说明

• /*：一级路径，如 /user 匹配，但 /user/login 不匹配。
• /**：任意级路径，匹配所有子路径。
• /book/*：/book 下的一级路径。
• /book/**：/book 下的所有子路径。

1.3 实战：登录校验

结合 Session 实现具体的登录拦截逻辑。注意，这里只需关注 preHandle，因为后续步骤通常不需要阻断。

@Component
@Slf4j
public class LoginInterceptor implements HandlerInterceptor {
    
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        HttpSession session = request.getSession();
        UserInfo userInfo = (UserInfo) session.getAttribute("SESSION_USER_KEY");
        
        if (userInfo != null) {
            log.info("登录成功");
            return true; // 放行
        }
        
        // 未登录，设置状态码并拦截
        response.setStatus(401);
        return false;
    }
}

二、统一数据返回格式

除了拦截，后端还常需要统一返回给前端的 JSON 结构（例如统一的 Result<T> 对象）。手动在每个 Controller 返回时封装很繁琐，Spring Boot 提供了 @ControllerAdvice + ResponseBodyAdvice 组合拳。

2.1 快速上手

添加注解并实现接口，重点处理 String 类型的序列化问题。

@ControllerAdvice
public class ResponseAdvice implements ResponseBodyAdvice<Object> {
    
    @Autowired
    private ObjectMapper objectMapper;

    // 判断是否处理该方法的返回值
    @Override
    public boolean supports(MethodParameter returnType, Class converterType) {
        return true;
    }

    // 写入响应体之前调用
    @SneakyThrows
    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
        // 如果已经是 Result 类型，直接返回，避免重复封装
        if (body instanceof Result<?>) {
            return body;
        }
        
        // String 类型需要特殊处理，否则会被当作普通字符串而非 JSON
        if (body instanceof String) {
            return objectMapper.writeValueAsString(Result.success(body));
        }
        
        // 其他类型统一包装
        return Result.success(body);
    }
}

注意： 当返回类型为 String 时，必须手动序列化，否则前端收到的可能是一个包裹了引号的字符串，而不是 JSON 对象。

三、统一异常处理

业务逻辑难免出错，与其让浏览器显示堆栈信息，不如统一捕获异常并返回友好的错误提示。使用 @ControllerAdvice 配合 @ExceptionHandler 即可。

@ControllerAdvice
@ResponseBody
public class ErrorAdvice {
    
    // 捕获所有 Exception
    @ExceptionHandler(Exception.class)
    public Object handleException(Exception e) {
        return Result.fail(e.getMessage());
    }

    // 针对特定异常自定义处理
    @ExceptionHandler(NullPointerException.class)
    public Object handleNPE(NullPointerException e) {
        return Result.fail("发生空指针异常:" + e.getMessage());
    }
}

3.1 执行顺序关键点

理解这三者的执行顺序对调试至关重要：

1. 请求进入：先经过拦截器的 preHandle。
2. 业务执行：Controller 方法运行。若抛出异常，直接进入异常处理阶段；若正常，返回数据。
3. 异常捕获：@ExceptionHandler 优先于 ResponseBodyAdvice 捕获异常。如果 Controller 内部已 try-catch 处理，则不会触发全局异常处理器。
4. 数据封装：无论是正常返回的数据，还是异常处理器返回的 Result 对象，都会进入 ResponseBodyAdvice.beforeBodyWrite。因此，我们在 beforeBodyWrite 中要判断是否已是 Result 类型，防止二次封装。

这样一套组合下来，既保证了接口的安全性，又确保了前后端交互格式的规范性。