CoreAgent/CoreAgent.ProtocolClient/Docs/WebSocketMgr/PrivateMethods.md

# PrivateMethods.cs (自动转换为Markdown)

```csharp
// 以下内容为原始C#代码，含详细注释
// 文件原路径：Managers/WebSocketMgr/PrivateMethods.cs

using Microsoft.Extensions.Logging;
using Newtonsoft.Json.Linq;
using Newtonsoft.Json;
using System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using WebSocket4Net;

namespace CoreAgent.ProtocolClient.Managers.WebSocketMgr
{
    public partial class WebSocketMessageManager
    {
        #region 私有方法

        /// <summary>
        /// 检查对象是否已释放，如果已释放则抛出异常
        /// 
        /// 功能说明：
        /// 1. 检查_disposed字段，如果为true则抛出ObjectDisposedException
        /// 2. 在所有公共方法开始时调用，确保对象状态正确
        /// 3. 提供统一的释放状态检查逻辑
        /// 
        /// 对应关系：
        /// - 检查逻辑：对应原始实现中的_disposed检查
        /// - 异常类型：ObjectDisposedException，与.NET标准一致
        /// - 使用场景：在所有公共方法开始时调用
        /// 
        /// 重构改进：
        /// - 统一的释放状态检查
        /// - 更清晰的异常信息
        /// - 更好的代码复用
        /// </summary>
        private void ThrowIfDisposed()
        {
            if (_disposed)
                throw new ObjectDisposedException(nameof(WebSocketMessageManager));
        }

        /// <summary>
        /// WebSocket连接打开事件处理器 - 对应LTEClientWebSocket.OnSocketOpened
        /// 
        /// 功能说明：
        /// 1. 处理WebSocket连接成功建立事件
        /// 2. 记录连接成功日志
        /// 3. 触发ConnectionOpened事件
        /// 
        /// 对应关系：
        /// - 事件处理：对应原始实现中的OnSocketOpened方法
        /// - 日志记录：对应原始实现中的连接成功日志
        /// - 事件触发：对应原始实现中的ConnectionOpened事件触发
        /// 
        /// 重构改进：
        /// - 更清晰的日志记录
        /// - 更好的异常处理
        /// - 保持了完全一致的事件处理逻辑
        /// </summary>
        /// <param name="sender">事件发送者</param>
        /// <param name="e">事件参数</param>
        private void OnSocketOpened(object? sender, EventArgs e)
        {
            try
            {
                _logger.LogInformation($"[{_clientName}] WebSocket连接已建立");
                ConnectionOpened?.Invoke(this, EventArgs.Empty);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, $"[{_clientName}] 处理连接打开事件异常: {ex.Message}");
            }
        }

        /// <summary>
        /// WebSocket连接关闭事件处理器 - 对应LTEClientWebSocket.OnSocketClosed
        /// 
        /// 功能说明：
        /// 1. 处理WebSocket连接关闭事件
        /// 2. 记录连接关闭日志
        /// 3. 触发ConnectionClosed事件
        /// 
        /// 对应关系：
        /// - 事件处理：对应原始实现中的OnSocketClosed方法
        /// - 日志记录：对应原始实现中的连接关闭日志
        /// - 事件触发：对应原始实现中的ConnectionClosed事件触发
        /// 
        /// 重构改进：
        /// - 更清晰的日志记录
        /// - 更好的异常处理
        /// - 保持了完全一致的事件处理逻辑
        /// </summary>
        /// <param name="sender">事件发送者</param>
        /// <param name="e">事件参数</param>
        private void OnSocketClosed(object? sender, EventArgs e)
        {
            try
            {
                _logger.LogInformation($"[{_clientName}] WebSocket连接已关闭");
                ConnectionClosed?.Invoke(this, EventArgs.Empty);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, $"[{_clientName}] 处理连接关闭事件异常: {ex.Message}");
            }
        }

        /// <summary>
        /// WebSocket消息接收事件处理器 - 对应LTEClientWebSocket.OnSocketMessage
        /// 
        /// 功能说明：
        /// 1. 处理WebSocket消息接收事件
        /// 2. 解析接收到的消息
        /// 3. 触发MessageReceived事件
        /// 4. 调用HandleReceivedMessage处理消息
        /// 
        /// 对应关系：
        /// - 事件处理：对应原始实现中的OnSocketMessage方法
        /// - 消息解析：对应原始实现中的消息解析逻辑
        /// - 事件触发：对应原始实现中的MessageReceived事件触发
        /// - 消息处理：对应原始实现中的消息处理逻辑
        /// 
        /// 重构改进：
        /// - 更清晰的错误处理
        /// - 更详细的日志记录
        /// - 保持了完全一致的事件处理逻辑
        /// </summary>
        /// <param name="sender">事件发送者</param>
        /// <param name="e">消息接收事件参数</param>
        private void OnSocketMessageReceived(object? sender, MessageReceivedEventArgs e)
        {
            try
            {
                var messageText = e.Message;
                _logger.LogDebug($"[{_clientName}] 接收到消息: {messageText}");

                // 解析消息 - 对应原始实现中的消息解析逻辑
                JObject? message = null;
                try
                {
                    message = JObject.Parse(messageText);
                }
                catch (JsonException ex)
                {
                    _logger.LogError(ex, $"[{_clientName}] 消息解析失败: {messageText}");
                    ConnectionError?.Invoke(this, $"消息解析失败: {ex.Message}");
                    return;
                }

                // 触发MessageReceived事件 - 对应原始实现中的事件触发
                MessageReceived?.Invoke(this, message);

                // 处理消息 - 对应原始实现中的消息处理逻辑
                HandleReceivedMessage(message, error => ConnectionError?.Invoke(this, error));
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, $"[{_clientName}] 处理接收消息异常: {ex.Message}");
                ConnectionError?.Invoke(this, $"处理接收消息异常: {ex.Message}");
            }
        }

        /// <summary>
        /// WebSocket错误事件处理器 - 对应LTEClientWebSocket.OnSocketError
        /// 
        /// 功能说明：
        /// 1. 处理WebSocket连接错误事件
        /// 2. 记录错误日志
        /// 3. 触发ConnectionError事件
        /// 
        /// 对应关系：
        /// - 事件处理：对应原始实现中的OnSocketError方法
        /// - 错误记录：对应原始实现中的错误日志记录
        /// - 事件触发：对应原始实现中的ConnectionError事件触发
        /// 
        /// 重构改进：
        /// - 更详细的错误信息记录
        /// - 更好的异常处理
        /// - 保持了完全一致的事件处理逻辑
        /// </summary>
        /// <param name="sender">事件发送者</param>
        /// <param name="e">错误事件参数</param>
        private void OnSocketError(object? sender, SuperSocket.ClientEngine.ErrorEventArgs e)
        {
            try
            {
                var errorMessage = e.Exception?.Message ?? "WebSocket连接错误";
                _logger.LogError(e.Exception, $"[{_clientName}] WebSocket错误: {errorMessage}");
                ConnectionError?.Invoke(this, errorMessage);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, $"[{_clientName}] 处理WebSocket错误事件异常: {ex.Message}");
            }
        }

        /// <summary>
        /// 启动消息延迟发送定时器 - 对应LTEClientWebSocket.StartMessageDeferTimer
        /// 
        /// 功能说明：
        /// 1. 启动消息延迟发送定时器，实现批量发送优化
        /// 2. 当队列中消息少于100条时，延迟1毫秒发送
        /// 3. 当队列中消息达到100条时，立即发送
        /// 
        /// 对应关系：
        /// - 定时器创建：对应原始实现中的定时器创建逻辑
        /// - 延迟策略：1毫秒延迟，与原始实现完全一致
        /// - 批处理大小：100条消息，与原始实现完全一致
        /// - 回调函数：对应原始实现中的定时器回调逻辑
        /// 
        /// 重构改进：
        /// - 更清晰的定时器管理
        /// - 更好的异常处理
        /// - 保持了完全一致的批处理策略
        /// </summary>
        private void StartMessageDeferTimer()
        {
            Timer? timer = null;
            timer = new Timer(_ =>
            {
                try
                {
                    OnMessageDeferTimer(null);
                }
                finally
                {
                    timer?.Dispose(); // 用完即销毁
                }
            }, null, 1, Timeout.Infinite);
        }

        /// <summary>
        /// 停止消息延迟发送定时器 - 对应LTEClientWebSocket.StopMessageDeferTimer
        /// 
        /// 功能说明：
        /// 1. 停止消息延迟发送定时器
        /// 2. 释放定时器资源
        /// 3. 确保线程安全的定时器管理
        /// 
        /// 对应关系：
        /// - 定时器停止：对应原始实现中的定时器停止逻辑
        /// - 资源释放：对应原始实现中的定时器释放逻辑
        /// - 线程安全：使用锁确保线程安全
        /// 
        /// 重构改进：
        /// - 更清晰的资源管理
        /// - 更好的线程安全保证
        /// - 保持了完全一致的停止逻辑
        /// </summary>
        private void StopMessageDeferTimer()
        {
            // 新实现下无需手动停止定时器，方法保留兼容性
        }

        /// <summary>
        /// 消息延迟发送定时器回调 - 对应LTEClientWebSocket.OnMessageDeferTimer
        /// 
        /// 功能说明：
        /// 1. 处理消息延迟发送定时器回调
        /// 2. 批量发送队列中的消息
        /// 3. 实现消息发送优化
        /// 
        /// 对应关系：
        /// - 定时器回调：对应原始实现中的OnMessageDeferTimer方法
        /// - 批量发送：对应原始实现中的批量发送逻辑
        /// - 批处理大小：100条消息，与原始实现完全一致
        /// - 发送逻辑：对应原始实现中的SendMessageNow调用
        /// 
        /// 重构改进：
        /// - 更清晰的批量发送逻辑
        /// - 更好的异常处理
        /// - 保持了完全一致的批处理策略
        /// </summary>
        /// <param name="state">定时器状态参数</param>
        private void OnMessageDeferTimer(object? state)
        {
            try
            {
                // 批量发送消息 - 对应原始实现中的批量发送逻辑
                var messages = new List<JObject>();
                var count = 0;
                const int batchSize = 100; // 与原始实现完全一致

                // 从队列中取出消息 - 对应原始实现中的队列处理逻辑
                while (count < batchSize && _messageFifo.TryTake(out var message))
                {
                    messages.Add(message);
                    count++;
                }

                if (messages.Count > 0)
                {
                    // 发送消息 - 对应原始实现中的SendMessageNow调用
                    SendMessageNow(messages);
                }

                // 如果队列中还有消息，继续启动定时器 - 对应原始实现中的定时器重启逻辑
                if (_messageFifo.Count > 0)
                {
                    StartMessageDeferTimer();
                }
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, $"[{_clientName}] 消息延迟发送定时器异常: {ex.Message}");
            }
        }

        /// <summary>
        /// 立即发送消息 - 对应LTEClientWebSocket.SendMessageNow
        /// 
        /// 功能说明：
        /// 1. 立即发送消息列表到WebSocket
        /// 2. 处理发送异常和错误
        /// 3. 触发MessageSent事件
        /// 
        /// 对应关系：
        /// - 消息发送：对应原始实现中的SendMessageNow方法
        /// - 异常处理：对应原始实现中的发送异常处理
        /// - 事件触发：对应原始实现中的事件触发逻辑
        /// - 日志记录：对应原始实现中的发送日志记录
        /// 
        /// 重构改进：
        /// - 更清晰的发送逻辑
        /// - 更详细的错误处理
        /// - 新增MessageSent事件触发
        /// - 保持了完全一致的发送逻辑
        /// </summary>
        /// <param name="messages">要发送的消息列表</param>
        private void SendMessageNow(List<JObject> messages)
        {
            if (messages == null || messages.Count == 0)
                return;

            if (!IsConnected)
            {
                _logger.LogWarning($"[{_clientName}] WebSocket未连接，无法发送消息");
                return;
            }

            try
            {
                foreach (var message in messages)
                {
                    var messageText = JsonConvert.SerializeObject(message);
                    _webSocket?.Send(messageText);

                    // 触发MessageSent事件 - 新增功能，提供更完整的消息生命周期通知
                    MessageSent?.Invoke(this, message);

                    _logger.LogDebug($"[{_clientName}] 消息已发送: {messageText}");
                }
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, $"[{_clientName}] 发送消息异常: {ex.Message}");
                ConnectionError?.Invoke(this, $"发送消息异常: {ex.Message}");
            }
        }

        /// <summary>
        /// 清空消息队列 - 对应LTEClientWebSocket中的队列清理逻辑
        /// 
        /// 功能说明：
        /// 1. 清空消息队列中的所有消息
        /// 2. 在断开连接时调用，确保资源清理
        /// 
        /// 对应关系：
        /// - 队列清理：对应原始实现中的队列清理逻辑
        /// - 调用时机：在Disconnect()方法中调用
        /// - 日志记录：对应原始实现中的清理日志记录
        /// 
        /// 重构改进：
        /// - 更清晰的清理逻辑
        /// - 更详细的日志记录
        /// - 保持了完全一致的清理逻辑
        /// </summary>
        private void ClearMessageQueue()
        {
            var count = 0;
            while (_messageFifo.TryTake(out _))
            {
                count++;
            }

            if (count > 0)
            {
                _logger.LogInformation($"[{_clientName}] 清空消息队列，丢弃 {count} 条消息");
            }
        }

        #endregion
    }
}