<!-- SpringBoot集成WebSocket核心依賴 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-websocket</artifactId>
</dependency>
<!-- 可選：SpringMVC基礎依賴（項目已引入可忽略） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

/**
 * All rights reserved.
 */
package com.itl.framework.config;

import org.springframework.context.annotation.Condition;
import org.springframework.context.annotation.ConditionContext;
import org.springframework.core.type.AnnotatedTypeMetadata;
import org.springframework.util.ClassUtils;

/**
 * 類描述：WebSocket條件判斷類，控制ServerEndpointExporter是否創(chuàng)建
 * jar包部署(內嵌Tomcat)返回true，war包部署(外部Tomcat)返回false
 * @author itl
 * @version 1.0
 * 
 * 修訂歷史：
 * 日期			修訂者		修訂描述
 * 2026-02-05	xxx		修復matches方法固定返回false問題，實現(xiàn)jar/war包部署動態(tài)判斷
 */
public class WebSocketAutoWired implements Condition {

    /**
     * 核心判斷方法：jar包部署(內嵌Tomcat)為true; war包部署(外部Tomcat)為false
     */
    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        // 判斷類加載器中是否存在內嵌Tomcat核心類 → 存在=jar包部署，不存在=war包部署
        return ClassUtils.isPresent(
                "org.apache.catalina.startup.Tomcat",
                context.getClassLoader()
        );
    }
}

/**
 *
 * All rights reserved.
 */
package com.itl.framework.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Conditional;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.socket.server.standard.ServerEndpointExporter;

/**
 * 類描述：WebSocket核心配置類
 * 動態(tài)創(chuàng)建ServerEndpointExporter，解決內嵌Tomcat/外部Tomcat部署兼容問題
 * @author itl
 * @version 1.0
 * 新增條件注解，適配內嵌/外部Tomcat
 */
@Configuration
public class WebSocketConfig {

    /**
     * 注冊WebSocket端點處理器，僅內嵌Tomcat(jar包)時創(chuàng)建
     * 外部Tomcat(war包)由容器自身初始化，無需手動創(chuàng)建
     */
    @Bean
    @Conditional(WebSocketAutoWired.class)
    public ServerEndpointExporter serverEndpointExporter() {
        return new ServerEndpointExporter();
    }
}

/**
 * All rights reserved.
 */
package com.itl.common.utils;

import java.util.Map;
import java.util.Set;
import java.util.Iterator;
import java.util.concurrent.ConcurrentHashMap;
import javax.websocket.Session;

/**
 * 類描述：WebSocket工具類，管理客戶端Session和消息發(fā)送
 * @author itl
 * 
 * 修訂歷史：
 * 日期			修訂者		修訂描述
 * 優(yōu)化Session管理，支持單用戶多連接；增加異常處理和Session有效性判斷
 */
public class WebSocketUtils {

    // 存儲客戶端連接：key=用戶ID，value=該用戶的所有Session連接（支持多端登錄）
    public static Map<String, Set<Session>> clients = new ConcurrentHashMap<>();

    /**
     * 添加客戶端連接
     * @param userId 用戶唯一標識
     * @param session 客戶端會話
     */
    public static void add(String userId, Session session) {
        // 不存在則創(chuàng)建新的Set，存在則直接添加；ConcurrentHashMap.newKeySet()保證線程安全
        clients.computeIfAbsent(userId, k -> ConcurrentHashMap.newKeySet()).add(session);
    }

    /**
     * 處理客戶端發(fā)送的消息（可根據(jù)業(yè)務自定義）
     * @param userId 發(fā)送消息的用戶ID
     * @param message 消息內容
     */
    public static void receive(String userId, String message) {
        // 示例：雙屏聯(lián)動，左屏消息推右屏，右屏消息推左屏
        if ("left".equals(userId)) {
            sendMessage("right", "左屏推送：" + message);
        } else if ("right".equals(userId)) {
            sendMessage("left", "右屏推送：" + message);
        }
        System.out.println("收到用戶[" + userId + "]的消息：" + message);
    }

    /**
     * 精準移除某用戶的某一個Session連接（連接關閉/異常時調用）
     * @param userId 用戶唯一標識
     * @param session 要移除的會話
     */
    public static void remove(String userId, Session session) {
        Set<Session> sessions = clients.get(userId);
        if (sessions != null) {
            sessions.remove(session);
            // 若該用戶無任何連接，移除key，避免空集合占用內存
            if (sessions.isEmpty()) {
                clients.remove(userId);
            }
        }
    }

