WebSocket连接必须做Query参数校验，因为握手后脱离HTTP生命周期，SpringSecurity等鉴权机制默认不生效；若前端未在URL中显式传递Token，服务端无法获取认证依据，导致“未授权连接成功”实为鉴权未触发。
WebSocket连接为什么必须做Query参数校验？
因为websocket握手请求虽以http形式发起，但一旦升级成功，后续通信就脱离http生命周期——springsecurity、jwt过滤器等常规http鉴权机制默认不生效。如果前端只靠localstorage里存着token、却不在建立连接时显式传递，服务端根本收不到认证依据。你看到的“未授权连接成功”，不是安全机制失效了，而是它压根没被触发。
URL Query传Token：怎么拼才不会被截断或报错？
直接拼接token参数看似简单，但实际踩坑最多。常见错误包括：token含特殊字符（如+、/、空格）、未编码、参数名与后端约定不一致、URL过长被代理截断。
- 务必用
encodeURIComponent()包裹Token值，例如：`wss://api.example.com/ws?token=${encodeURIComponent(token)}` - 避免使用
authorization作为参数名——部分CDN或网关会自动剥离该关键词；推荐用access_token或t等中性名称 - 若Token本身是JWT，注意其可能含多个
.和=，这些在URL中虽合法，但某些老旧负载均衡器会误判为非法字符，建议统一编码 - 不要在Query中传敏感字段以外的信息（如
user_id、room_id），这些应由服务端从Token解析得出，防止客户端篡改
后端如何安全地从Query取Token并校验？
不能依赖HttpServletRequest.getParameter("token")就完事。WebSocket握手请求走的是Servlet容器的Upgrade流程，部分容器（如Tomcat 9+）对Query参数解析有缓存或延迟行为；更稳妥的方式是在HandshakeInterceptor或ServerEndpointConfig.Configurator中手动解析原始URI。
- Spring WebFlux/WebSocket项目优先用
HandshakeInterceptor.beforeHandshake()，通过ServerHttpRequest.getURI().getQuery()获取完整Query字符串，再用UriComponentsBuilder.fromUri()解析 - 纯Java EE（
@ServerEndpoint）环境，需继承ServerEndpointConfig.Configurator，重写modifyHandshake()，从HandshakeRequest.getParameterMap()读取——但要注意该Map在某些容器中可能为空，此时应回退到解析request.getRequestURI() - 校验失败必须抛出异常（如
RuntimeException），不能仅返回response.setStatus(401)——WebSocket协议不识别HTTP状态码，不抛异常会导致连接静默建立
Query方案的硬伤：哪些场景它根本不适用？
Query传Token不是万能解法。当你的部署链路中存在任何一级组件会重写、过滤或记录URL（比如API网关、WAF、审计日志系统），Token就会暴露在明文日志或监控面板里。更严重的是，浏览器开发者工具的Network标签页、chrome://net-internals、甚至公司内部的流量镜像系统，都能直接看到完整URL。
- 金融、政务、医疗类系统严禁使用Query传Token，合规审计必挂
- 若已用Query方案，必须确保所有中间件（Nginx、Kong、Envoy）配置了
log_subrequest off或过滤token=字段 - 移动端WebView或小程序环境，Query参数可能被系统级URL拦截器修改，导致Token丢失——微信小程序
wx.connectSocket()明确要求url参数不能含#号，但对Query无强制限制，仍建议加encodeURIComponent
真正容易被忽略的点是：Query参数在校验通过后，不应再被业务逻辑反复读取。Token应只用于身份确认，用户权限、角色、租户ID等信息，必须从解析后的JWT payload中提取，而不是从URL里二次拿——否则攻击者伪造Query就能绕过RBAC检查。
立即学习“前端免费学习笔记（深入）”；
