update 增加sse注释说明

ruoyi-common/ruoyi-common-sse/src/main/java/org/dromara/common/sse/controller/SseController.java

@@ -16,6 +16,11 @@ import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
 
 import java.util.List;
 
+/**
+ * SSE 控制器
+ *
+ * @author Lion Li
+ */
 @RestController
 @ConditionalOnProperty(value = "sse.enabled", havingValue = "true")
 @RequiredArgsConstructor
@@ -23,6 +28,9 @@ public class SseController implements DisposableBean {
 
     private final SseEmitterManager sseEmitterManager;
 
+    /**
+     * 建立 SSE 连接
+     */
     @GetMapping(value = "${sse.path}", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
     public SseEmitter connect() {
         String tokenValue = StpUtil.getTokenValue();
@@ -30,6 +38,9 @@ public class SseController implements DisposableBean {
         return sseEmitterManager.connect(userId, tokenValue);
     }
 
+    /**
+     * 关闭 SSE 连接
+     */
     @SaIgnore
     @GetMapping(value = "${sse.path}/close")
     public R<Void> close() {
@@ -39,6 +50,12 @@ public class SseController implements DisposableBean {
         return R.ok();
     }
 
+    /**
+     * 向特定用户发送消息
+     *
+     * @param userId 目标用户的 ID
+     * @param msg    要发送的消息内容
+     */
     @GetMapping(value = "${sse.path}/send")
     public R<Void> send(Long userId, String msg) {
         SseMessageDto dto = new SseMessageDto();
@@ -48,12 +65,20 @@ public class SseController implements DisposableBean {
         return R.ok();
     }
 
+    /**
+     * 向所有用户发送消息
+     *
+     * @param msg 要发送的消息内容
+     */
     @GetMapping(value = "${sse.path}/sendAll")
     public R<Void> send(String msg) {
         sseEmitterManager.publishAll(msg);
         return R.ok();
     }
 
+    /**
+     * 清理资源。此方法目前不执行任何操作，但避免因未实现而导致错误
+     */
     @Override
     public void destroy() throws Exception {
         // 销毁时不需要做什么 此方法避免无用操作报错

ruoyi-common/ruoyi-common-sse/src/main/java/org/dromara/common/sse/core/SseEmitterManager.java

@@ -13,8 +13,14 @@ import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.function.Consumer;
 
+/**
+ * 管理 Server-Sent Events (SSE) 连接
+ *
+ * @author Lion Li
+ */
 @Slf4j
 public class SseEmitterManager {
+
     /**
      * 订阅的频道
      */
@@ -22,24 +28,44 @@ public class SseEmitterManager {
 
     private final static Map<Long, Map<String, SseEmitter>> USER_TOKEN_EMITTERS = new ConcurrentHashMap<>();
 
+    /**
+     * 建立与指定用户的 SSE 连接
+     *
+     * @param userId 用户的唯一标识符，用于区分不同用户的连接
+     * @param token  用户的唯一令牌，用于识别具体的连接
+     * @return 返回一个 SseEmitter 实例，客户端可以通过该实例接收 SSE 事件
+     */
     public SseEmitter connect(Long userId, String token) {
+        // 从 USER_TOKEN_EMITTERS 中获取或创建当前用户的 SseEmitter 映射表（ConcurrentHashMap）
+        // 每个用户可以有多个 SSE 连接，通过 token 进行区分
         Map<String, SseEmitter> emitters = USER_TOKEN_EMITTERS.computeIfAbsent(userId, k -> new ConcurrentHashMap<>());
+
+        // 创建一个新的 SseEmitter 实例，超时时间设置为 0 表示无限制
         SseEmitter emitter = new SseEmitter(0L);
 
         emitters.put(token, emitter);
 
+        // 当 emitter 完成、超时或发生错误时，从映射表中移除对应的 token
         emitter.onCompletion(() -> emitters.remove(token));
         emitter.onTimeout(() -> emitters.remove(token));
         emitter.onError((e) -> emitters.remove(token));
 
         try {
+            // 向客户端发送一条连接成功的事件
             emitter.send(SseEmitter.event().comment("connected"));
         } catch (IOException e) {
+            // 如果发送消息失败，则从映射表中移除 emitter
             emitters.remove(token);
         }
         return emitter;
     }
 
+    /**
+     * 断开指定用户的 SSE 连接
+     *
+     * @param userId 用户的唯一标识符，用于区分不同用户的连接
+     * @param token  用户的唯一令牌，用于识别具体的连接
+     */
     public void disconnect(Long userId, String token) {
         Map<String, SseEmitter> emitters = USER_TOKEN_EMITTERS.get(userId);
         if (emitters != null) {

ruoyi-common/ruoyi-common-sse/src/main/java/org/dromara/common/sse/utils/SseMessageUtils.java

@@ -8,7 +8,7 @@ import org.dromara.common.sse.core.SseEmitterManager;
 import org.dromara.common.sse.dto.SseMessageDto;
 
 /**
- * 工具类
+ * SSE工具类
  *
  * @author Lion Li
  */