    /**
     * 移除某用戶的所有連接
     * @param userId 用戶唯一標識
     */
    public static void remove(String userId) {
        clients.remove(userId);
    }

    /**
     * 向指定用戶發(fā)送消息
     * @param userId 接收消息的用戶ID
     * @param message 消息內容
     * @return 成功發(fā)送的連接數(shù)
     */
    public static int sendMessage(String userId, String message) {
        Set<Session> sessions = clients.get(userId);
        // 無該用戶連接，直接返回0
        if (sessions == null || sessions.isEmpty()) {
            return 0;
        }
        int successCount = 0;
        Iterator<Session> it = sessions.iterator();
        while (it.hasNext()) {
            Session session = it.next();
            // 判斷Session是否有效（連接未關閉）
            if (!session.isOpen()) {
                it.remove(); // 移除失效Session，避免內存泄漏
                continue;
            }
            try {
                // 異步發(fā)送消息（推薦），同步發(fā)送使用session.getBasicRemote().sendText(message)
                session.getAsyncRemote().sendText(message);
                successCount++;
            } catch (Exception e) {
                it.remove(); // 發(fā)送失敗，移除失效Session
                e.printStackTrace(); // 實際項目建議使用日志框架（如Logback/Log4j2）
            }
        }
        // 清理空集合
        if (sessions.isEmpty()) {
            clients.remove(userId);
        }
        return successCount;
    }
}

/**
 * All rights reserved.
 */
package com.itl.framework.web.service;

import javax.websocket.OnClose;
import javax.websocket.OnError;
import javax.websocket.OnMessage;
import javax.websocket.OnOpen;
import javax.websocket.Session;
import javax.websocket.server.PathParam;
import javax.websocket.server.ServerEndpoint;
import org.springframework.stereotype.Component;
import com.itl.common.utils.WebSocketUtils;

/**
 * 類描述：WebSocket服務端端點，處理客戶端連接和事件回調
 * 服務端地址：/connect/{userId}
 * @author itl
 * 修復onError方法參數(shù)注解問題；優(yōu)化連接管理，精準移除Session
 */
@ServerEndpoint("/connect/{userId}") // WebSocket連接地址，{userId}為用戶唯一標識
@Component // 必須交給Spring管理，否則無法掃描
public class WebSocketService {

    /**
     * 連接打開事件（客戶端首次連接時調用）
     * @param userId 路徑參數(shù)中的用戶ID
     * @param session 客戶端會話
     */
    @OnOpen
    public void onOpen(@PathParam("userId") String userId, Session session) {
        System.out.println("【WebSocket】連接打開成功！");
        WebSocketUtils.add(userId, session);
        System.out.println("【WebSocket】用戶" + userId + "上線，當前在線人數(shù)：" + WebSocketUtils.clients.size());
    }

    /**
     * 接收客戶端消息事件
     * @param userId 發(fā)送消息的用戶ID
     * @param message 客戶端發(fā)送的消息
     * @return 服務端向客戶端的回執(zhí)消息
     */
    @OnMessage
    public String onMessage(@PathParam("userId") String userId, String message) {
        // 心跳檢測（可選），客戶端發(fā)送&時，服務端回執(zhí)&，避免連接被斷開
        if (message.equals("&")) {
            return "&";
        } else {
            // 調用工具類處理消息
            WebSocketUtils.receive(userId, message);
            return "【服務端回執(zhí)】已收到消息：" + message;
        }
    }

    /**
     * 連接異常事件（網絡中斷、客戶端崩潰等）
     * 注意：@OnError注解不支持@PathParam參數(shù)，會導致參數(shù)解析異常
     * @param session 異常的客戶端會話
     * @param throwable 異常信息
     */
    @OnError
    public void onError(Session session, Throwable throwable) {
        // 遍歷移除該失效的Session
        WebSocketUtils.clients.forEach((userId, sessions) -> {
            WebSocketUtils.remove(userId, session);
        });
        throwable.printStackTrace();
        System.out.println("【WebSocket】連接異常，已移除失效會話");
    }

    /**
     * 連接關閉事件（客戶端主動關閉連接）
     * @param userId 斷開連接的用戶ID
     * @param session 關閉的客戶端會話
     */
    @OnClose
    public void onClose(@PathParam("userId") String userId, Session session) {
        System.out.println("【WebSocket】連接關閉成功！");
        WebSocketUtils.remove(userId, session);
        System.out.println("【WebSocket】用戶" + userId + "下線，當前在線人數(shù)：" + WebSocketUtils.clients.size());
    }
}

