主题
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 |
WebSocketProperties | pmforge.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、用户类型、租户 ID | websocket/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.websocket | enable | true | 总开关 |
pmforge.websocket | path | /ws(示例配置为 /infra/ws) | 握手路径,不带 /admin-api 前缀 |
pmforge.websocket | sender-type | local | local/redis/rocketmq/rabbitmq/kafka |
pmforge.websocket.sender-rocketmq | topic / consumer-group | 无默认值(示例用 ${spring.application.name}-websocket) | 广播消费 |
pmforge.websocket.sender-rabbitmq | exchange / queue | 无默认值 | 声明 durable TopicExchange;队列带 UUID、autoDelete=true |
pmforge.websocket.sender-kafka | topic / consumer-group | 无默认值 | groupId 追加 UUID 实现广播 |
5. 扩展点
- 加一种消息:实现
WebSocketMessageListener<MyMessage>并注册成 Bean,泛型即消息体类型;前端发{"type":"my_type","content":"{...}"}即可命中。 - 换发送通道:只改
pmforge.websocket.sender-type与对应 topic 配置,业务代码里的WebSocketMessageSender调用不变。 - 主动推送:注入
WebSocketMessageSender,调send(userType, userId, message)或广播方法;也可注入WebSocketSessionManager直接遍历会话。 - 握手校验:新增
HandshakeInterceptorBean 即可参与握手(全部拦截器都会被注册)。 - 鉴权放行:路径已由
WebSocketAuthorizeRequestsCustomizer放行;若改了path,它会自动跟随。
6. 常见坑
- 默认
local只适合单机:源码注释原话是「仅仅适合单机场景!!!」——多实例部署时,用户在 A 实例、消息从 B 实例发出,A 上的连接收不到。 - 握手失败不会返回 401:
LoginUserHandshakeInterceptor取不到LoginUser直接return false,浏览器只看到连接被拒;排查时先看令牌是否放在了 query 参数(token)。 content必须是 JSON 对象字符串:帧是{type, content}两层,content里再放业务 JSON;直接传对象或数组会在TypeUtil.getTypeArgument反序列化处失败。- 广播型消费组会「不沉淀位点」:rocketmq/rabbitmq/kafka 的 consumer group/queue 名都追加了 UUID 以实现广播,重启后相当于新消费者——历史消息不会补推,这是设计取舍而非 bug。
- 发送有硬性上限:
ConcurrentWebSocketSessionDecorator设了 5 秒发送超时、100KB 缓冲,慢客户端会被断开,大消息(如整页表格导出)不要走 WebSocket。 - 会话查询按租户过滤:
WebSocketSessionManagerImpl.getSessionList(userType)只在当前TenantContextHolder租户内返回;跨租户推送必须切上下文(TenantUtils.execute)。
7. 关联页面
- starter-security:
LoginUser与放行规则 - starter-mq:
redissender 复用的RedisMQTemplate - starter-biz-tenant:
TenantUtils.execute切租户 - 横切机制、通知与消息