Spring WebSocket Scope 深度解析 🚀

🎯 核心概念理解

WebSocket Scope 是 Spring Framework 为 WebSocket 应用提供的一种特殊作用域机制。它解决了一个关键问题：如何在 WebSocket 会话的生命周期内管理和共享状态数据？

IMPORTANT

WebSocket Scope 让我们能够创建与特定 WebSocket 会话绑定的 Bean，这些 Bean 在会话期间保持状态，会话结束时自动销毁。

🤔 为什么需要 WebSocket Scope？

在传统的 HTTP 请求-响应模式中，我们有 request 和 session 作用域。但 WebSocket 是长连接，一个会话可能包含多次消息交互。如果没有 WebSocket Scope，我们会遇到以下问题：

❌ 问题场景

@Controller
class GameController {
    // 这样做有问题！所有WebSocket会话共享同一个实例
    private var gameState = GameState() 
    
    @MessageMapping("/move")
    fun handleMove(move: String) {
        // 多个玩家的游戏状态会互相干扰！
        gameState.processMove(move) 
    }
}

✅ 使用WebSocket Scope

@Component
@Scope(scopeName = "websocket", proxyMode = ScopedProxyMode.TARGET_CLASS)
class GameState {
    private var playerMoves = mutableListOf<String>()
    
    fun processMove(move: String) {
        playerMoves.add(move) // 每个WebSocket会话都有独立的状态
    }
}

📊 WebSocket Scope 工作原理

💡 实战应用场景

场景1：在线聊天室用户状态管理

用户状态Bean

@Component
@Scope(scopeName = "websocket", proxyMode = ScopedProxyMode.TARGET_CLASS)
class ChatUserSession {
    
    private lateinit var username: String
    private var joinTime: LocalDateTime = LocalDateTime.now()
    private val messageHistory = mutableListOf<String>()
    
    @PostConstruct
    fun init() {
        println("用户会话初始化: ${Thread.currentThread().name}")
    }
    
    fun setUsername(name: String) {
        this.username = name
    }
    
    fun addMessage(message: String) {
        messageHistory.add("[$username] $message")
    }
    
    fun getMessageCount(): Int = messageHistory.size
    
    @PreDestroy
    fun destroy() {
        println("用户 $username 离开聊天室，共发送 ${messageHistory.size} 条消息")
    }
}

聊天控制器

@Controller
class ChatController(
    private val chatUserSession: ChatUserSession
) {
    
    @MessageMapping("/chat.join")
    fun joinChat(username: String, headerAccessor: SimpMessageHeaderAccessor) {
        // 设置用户名到当前WebSocket会话的Bean中
        chatUserSession.setUsername(username) 
        
        // 也可以通过会话属性访问
        val sessionAttrs = headerAccessor.sessionAttributes
        sessionAttrs["username"] = username
    }
    
    @MessageMapping("/chat.send")
    @SendTo("/topic/messages")
    fun sendMessage(message: String): String {
        // 记录消息到当前用户会话
        chatUserSession.addMessage(message) 
        
        return message
    }
    
    @MessageMapping("/chat.stats")
    @SendToUser("/queue/stats")
    fun getUserStats(): Map<String, Any> {
        return mapOf(
            "messageCount" to chatUserSession.getMessageCount(), 
            "sessionDuration" to "计算会话时长..."
        )
    }
}

场景2：游戏状态管理

@Component
@Scope(scopeName = "websocket", proxyMode = ScopedProxyMode.TARGET_CLASS)
class GameSession {
    
    private var gameId: String = UUID.randomUUID().toString()
    private var playerScore: Int = 0
    private var gameLevel: Int = 1
    private val gameEvents = mutableListOf<GameEvent>()
    
    @PostConstruct
    fun initGame() {
        println("游戏会话开始: $gameId")
        gameEvents.add(GameEvent("GAME_START", LocalDateTime.now()))
    }
    
    fun updateScore(points: Int) {
        playerScore += points
        if (playerScore > gameLevel * 100) {
            levelUp()
        }
    }
    
    private fun levelUp() {
        gameLevel++
        gameEvents.add(GameEvent("LEVEL_UP", LocalDateTime.now()))
    }
    
    fun getCurrentState(): GameState {
        return GameState(gameId, playerScore, gameLevel)
    }
    
    @PreDestroy
    fun endGame() {
        gameEvents.add(GameEvent("GAME_END", LocalDateTime.now()))
        println("游戏结束: $gameId, 最终得分: $playerScore, 等级: $gameLevel")
        // 可以在这里保存游戏记录到数据库
    }
}

data class GameEvent(val type: String, val timestamp: LocalDateTime)
data class GameState(val gameId: String, val score: Int, val level: Int)

⚠️ 重要注意事项

WARNING

使用 WebSocket Scope 时必须配置 proxyMode = ScopedProxyMode.TARGET_CLASS，因为控制器通常是单例，生命周期比 WebSocket 会话更长。

TIP

WebSocket-scoped Bean 支持完整的 Spring 生命周期回调（@PostConstruct 和 @PreDestroy），这使得资源管理变得非常方便。

🔧 配置和最佳实践

1. 正确的代理模式配置

@Component
@Scope(
    scopeName = "websocket", 
    proxyMode = ScopedProxyMode.TARGET_CLASS 
)
class MyWebSocketBean {
    // Bean 实现
}

2. 访问会话属性的两种方式

方式1: 通过HeaderAccessor

@MessageMapping("/action")
fun handleMessage(
    message: String,
    headerAccessor: SimpMessageHeaderAccessor
) {
    val sessionAttrs = headerAccessor.sessionAttributes 
    sessionAttrs["lastMessage"] = message
}

方式2: 通过WebSocket-scoped Bean

@MessageMapping("/action")
fun handleMessage(
    message: String,
    myBean: MyWebSocketBean
) {
    // myBean 自动来自当前 WebSocket 会话
    myBean.processMessage(message) 
}

3. 完整的配置示例

完整的WebSocket配置类

@Configuration
@EnableWebSocketMessageBroker
class WebSocketConfig : WebSocketMessageBrokerConfigurer {
    
    override fun configureMessageBroker(config: MessageBrokerRegistry) {
        config.enableSimpleBroker("/topic", "/queue")
        config.setApplicationDestinationPrefixes("/app")
        config.setUserDestinationPrefix("/user")
    }
    
    override fun registerStompEndpoints(registry: StompEndpointRegistry) {
        registry.addEndpoint("/ws")
            .setAllowedOriginPatterns("*")
            .withSockJS()
    }
    
    // 注册WebSocket作用域（Spring Boot通常自动配置）
    @Bean
    fun webSocketScope(): Scope {
        return SimpleThreadScope() // 实际实现会更复杂
    }
}

🎉 总结

WebSocket Scope 是 Spring 为长连接应用提供的优雅解决方案，它让我们能够：

• ✅ 状态隔离：每个 WebSocket 会话拥有独立的 Bean 实例
• ✅ 生命周期管理：自动处理 Bean 的创建和销毁
• ✅ 依赖注入：无缝集成 Spring 的 DI 容器
• ✅ 资源清理：会话结束时自动清理资源

NOTE

WebSocket Scope 特别适用于需要在整个 WebSocket 会话期间维护状态的场景，如在线游戏、实时协作工具、聊天应用等。

通过合理使用 WebSocket Scope，我们可以构建出更加健壮和可维护的实时应用程序！ 🎯