import com.itl.common.utils.WebSocketUtils;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * WebSocket測試控制器，雙屏消息互推接口
 * @author itl
 * @date 2026-02-05
 */
@RestController
@RequestMapping("/websocket")
@Api(tags = "WebSocket測試接口")
public class WebSocketController {

    /**
     * 接收左屏消息并推送至右屏
     * @param message 消息內容
     * @return 推送結果（1=成功，0=失?。?
     */
    @ApiOperation(value = "左屏推右屏", notes = "HTTP接口觸發(fā)，向右屏推送消息")
    @ApiImplicitParam(name = "message", value = "推送的消息內容", required = true, dataType = "String")
    @GetMapping(value = "/right")
    public AjaxResult right(String message) {
        // toAjax：通用工具類，1=成功，0=失敗
        return toAjax(WebSocketUtils.sendMessage("right", message));
    }

    /**
     * 接收右屏消息并推送至左屏
     * @param message 消息內容
     * @return 推送結果（1=成功，0=失?。?
     */
    @ApiOperation(value = "右屏推左屏", notes = "HTTP接口觸發(fā)，向左屏推送消息")
    @ApiImplicitParam(name = "message", value = "推送的消息內容", required = true, dataType = "String")
    @GetMapping(value = "/left")
    public AjaxResult left(String message) {
        return toAjax(WebSocketUtils.sendMessage("left", message));
    }

    /**
     * 通用響應結果封裝（項目已實現(xiàn)可忽略）
     * @param rows 成功數(shù)
     * @return AjaxResult
     */
    private AjaxResult toAjax(int rows) {
        return rows > 0 ? AjaxResult.success() : AjaxResult.error();
    }
}

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>WebSocket雙屏測試</title>
</head>
<body>
    <h3>WebSocket雙屏聯(lián)動測試（<span id="screenType">左屏</span>）</h3>
    <input type="text" id="msgInput" placeholder="請輸入消息內容">
    <button onclick="sendMsg()">發(fā)送消息</button>
    <div id="msgList" style="margin-top: 20px; width: 500px; height: 300px; border: 1px solid #ccc; padding: 10px; overflow-y: auto;"></div>

    <script>
        // 定義用戶ID，left=左屏，right=右屏
        const userId = "left";
        document.getElementById("screenType").innerText = userId === "left" ? "左屏" : "右屏";
        // WebSocket連接地址，替換為自己的服務端地址
        const ws = new WebSocket("ws://localhost:8080/connect/" + userId);

        // 連接成功回調
        ws.onopen = function() {
            addMsg("【系統(tǒng)提示】WebSocket連接成功！");
        };

        // 接收消息回調
        ws.onmessage = function(event) {
            addMsg("【收到消息】" + event.data);
        };

        // 連接關閉回調
        ws.onclose = function() {
            addMsg("【系統(tǒng)提示】WebSocket連接關閉！");
        };

        // 連接異常回調
        ws.onerror = function() {
            addMsg("【系統(tǒng)提示】WebSocket連接異常！");
        };

        // 發(fā)送消息
        function sendMsg() {
            const msg = document.getElementById("msgInput").value;
            if (!msg) {
                alert("請輸入消息內容！");
                return;
            }
            ws.send(msg);
            addMsg("【發(fā)送消息】" + msg);
            document.getElementById("msgInput").value = "";
        }

        // 追加消息到頁面
        function addMsg(content) {
            const msgList = document.getElementById("msgList");
            const div = document.createElement("div");
            div.style.margin = "5px 0";
            div.innerText = new Date().toLocaleString() + " - " + content;
            msgList.appendChild(div);
            // 滾動到底部
            msgList.scrollTop = msgList.scrollHeight;
        }

        // 心跳檢測，每30秒發(fā)送一次&，防止連接斷開
        setInterval(() => {
            ws.send("&");
        }, 30000);
    </script>
</body>
</html>

<packaging>jar</packaging >

<packaging>war</packaging>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <!-- 排除內嵌Tomcat -->
        <exclusions>
            <exclusion>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-tomcat</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <!-- 引入servlet-api依賴 -->
    <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>3.1.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

@SpringBootApplication
public class Application extends SpringBootServletInitializer {
    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(Application.class);
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}