Skip to content

starter-websocket ​

1. 职责 ​

提供一条「JSON 帧」协议的 WebSocket 通道:客户端连 /infra/ws(默认),每条消息是 {"type": "...", "content": "{...}"},服务端按 type 分发给业务 WebSocketMessageListener;同时维护会话表(按用户类型 + 用户 ID 索引),让后台能主动推消息给某个人或所有人。

「跨实例」的部分用可插拔的 sender 解决:sender-type 选 local/redis/rocketmq/rabbitmq/kafka,换实现不用改业务代码。

它不解决:消息持久化与必达(Redis Pub/Sub 与 WebSocket 都是「在线才收」)、鉴权本身(复用 starter-security 的 LoginUser)、前端协议约定之外的上行格式。

本节路径均省略公共前缀 framework/pmforge-spring-boot-starter-websocket/src/main/java/com/pmforge/framework/。

2. 关键类 ​

类作用路径
PmforgeWebSocketAutoConfiguration注册 handler、握手拦截器、会话管理器、sender;内部按 sender-type 择一装配websocket/config/PmforgeWebSocketAutoConfiguration.java
WebSocketPropertiespmforge.websocket.*websocket/config/WebSocketProperties.java
JsonWebSocketMessage帧结构:type + content(content 必须是 JSON 对象字符串)websocket/core/message/JsonWebSocketMessage.java
JsonWebSocketMessageHandler分发器:ping→pong、按 type 找 listener、反序列化、切租户上下文websocket/core/handler/JsonWebSocketMessageHandler.java
WebSocketMessageListener<T>业务监听器接口,泛型 T 决定 content 反序列化类型websocket/core/listener/WebSocketMessageListener.java
WebSocketSessionHandlerDecorator每条连接套 ConcurrentWebSocketSessionDecorator(发送超时 5s、缓冲 100KB)websocket/core/session/WebSocketSessionHandlerDecorator.java
WebSocketSessionManagerImpl会话表:idSessions + userSessions(用户类型 → 用户 ID → 会话);按租户过滤websocket/core/session/WebSocketSessionManagerImpl.java
LoginUserHandshakeInterceptor握手时取 LoginUser,取不到直接拒绝websocket/core/security/LoginUserHandshakeInterceptor.java
WebSocketAuthorizeRequestsCustomizer把 pmforge.websocket.path 加进 Security 放行列表websocket/core/security/WebSocketAuthorizeRequestsCustomizer.java
AbstractWebSocketMessageSender + 5 套实现单机/Redis/RocketMQ/RabbitMQ/Kafka 的发送与消费websocket/core/sender/
WebSocketFrameworkUtils从 session 取 LoginUser、用户 ID、用户类型、租户 IDwebsocket/core/util/WebSocketFrameworkUtils.java

3. 自动配置 ​

配置类生效条件注册了什么
PmforgeWebSocketAutoConfiguration@ConditionalOnProperty(prefix="pmforge.websocket", value="enable", matchIfMissing=true);@AutoConfiguration(before = PmforgeRedisMQConsumerAutoConfiguration.class)WebSocketConfigurer(addHandler(handler, path)、握手拦截器、setAllowedOriginPatterns("*"));WebSocketHandler;WebSocketSessionManager;WebSocketAuthorizeRequestsCustomizer
…SenderConfiguration(5 个内部 @Configuration)@ConditionalOnProperty(prefix="pmforge.websocket", name="sender-type", havingValue="local"/"redis"/"rocketmq"/"rabbitmq"/"kafka")对应的 *WebSocketMessageSender 与(除 local 外)消费者;rocketmq/rabbitmq/kafka 还依赖 sender-*.topic/exchange/queue 配置项

4. 配置项 ​

前缀键默认值说明
pmforge.websocketenabletrue总开关
pmforge.websocketpath/ws(示例配置为 /infra/ws)握手路径,不带 /admin-api 前缀
pmforge.websocketsender-typelocallocal/redis/rocketmq/rabbitmq/kafka
pmforge.websocket.sender-rocketmqtopic / consumer-group无默认值(示例用 ${spring.application.name}-websocket)广播消费
pmforge.websocket.sender-rabbitmqexchange / queue无默认值声明 durable TopicExchange;队列带 UUID、autoDelete=true
pmforge.websocket.sender-kafkatopic / consumer-group无默认值groupId 追加 UUID 实现广播

5. 扩展点 ​

  • 加一种消息:实现 WebSocketMessageListener<MyMessage> 并注册成 Bean,泛型即消息体类型;前端发 {"type":"my_type","content":"{...}"} 即可命中。
  • 换发送通道:只改 pmforge.websocket.sender-type 与对应 topic 配置,业务代码里的 WebSocketMessageSender 调用不变。
  • 主动推送:注入 WebSocketMessageSender,调 send(userType, userId, message) 或广播方法;也可注入 WebSocketSessionManager 直接遍历会话。
  • 握手校验:新增 HandshakeInterceptor Bean 即可参与握手(全部拦截器都会被注册)。
  • 鉴权放行:路径已由 WebSocketAuthorizeRequestsCustomizer 放行;若改了 path,它会自动跟随。

6. 常见坑 ​

  1. 默认 local 只适合单机:源码注释原话是「仅仅适合单机场景!!!」——多实例部署时,用户在 A 实例、消息从 B 实例发出,A 上的连接收不到。
  2. 握手失败不会返回 401:LoginUserHandshakeInterceptor 取不到 LoginUser 直接 return false,浏览器只看到连接被拒;排查时先看令牌是否放在了 query 参数(token)。
  3. content 必须是 JSON 对象字符串:帧是 {type, content} 两层,content 里再放业务 JSON;直接传对象或数组会在 TypeUtil.getTypeArgument 反序列化处失败。
  4. 广播型消费组会「不沉淀位点」:rocketmq/rabbitmq/kafka 的 consumer group/queue 名都追加了 UUID 以实现广播,重启后相当于新消费者——历史消息不会补推,这是设计取舍而非 bug。
  5. 发送有硬性上限:ConcurrentWebSocketSessionDecorator 设了 5 秒发送超时、100KB 缓冲,慢客户端会被断开,大消息(如整页表格导出)不要走 WebSocket。
  6. 会话查询按租户过滤:WebSocketSessionManagerImpl.getSessionList(userType) 只在当前 TenantContextHolder 租户内返回;跨租户推送必须切上下文(TenantUtils.execute)。

7. 关联页面 ​