WebSocket和HTTP对比对比维度WebSocketHTTP通信方向全双工客户端和服务器可以同时、互相发送消息。半双工/单工必须由客户端发起请求服务器才能响应。连接状态持久连接一旦建立除非主动关闭否则一直保持在线。短连接每次请求/响应后连接通常就会断开Keep-Alive 也只是复用不是长连。服务端能力可以主动向客户端推送数据如实时通知。不能主动推送只能被动响应客户端的请求。实时性极高消息到达即发送延迟低。较低需要客户端不断轮询频繁发请求才能获取新数据。适用场景实时聊天、在线游戏、股票行情、协同编辑等。传统的网页浏览、API 调用、文件下载等提示这里主要是WebSocket的一个实例,具体根据实际需求1. 概述平台目前提供1 个 WebSocket 端点设备列表实时推送。项目说明业务需求大屏需要实时获取 列表设备的最新健康度状态1分钟1次这个时间频率可自行设置数据同源与 HTTPPOST /device/list共用TwinbornService.listDevices()推送方式连接后立即推送 1 次之后每60 秒自动推送协议纯文本 JSONTextMessage注意一般来说使用WebSocket实时推送都会写一个HTTP接口防止实时接口获取不到可手动获取HTTPHTTP 示例2. 连接地址 和HTTP区别是 前缀连接不同,接口前方加/ws默认端口45152 我自己项目中的端口定义实际根据自己项目来ws://{host}:45152/ws/device/list生产环境建议使用 WSSwss://{host}:{port}/ws/device/list //wss 数据传输需要加密考虑到数据安全3.跨域WebSocketConfig中配置了setAllowedOrigins(*)允许任意来源连接。这里可以根据AI生成WebSocketConfig的连接工具类类似HTTP的连接工具类4. 筛选参数4.1 连接时通过 URL Query 传入可选ws://{ip}:45152/ws/device/list?treePath压缩机deviceName螺杆abnormaltrue参数类型说明treePathString组织树路径tree_path模糊匹配deviceNameString设备名称device_name模糊匹配abnormalBooleantrue仅异常预警/报警false仅正常不传则不过滤Query 值会做 UTF-8 URL 解码。4.2 连接后通过 JSON 文本消息更新可选客户端可随时发送 JSON 文本立即触发一次推送后续仍按 60 秒周期推送。{ treePath: 注采站, deviceName: 压缩机, abnormal: true }格式错误时服务端返回{ code: 500, message: 消息体须为 JSON字段treePath、deviceName、abnormal, data: null }5. 推送规则时机行为连接建立解析 URL Query → 启动定时任务 →立即推送定时任务每60 秒推送一次PUSH_INTERVAL_SECONDS 60收到客户端 JSON更新筛选条件 →立即推送连接关闭 / 传输异常取消该 session 的定时任务服务销毁PreDestroy取消所有任务并关闭线程池6. 消息格式6.1 成功响应结构与 HTTP 接口一致为ResultListTwinbornDeviceSearchVo{ code: 200, message: success, data: [ { } ] }6.3 失败响应{ code: 500, message: 设备列表推送失败, data: null }7. 与 HTTP 接口对照对比项WebSocketHTTP地址ws://.../ws/device/listPOST /device/list参数方式URL Query 或连接后发 JSON 文本Request Body JSON返回结构ResultListTwinbornDeviceSearchVo相同业务逻辑twinbornService.listDevices(query)相同推送连接后即时 每 60 秒单次请求单次返回8. 内部实现要点8.1TwinbornWebSocketConfigregistry.addHandler(deviceListWebSocketHandler, /ws/device/list) .setAllowedOrigins(*);注册 Handler 与路径启用 Spring WebSocketEnableWebSocket. 前端接入示例9.1 原生 WebSocketconst ws new WebSocket( ws://{ip}:45152/ws/device/list?treePath压缩机abnormaltrue ); ws.onmessage (event) { const result JSON.parse(event.data); if (result.code 200) { console.log(设备列表, result.data); } else { console.error(result.message); } }; // 动态更新筛选条件会立即收到新推送 ws.send(JSON.stringify({ treePath: 注采站, deviceName: 压缩机, abnormal: false })); ws.onclose () console.log(连接已关闭);9.2 典型使用场景大屏/监控页建立长连接每 60 秒自动刷新设备健康状态带筛选的列表页URL 带初始条件用户改筛选时sendJSON 即可10. 注意事项单向推送为主服务端主动推送客户端发消息仅用于更新筛选条件无心跳机制依赖 60 秒定时推送网络断开后需前端自行重连无鉴权当前 Handler 未做 Token / Session 校验并发安全同一 session 发送使用synchronized(session)空参数不传筛选条件时返回全部未删除设备与 HTTP 行为一致11. Maven 依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-websocket/artifactId /dependency
完整的WebSocket 接口文档
发布时间：2026/7/11 13:27:36
WebSocket和HTTP对比对比维度WebSocketHTTP通信方向全双工客户端和服务器可以同时、互相发送消息。半双工/单工必须由客户端发起请求服务器才能响应。连接状态持久连接一旦建立除非主动关闭否则一直保持在线。短连接每次请求/响应后连接通常就会断开Keep-Alive 也只是复用不是长连。服务端能力可以主动向客户端推送数据如实时通知。不能主动推送只能被动响应客户端的请求。实时性极高消息到达即发送延迟低。较低需要客户端不断轮询频繁发请求才能获取新数据。适用场景实时聊天、在线游戏、股票行情、协同编辑等。传统的网页浏览、API 调用、文件下载等提示这里主要是WebSocket的一个实例,具体根据实际需求1. 概述平台目前提供1 个 WebSocket 端点设备列表实时推送。项目说明业务需求大屏需要实时获取 列表设备的最新健康度状态1分钟1次这个时间频率可自行设置数据同源与 HTTPPOST /device/list共用TwinbornService.listDevices()推送方式连接后立即推送 1 次之后每60 秒自动推送协议纯文本 JSONTextMessage注意一般来说使用WebSocket实时推送都会写一个HTTP接口防止实时接口获取不到可手动获取HTTPHTTP 示例2. 连接地址 和HTTP区别是 前缀连接不同,接口前方加/ws默认端口45152 我自己项目中的端口定义实际根据自己项目来ws://{host}:45152/ws/device/list生产环境建议使用 WSSwss://{host}:{port}/ws/device/list //wss 数据传输需要加密考虑到数据安全3.跨域WebSocketConfig中配置了setAllowedOrigins(*)允许任意来源连接。这里可以根据AI生成WebSocketConfig的连接工具类类似HTTP的连接工具类4. 筛选参数4.1 连接时通过 URL Query 传入可选ws://{ip}:45152/ws/device/list?treePath压缩机deviceName螺杆abnormaltrue参数类型说明treePathString组织树路径tree_path模糊匹配deviceNameString设备名称device_name模糊匹配abnormalBooleantrue仅异常预警/报警false仅正常不传则不过滤Query 值会做 UTF-8 URL 解码。4.2 连接后通过 JSON 文本消息更新可选客户端可随时发送 JSON 文本立即触发一次推送后续仍按 60 秒周期推送。{ treePath: 注采站, deviceName: 压缩机, abnormal: true }格式错误时服务端返回{ code: 500, message: 消息体须为 JSON字段treePath、deviceName、abnormal, data: null }5. 推送规则时机行为连接建立解析 URL Query → 启动定时任务 →立即推送定时任务每60 秒推送一次PUSH_INTERVAL_SECONDS 60收到客户端 JSON更新筛选条件 →立即推送连接关闭 / 传输异常取消该 session 的定时任务服务销毁PreDestroy取消所有任务并关闭线程池6. 消息格式6.1 成功响应结构与 HTTP 接口一致为ResultListTwinbornDeviceSearchVo{ code: 200, message: success, data: [ { } ] }6.3 失败响应{ code: 500, message: 设备列表推送失败, data: null }7. 与 HTTP 接口对照对比项WebSocketHTTP地址ws://.../ws/device/listPOST /device/list参数方式URL Query 或连接后发 JSON 文本Request Body JSON返回结构ResultListTwinbornDeviceSearchVo相同业务逻辑twinbornService.listDevices(query)相同推送连接后即时 每 60 秒单次请求单次返回8. 内部实现要点8.1TwinbornWebSocketConfigregistry.addHandler(deviceListWebSocketHandler, /ws/device/list) .setAllowedOrigins(*);注册 Handler 与路径启用 Spring WebSocketEnableWebSocket. 前端接入示例9.1 原生 WebSocketconst ws new WebSocket( ws://{ip}:45152/ws/device/list?treePath压缩机abnormaltrue ); ws.onmessage (event) { const result JSON.parse(event.data); if (result.code 200) { console.log(设备列表, result.data); } else { console.error(result.message); } }; // 动态更新筛选条件会立即收到新推送 ws.send(JSON.stringify({ treePath: 注采站, deviceName: 压缩机, abnormal: false })); ws.onclose () console.log(连接已关闭);9.2 典型使用场景大屏/监控页建立长连接每 60 秒自动刷新设备健康状态带筛选的列表页URL 带初始条件用户改筛选时sendJSON 即可10. 注意事项单向推送为主服务端主动推送客户端发消息仅用于更新筛选条件无心跳机制依赖 60 秒定时推送网络断开后需前端自行重连无鉴权当前 Handler 未做 Token / Session 校验并发安全同一 session 发送使用synchronized(session)空参数不传筛选条件时返回全部未删除设备与 HTTP 行为一致11. Maven 依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-websocket/artifactId /dependency
