欢迎来到尧图网

客户服务 关于我们

您的位置:首页 > 文旅 > 八卦 > Spring Cloud 项目中优雅地传递用户信息:基于 Gateway + ThreadLocal 的用户上下文方案

Spring Cloud 项目中优雅地传递用户信息:基于 Gateway + ThreadLocal 的用户上下文方案

2025/5/1 19:30:22 来源:https://blog.csdn.net/m0_73612839/article/details/147616920  浏览:    关键词:Spring Cloud 项目中优雅地传递用户信息:基于 Gateway + ThreadLocal 的用户上下文方案

在 Spring Cloud 微服务架构中,我们通常使用 API 网关(如 Spring Cloud Gateway)作为流量入口,负责统一的用户身份校验和请求路由。本文将介绍一种通用的用户信息传递方案:网关完成认证后通过请求头传递用户信息,服务端使用拦截器结合 ThreadLocal 实现用户上下文的自动获取与清理。


📚 目录

  1. 架构概览与设计思想

  2. Spring Cloud Gateway 设置用户信息头

  3. UserContext:用户上下文工具类

  4. UserInfoInterceptor:拦截器实现

  5. MvcConfig:注册拦截器(按需加载)

  6. Spring Boot 自动装配支持

  7. 线程复用风险与清理机制

  8. 统一用户信息访问方式

  9. 总结与建议


架构概览与设计思想

[浏览器 / APP]↓
[SpringCloud Gateway] —— 登录校验 + 添加用户ID至请求头(user-info)↓
[业务服务] —— 使用拦截器提取 user-info,存入 ThreadLocal↓
[Service / Mapper 层] —— 通过 UserContext.getUser() 获取用户ID

设计目标:

  • 登录状态统一在网关校验,后端服务无需再次解析 Token

  • 后端服务无侵入获取当前用户信息

  • 请求结束后自动清除用户信息,避免线程复用污染


Spring Cloud Gateway 设置用户信息头

在登录校验通过后,我们可以使用 Gateway 的 GlobalFilter 将解析后的用户ID写入请求头中:

exchange.getRequest().mutate().header("user-info", userId.toString()).build();

也可以用 exchange.getRequest().mutate().headers(...) 添加多个自定义信息,例如用户名、角色等。


UserContext:用户上下文工具类

public class UserContext {private static final ThreadLocal<Long> tl = new ThreadLocal<>();public static void setUser(Long userId) {tl.set(userId);}public static Long getUser() {return tl.get();}public static void removeUser(){tl.remove();}
}

UserInfoInterceptor:拦截器实现

public class UserInfoInterceptor implements HandlerInterceptor {@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {String userInfo = request.getHeader("user-info");if (StrUtil.isNotBlank(userInfo)) {UserContext.setUser(Long.valueOf(userInfo));}return true;}@Overridepublic void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {UserContext.removeUser(); // 一定要清理,防止线程复用导致数据串用!}
}

MvcConfig:注册拦截器(按需加载)

@Configuration
@ConditionalOnClass(DispatcherServlet.class)
public class MvcConfig implements WebMvcConfigurer {@Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(new UserInfoInterceptor());}
}

🔍 为什么使用 @ConditionalOnClass(DispatcherServlet.class)?

该注解的作用是:仅当项目中存在 DispatcherServlet(即为 Spring Web 应用)时才加载该配置类。

这样做可以:

  • 增强公共模块的通用性(非 Web 模块不加载 MVC 配置)

  • 避免在非 Web 项目中报类找不到错误


Spring Boot 自动装配支持

在 common 模块中配置自动注册支持:

📄 resources/META-INF/spring.factories

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\com.hmall.common.config.MvcConfig

线程复用风险与清理机制

为什么一定要调用 ThreadLocal.remove()

Spring Boot 默认使用 Tomcat,Tomcat 内部维护一个线程池,线程复用带来两大隐患:

  1. 数据串用: 用户 A 请求设置了 userId=1,未清除,线程复用处理用户 B 请求时会错误复用 A 的 userId。

  2. 内存泄漏: ThreadLocalMap key 是弱引用,value 是强引用,不调用 remove 会导致 value 无法 GC 回收。

✅ 正确做法是在 afterCompletion 中移除:

UserContext.removeUser();

统一用户信息访问方式

在任何业务代码中:

Long userId = UserContext.getUser();

无需解析 Token、无需手动传参,统一、简洁、解耦。


总结与建议

  • ✅ 网关做登录校验 + 用户信息封装,是最佳实践

  • ✅ 后端使用拦截器 + ThreadLocal 自动注入用户上下文

  • @ConditionalOnClass 保证配置在 Web 项目中生效,避免不必要的类加载

  • afterCompletion 中清除 ThreadLocal,防止线程复用问题和内存泄漏

📝 推荐统一网关行为,例如:在请求头中添加 user-id、role、username 等,避免后端服务关注鉴权细节,聚焦业务逻辑。


📌 本文适用于 Spring Cloud Gateway + Spring Boot 微服务体系,实战性强,建议在项目中统一实践。

版权声明:

本网仅为发布的内容提供存储空间,不对发表、转载的内容提供任何形式的保证。凡本网注明“来源:XXX网络”的作品,均转载自其它媒体,著作权归作者所有,商业转载请联系作者获得授权,非商业转载请注明出处。

我们尊重并感谢每一位作者,均已注明文章来源和作者。如因作品内容、版权或其它问题,请及时与我们联系,联系邮箱:809451989@qq.com,投稿邮箱:809451989@qq.com

热搜词