Spring容器啟動(dòng)
    └── ServerEndpointExporter.afterPropertiesSet()
            └── 掃描 @ServerEndpoint 類
                    └── 注冊到 ServerContainer（Tomcat WebSocket 運(yùn)行時(shí)）

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-websocket</artifactId>
</dependency>

@Configuration
public class WebSocketConfig {
    /**
     * 向 Spring 容器注冊 ServerEndpointExporter
     * 它會(huì)在應(yīng)用啟動(dòng)后，將所有 @ServerEndpoint 注解的類注冊到底層 Servlet 容器
     * 注意：使用外部容器（如獨(dú)立部署的 Tomcat）時(shí)，不需要注冊此 Bean，
     *       外部容器會(huì)自行完成注冊
     */
    @Bean
    public ServerEndpointExporter serverEndpointExporter() {
        return new ServerEndpointExporter();
    }
}

@Component  // ① 必須交給 Spring 容器，才能在內(nèi)部注入 Service 等 Bean
@ServerEndpoint("/ws/chat/{roomId}")  // ② 定義 WebSocket 連接路徑
public class ChatWebSocketServer {
    // ③ 核心踩坑點(diǎn)：@ServerEndpoint 每個(gè)連接都會(huì) new 一個(gè)新實(shí)例
    //    因此不能用普通的 @Autowired 字段注入，必須用 static 字段 + setter 注入
    private static MessageService messageService;
    @Autowired
    public void setMessageService(MessageService messageService) {
        ChatWebSocketServer.messageService = messageService;
    }
    // ④ 線程安全：用 ConcurrentHashMap 管理所有在線 Session
    private static final ConcurrentHashMap<String, Session> SESSION_MAP
            = new ConcurrentHashMap<>();
    private Session session;
    private String userId;
    /**
     * 連接建立成功時(shí)觸發(fā)
     */
    @OnOpen
    public void onOpen(Session session, @PathParam("roomId") String roomId) {
        this.session = session;
        this.userId = session.getId();
        SESSION_MAP.put(userId, session);
        System.out.printf("用戶 [%s] 加入房間 [%s]，當(dāng)前在線人數(shù)：%d%n",
                userId, roomId, SESSION_MAP.size());
    }
    /**
     * 收到客戶端消息時(shí)觸發(fā)
     */
    @OnMessage
    public void onMessage(String message, Session session) {
        System.out.printf("收到用戶 [%s] 的消息：%s%n", userId, message);
        // 調(diào)用業(yè)務(wù) Service 處理消息（static 注入，可正常使用）
        messageService.saveMessage(userId, message);
        // 廣播給所有在線用戶
        broadcastMessage(userId + ": " + message);
    }
    /**
     * 連接關(guān)閉時(shí)觸發(fā)
     */
    @OnClose
    public void onClose() {
        SESSION_MAP.remove(userId);
        System.out.printf("用戶 [%s] 斷開連接，當(dāng)前在線人數(shù)：%d%n",
                userId, SESSION_MAP.size());
    }
    /**
     * 發(fā)生錯(cuò)誤時(shí)觸發(fā)
     */
    @OnError
    public void onError(Session session, Throwable error) {
        System.err.printf("用戶 [%s] 發(fā)生錯(cuò)誤：%s%n", userId, error.getMessage());
        error.printStackTrace();
    }
    /**
     * 廣播消息給所有在線用戶
     */
    private void broadcastMessage(String message) {
        SESSION_MAP.values().forEach(s -> {
            try {
                if (s.isOpen()) {
                    s.getBasicRemote().sendText(message);
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
        });
    }
    /**
     * 向指定用戶發(fā)送消息（可供外部調(diào)用）
     */
    public static void sendMessageToUser(String userId, String message) {
        Session session = SESSION_MAP.get(userId);
        if (session != null && session.isOpen()) {
            try {
                session.getBasicRemote().sendText(message);
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    }
}

HTTP 請(qǐng)求升級(jí)為 WebSocket
    └── DispatcherServlet
            └── WebSocketHandlerMapping（路徑路由）
                    └── 你的 WebSocketHandler（處理具體邏輯）

@Configuration
@EnableWebSocket  // ① 開啟 Spring WebSocket 支持
public class WebSocketConfig implements WebSocketConfigurer {  // ② 實(shí)現(xiàn)此接口
    @Autowired
    private ChatWebSocketHandler chatWebSocketHandler;
    @Autowired
    private WebSocketAuthInterceptor authInterceptor;
    /**
     * ③ 重寫此方法，將處理器注冊到指定路徑
     */
    @Override
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
        registry
            .addHandler(chatWebSocketHandler, "/ws/chat")  // 注冊處理器和路徑
            .addInterceptors(authInterceptor)               // 可添加握手?jǐn)r截器
            .setAllowedOrigins("*");                        // 跨域配置
    }
}

@Component
public class WebSocketAuthInterceptor implements HandshakeInterceptor {
    /**
     * WebSocket 握手前執(zhí)行：返回 false 則拒絕連接
     */
    @Override
    public boolean beforeHandshake(ServerHttpRequest request,
                                   ServerHttpResponse response,
                                   WebSocketHandler wsHandler,
                                   Map<String, Object> attributes) throws Exception {
        // 從請(qǐng)求參數(shù)或 Header 中獲取 Token，驗(yàn)證用戶身份
        String token = ((ServletServerHttpRequest) request)
                .getServletRequest().getParameter("token");
        if (token == null || !isValidToken(token)) {
            response.setStatusCode(HttpStatus.UNAUTHORIZED);
            return false;  // 拒絕握手
        }
        // 將用戶信息存入 attributes，后續(xù) Handler 中可以取到
        attributes.put("userId", parseUserId(token));
        return true;
    }
    @Override
    public void afterHandshake(ServerHttpRequest request, ServerHttpResponse response,
                               WebSocketHandler wsHandler, Exception exception) {
        // 握手后執(zhí)行，一般留空
    }
    private boolean isValidToken(String token) {
        // 實(shí)際項(xiàng)目中調(diào)用 JWT 解析或 Redis 校驗(yàn)
        return token.startsWith("valid_");
    }
    private String parseUserId(String token) {
        return token.replace("valid_", "");
    }
}

@Component  // ① 交給 Spring 容器管理，正常 @Autowired 注入無任何問題
public class ChatWebSocketHandler extends TextWebSocketHandler {  // ② 繼承此類處理文本消息
    @Autowired
    private MessageService messageService;  // ③ 單例 Handler，直接 @Autowired 完全沒問題
    // 維護(hù)在線 Session 的線程安全 Map
    private static final ConcurrentHashMap<String, WebSocketSession> SESSION_MAP
            = new ConcurrentHashMap<>();
    /**
     * 連接建立成功時(shí)觸發(fā)
     */
    @Override
    public void afterConnectionEstablished(WebSocketSession session) throws Exception {
        String userId = (String) session.getAttributes().get("userId");
        SESSION_MAP.put(userId, session);
        System.out.printf("用戶 [%s] 已連接，當(dāng)前在線：%d%n", userId, SESSION_MAP.size());
    }
    /**
     * 收到文本消息時(shí)觸發(fā)
     */
    @Override
    protected void handleTextMessage(WebSocketSession session, TextMessage message)
            throws Exception {
        String userId = (String) session.getAttributes().get("userId");
        String payload = message.getPayload();
        System.out.printf("收到 [%s] 的消息：%s%n", userId, payload);
        // 調(diào)用業(yè)務(wù) Service
        messageService.saveMessage(userId, payload);
        // 廣播消息
        broadcastMessage(userId + ": " + payload);
    }
    /**
     * 連接關(guān)閉時(shí)觸發(fā)
     */
    @Override
    public void afterConnectionClosed(WebSocketSession session, CloseStatus status)
            throws Exception {
        String userId = (String) session.getAttributes().get("userId");
        SESSION_MAP.remove(userId);
        System.out.printf("用戶 [%s] 已斷開，當(dāng)前在線：%d%n", userId, SESSION_MAP.size());
    }
    /**
     * 傳輸異常時(shí)觸發(fā)
     */
    @Override
    public void handleTransportError(WebSocketSession session, Throwable exception)
            throws Exception {
        System.err.println("傳輸錯(cuò)誤：" + exception.getMessage());
        session.close(CloseStatus.SERVER_ERROR);
    }
    private void broadcastMessage(String message) {
        SESSION_MAP.values().forEach(s -> {
            try {
                if (s.isOpen()) {
                    s.sendMessage(new TextMessage(message));
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
        });
    }
}

java.lang.ClassCastException: class X cannot be cast to class Y

@ServerEndpoint("/ws/chat")
@Component
public class ChatServer {
    @Autowired
    private UserService userService;  // 運(yùn)行時(shí)是 null！
    @OnMessage
    public void onMessage(String msg) {
        userService.doSomething(msg);  // NullPointerException
    }
}

@ServerEndpoint("/ws/chat")
@Component
public class ChatServer {
    private static UserService userService;
    @Autowired  // Spring 對(duì)它管理的那個(gè)實(shí)例執(zhí)行此方法，寫入 static 字段
    public void setUserService(UserService userService) {
        ChatServer.userService = userService;
    }
}

// 嵌入式容器：需要
// 外部容器：刪掉這個(gè) Bean
@Bean
public ServerEndpointExporter serverEndpointExporter() {
    return new ServerEndpointExporter();
}

// 原生方式路徑示例
const ws1 = new WebSocket('ws://localhost:8080/ws/chat/room123');
// Spring 整合方式路徑示例（附帶 token 參數(shù)用于握手?jǐn)r截器驗(yàn)證）
const ws2 = new WebSocket('ws://localhost:8080/ws/chat?token=valid_user001');
ws2.onopen = () => {
    console.log('連接已建立');
    ws2.send(JSON.stringify({ type: 'chat', content: 'Hello!' }));
};
ws2.onmessage = (event) => {
    console.log('收到消息：', event.data);
};
ws2.onclose = (event) => {
    console.log('連接已關(guān)閉，code:', event.code);
};
ws2.onerror = (error) => {
    console.error('連接錯(cuò)誤：', error);
};

需要權(quán)限校驗(yàn)、Session 管理、與 Spring Security 集成？
    └── 選 Spring 整合方式（WebSocketHandler）
快速實(shí)現(xiàn)、團(tuán)隊(duì)熟悉 Java EE 規(guī)范、無復(fù)雜 Spring 生態(tài)依賴？
    └── 選原生方式（@ServerEndpoint）
需要打 war 包部署到外部 Tomcat？
    └── 兩種都行，但原生方式記得去掉 ServerEndpointExporter Bean
追求更強(qiáng)的消息抽象（發(fā)布訂閱、廣播頻道）？
    └── 考慮 Spring WebSocket + STOMP 協(xié)議（本文未涉及，可作進(jìn)階方向）