在Java Web项目尤其是Spring MVC或Spring Boot项目中，用户权限拦截是控制接口访问权限、保障系统数据安全的重要手段，基于HandlerInterceptor拦截器实现鉴权逻辑是业内常用的成熟方案，不需要依赖额外的安全框架就能满足大部分项目的权限管控需求。
HandlerInterceptor核心方法解析
HandlerInterceptor是Spring MVC提供的拦截器接口，包含三个核心方法，分别对应请求处理的不同阶段，开发者可以根据鉴权需求选择合适的方法实现逻辑。
- preHandle：在控制器方法执行之前调用，返回true则放行请求，返回false则中断请求，是最常用的鉴权逻辑实现位置。
- postHandle：在控制器方法执行之后、视图渲染之前调用，一般用于修改响应数据，很少用于权限相关逻辑。
- afterCompletion：在整个请求结束之后调用，一般用于资源清理，和权限拦截关联度较低。
基础鉴权拦截器实现
首先我们需要自定义一个拦截器类，实现HandlerInterceptor接口，在preHandle方法中编写登录状态和权限校验逻辑，以下是一个基础的实现示例。
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.ModelAndView;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;
public class AuthInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
// 获取当前请求的session
HttpSession session = request.getSession(false);
// 校验session中是否存在登录用户信息
if (session == null || session.getAttribute("loginUser") == null) {
// 未登录，返回401状态码并提示未授权
response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
response.setContentType("application/json;charset=UTF-8");
response.getWriter().write("{"code":401,"msg":"用户未登录，请先登录"}");
return false;
}
// 登录状态校验通过，放行请求
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 {
// 不需要额外处理，空实现即可
}
}
拦截器注册与白名单配置
自定义拦截器编写完成后，需要将其注册到Spring容器中，同时配置需要拦截的路径和排除的白名单路径，比如登录接口、静态资源路径一般不需要拦截。
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new AuthInterceptor())
// 拦截所有请求
.addPathPatterns("/**")
// 排除不需要拦截的路径，多个路径用逗号分隔
.excludePathPatterns(
"/user/login", // 登录接口
"/user/register", // 注册接口
"/static/**", // 静态资源路径
"/error" // 错误页面
);
}
}
进阶：接口级别权限校验
如果项目需要更细粒度的权限控制，比如不同角色的用户可以访问不同的接口，可以在拦截器中结合自定义注解实现接口级别的权限校验，首先定义一个权限标识注解。
import java.lang.annotation.*;
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequiredPermission {
// 权限标识，比如"user:add"表示新增用户权限
String value();
}
然后在控制器方法上添加该注解，标注接口需要的权限。
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
@GetMapping("/user/add")
@RequiredPermission("user:add")
public String addUser() {
return "新增用户成功";
}
@GetMapping("/user/list")
@RequiredPermission("user:list")
public String listUser() {
return "用户列表查询成功";
}
}
最后修改拦截器的preHandle方法，增加权限校验逻辑，获取当前登录用户的权限集合，判断是否有接口要求的权限。
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.ModelAndView;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;
import java.lang.reflect.Method;
public class AuthInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
// 1. 登录状态校验
HttpSession session = request.getSession(false);
if (session == null || session.getAttribute("loginUser") == null) {
response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
response.setContentType("application/json;charset=UTF-8");
response.getWriter().write("{"code":401,"msg":"用户未登录，请先登录"}");
return false;
}
// 2. 接口权限校验
if (handler instanceof org.springframework.web.method.HandlerMethod) {
org.springframework.web.method.HandlerMethod handlerMethod = (org.springframework.web.method.HandlerMethod) handler;
Method method = handlerMethod.getMethod();
// 判断方法上是否有RequiredPermission注解
if (method.isAnnotationPresent(RequiredPermission.class)) {
RequiredPermission requiredPermission = method.getAnnotation(RequiredPermission.class);
String needPermission = requiredPermission.value();
// 从session中获取当前用户的权限集合，实际项目中可能从数据库或Redis中获取
java.util.Set<String> userPermissions = (java.util.Set<String>) session.getAttribute("userPermissions");
if (userPermissions == null || !userPermissions.contains(needPermission)) {
response.setStatus(HttpServletResponse.SC_FORBIDDEN);
response.setContentType("application/json;charset=UTF-8");
response.getWriter().write("{"code":403,"msg":"用户无权限访问该接口"}");
return false;
}
}
}
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 {
}
}
常见问题与注意事项
在实际使用HandlerInterceptor实现权限拦截时，需要注意以下几个常见问题：
- 拦截器的执行顺序和注册顺序一致，如果有多个拦截器，先注册的先执行preHandle，后执行afterCompletion。
- 如果项目有跨域需求，需要把跨域处理的过滤器或拦截器放在权限拦截器之前，避免预检请求被拦截。
- 排除白名单路径时要考虑全面，避免把必要的接口误拦截，导致功能异常。
- 敏感信息不要直接存在session中，生产环境建议使用Redis存储登录状态和权限信息，设置合理的过期时间。
HandlerInterceptor是Spring生态原生的拦截器方案，轻量且灵活，适合大部分中小型项目的权限拦截需求，如果项目权限逻辑非常复杂，也可以结合Spring Security等安全框架实现更完善的功能。
JavaHandlerInterceptor权限拦截用户鉴权Spring_MVC修改时间：2026-07-23 08:33:32