改进异常处理相关代码的注释和功能

为 XException 和相关类添加详细注释，优化命名和代码格式。新增 ExceptionHelper 扩展方法，包括网络异常判断、可忽略异常判断及获取根本原因功能。移除冗余代码，增强可读性，并改进中文注释以支持国际化。
2025-12-06 17:59:07 +08:00 · 2025-09-27 09:39:23 +08:00
parent 5815715c64
commit f9ea1d11b5
2 changed files with 151 additions and 109 deletions
--- a/NewLife.Core/Exceptions/XException.cs
+++ b/NewLife.Core/Exceptions/XException.cs
@@ -1,72 +1,117 @@
-using System;
-using System.ComponentModel;
+using System.ComponentModel;

 namespace NewLife;

 /// <summary>X组件异常</summary>
+/// <remarks>
+/// NewLife.X 组件库的通用异常类型，支持多种构造方式包括格式化字符串和内部异常包装。
+/// 提供了比标准异常更丰富的构造函数，便于快速创建异常实例。
+/// </remarks>
 [Serializable]
 public class XException : Exception
 {
-    #region 构造
-    /// <summary>初始化</summary>
+    #region 构造函数
+    /// <summary>初始化 X 组件异常实例</summary>
    public XException() { }

-    /// <summary>初始化</summary>
-    /// <param name="message"></param>
+    /// <summary>使用指定的错误消息初始化 X 组件异常实例</summary>
+    /// <param name="message">描述错误的消息</param>
    public XException(String message) : base(message) { }

-    /// <summary>初始化</summary>
-    /// <param name="format"></param>
-    /// <param name="args"></param>
+    /// <summary>使用指定的格式字符串和参数初始化 X 组件异常实例</summary>
+    /// <param name="format">复合格式字符串</param>
+    /// <param name="args">格式化参数数组</param>
    public XException(String format, params Object?[] args) : base(String.Format(format, args)) { }

-    /// <summary>初始化</summary>
-    /// <param name="message"></param>
-    /// <param name="innerException"></param>
+    /// <summary>使用指定的错误消息和内部异常初始化 X 组件异常实例</summary>
+    /// <param name="message">描述错误的消息</param>
+    /// <param name="innerException">导致当前异常的异常</param>
    public XException(String message, Exception innerException) : base(message, innerException) { }

-    /// <summary>初始化</summary>
-    /// <param name="innerException"></param>
-    /// <param name="format"></param>
-    /// <param name="args"></param>
+    /// <summary>使用内部异常、格式字符串和参数初始化 X 组件异常实例</summary>
+    /// <param name="innerException">导致当前异常的异常</param>
+    /// <param name="format">复合格式字符串</param>
+    /// <param name="args">格式化参数数组</param>
    public XException(Exception innerException, String format, params Object?[] args) : base(String.Format(format, args), innerException) { }

-    /// <summary>初始化</summary>
-    /// <param name="innerException"></param>
-    public XException(Exception innerException) : base((innerException?.Message), innerException) { }
+    /// <summary>使用内部异常初始化 X 组件异常实例，自动使用内部异常的消息</summary>
+    /// <param name="innerException">导致当前异常的异常</param>
+    public XException(Exception innerException) : base(innerException?.Message, innerException) { }

-    ///// <summary>初始化</summary>
-    ///// <param name="info"></param>
-    ///// <param name="context"></param>
+    ///// <summary>序列化构造函数</summary>
+    ///// <param name="info">序列化信息</param>
+    ///// <param name="context">序列化上下文</param>
    //protected XException(SerializationInfo info, StreamingContext context) : base(info, context) { }
    #endregion
 }

 /// <summary>异常事件参数</summary>
-public class ExceptionEventArgs : CancelEventArgs
+/// <remarks>
+/// 用于异常处理事件的参数类，继承自 CancelEventArgs 支持取消操作。
+/// 包含异常发生时的动作描述和具体异常信息。
+/// </remarks>
+/// <remarks>使用动作描述和异常实例初始化异常事件参数</remarks>
+/// <param name="action">异常发生时的动作描述</param>
+/// <param name="ex">发生的异常实例</param>
+public class ExceptionEventArgs(String action, Exception ex) : CancelEventArgs
 {
-    /// <summary>发生异常时进行的动作</summary>
-    public String Action { get; set; }
+    /// <summary>发生异常时进行的动作描述</summary>
+    /// <remarks>用于描述异常发生时正在执行的操作或上下文信息</remarks>
+    public String Action { get; set; } = action;

-    /// <summary>异常</summary>
-    public Exception Exception { get; set; }
-
-    /// <summary>实例化</summary>
-    /// <param name="action"></param>
-    /// <param name="ex"></param>
-    public ExceptionEventArgs(String action, Exception ex)
-    {
-        Action = action;
-        Exception = ex;
-    }
+    /// <summary>发生的异常实例</summary>
+    public Exception Exception { get; set; } = ex;
 }

-/// <summary>异常助手</summary>
+/// <summary>异常助手类</summary>
+/// <remarks>提供异常类型判断和处理的扩展方法</remarks>
 [EditorBrowsable(EditorBrowsableState.Never)]
 public static class ExceptionHelper
 {
-    /// <summary>是否对象已被释放异常</summary>
-    /// <param name="ex"></param>
-    /// <returns></returns>
+    /// <summary>判断异常是否为对象已释放异常</summary>
+    /// <param name="ex">要检查的异常实例</param>
+    /// <returns>如果是 ObjectDisposedException 则返回 true，否则返回 false</returns>
+    /// <remarks>用于快速识别由于访问已释放对象而引发的异常</remarks>
    public static Boolean IsDisposed(this Exception ex) => ex is ObjectDisposedException;
+
+    /// <summary>判断异常是否为网络相关异常</summary>
+    /// <param name="ex">要检查的异常实例</param>
+    /// <returns>如果是网络相关异常则返回 true，否则返回 false</returns>
+    /// <remarks>包括 HttpRequestException、SocketException、TimeoutException 等网络通信异常</remarks>
+    public static Boolean IsNetworkException(this Exception ex) => ex switch
+    {
+        System.Net.Http.HttpRequestException => true,
+        System.Net.Sockets.SocketException => true,
+        TimeoutException => true,
+        OperationCanceledException => true,
+        _ => false
+    };
+
+    /// <summary>判断异常是否为可忽略的常见异常</summary>
+    /// <param name="ex">要检查的异常实例</param>
+    /// <returns>如果是可忽略的异常则返回 true，否则返回 false</returns>
+    /// <remarks>
+    /// 用于判断是否为正常业务流程中可能出现的异常，如对象已释放、操作取消等。
+    /// 这类异常通常不需要记录错误日志或进行特殊处理。
+    /// </remarks>
+    public static Boolean IsIgnorable(this Exception ex) => ex switch
+    {
+        ObjectDisposedException => true,
+        TaskCanceledException => true,
+        OperationCanceledException => true,
+        _ => false
+    };
+
+    /// <summary>获取异常的根本原因</summary>
+    /// <param name="ex">要检查的异常实例</param>
+    /// <returns>最内层的异常实例</returns>
+    /// <remarks>递归获取 InnerException 直到最内层异常，用于获取问题的根本原因</remarks>
+    public static Exception GetBaseException(this Exception ex)
+    {
+        while (ex.InnerException != null)
+        {
+            ex = ex.InnerException;
+        }
+        return ex;
+    }
 }
--- a/NewLife.Core/Extension/BitHelper.cs
+++ b/NewLife.Core/Extension/BitHelper.cs
@@ -1,89 +1,86 @@
-using System;
+namespace NewLife;

-namespace NewLife
+/// <summary>数据位助手</summary>
+public static class BitHelper
 {
-    /// <summary>数据位助手</summary>
-    public static class BitHelper
+    /// <summary>设置数据位</summary>
+    /// <param name="value">数值</param>
+    /// <param name="position"></param>
+    /// <param name="flag"></param>
+    /// <returns></returns>
+    public static UInt16 SetBit(this UInt16 value, Int32 position, Boolean flag)
    {
-        /// <summary>设置数据位</summary>
-        /// <param name="value">数值</param>
-        /// <param name="position"></param>
-        /// <param name="flag"></param>
-        /// <returns></returns>
-        public static UInt16 SetBit(this UInt16 value, Int32 position, Boolean flag)
-        {
-            return SetBits(value, position, 1, (flag ? (Byte)1 : (Byte)0));
-        }
+        return SetBits(value, position, 1, (flag ? (Byte)1 : (Byte)0));
+    }

-        /// <summary>设置数据位</summary>
-        /// <param name="value">数值</param>
-        /// <param name="position"></param>
-        /// <param name="length"></param>
-        /// <param name="bits"></param>
-        /// <returns></returns>
-        public static UInt16 SetBits(this UInt16 value, Int32 position, Int32 length, UInt16 bits)
-        {
-            if (length <= 0 || position >= 16) return value;
+    /// <summary>设置数据位</summary>
+    /// <param name="value">数值</param>
+    /// <param name="position"></param>
+    /// <param name="length"></param>
+    /// <param name="bits"></param>
+    /// <returns></returns>
+    public static UInt16 SetBits(this UInt16 value, Int32 position, Int32 length, UInt16 bits)
+    {
+        if (length <= 0 || position >= 16) return value;

-            var mask = (2 << (length - 1)) - 1;
+        var mask = (2 << (length - 1)) - 1;

-            value &= (UInt16)~(mask << position);
-            value |= (UInt16)((bits & mask) << position);
+        value &= (UInt16)~(mask << position);
+        value |= (UInt16)((bits & mask) << position);

-            return value;
-        }
+        return value;
+    }

-        /// <summary>设置数据位</summary>
-        /// <param name="value">数值</param>
-        /// <param name="position"></param>
-        /// <param name="flag"></param>
-        /// <returns></returns>
-        public static Byte SetBit(this Byte value, Int32 position, Boolean flag)
-        {
-            if (position >= 8) return value;
+    /// <summary>设置数据位</summary>
+    /// <param name="value">数值</param>
+    /// <param name="position"></param>
+    /// <param name="flag"></param>
+    /// <returns></returns>
+    public static Byte SetBit(this Byte value, Int32 position, Boolean flag)
+    {
+        if (position >= 8) return value;

-            var mask = (2 << (1 - 1)) - 1;
+        var mask = (2 << (1 - 1)) - 1;

-            value &= (Byte)~(mask << position);
-            value |= (Byte)(((flag ? 1 : 0) & mask) << position);
+        value &= (Byte)~(mask << position);
+        value |= (Byte)(((flag ? 1 : 0) & mask) << position);

-            return value;
-        }
+        return value;
+    }

-        /// <summary>获取数据位</summary>
-        /// <param name="value">数值</param>
-        /// <param name="position"></param>
-        /// <returns></returns>
-        public static Boolean GetBit(this UInt16 value, Int32 position)
-        {
-            return GetBits(value, position, 1) == 1;
-        }
+    /// <summary>获取数据位</summary>
+    /// <param name="value">数值</param>
+    /// <param name="position"></param>
+    /// <returns></returns>
+    public static Boolean GetBit(this UInt16 value, Int32 position)
+    {
+        return GetBits(value, position, 1) == 1;
+    }

-        /// <summary>获取数据位</summary>
-        /// <param name="value">数值</param>
-        /// <param name="position"></param>
-        /// <param name="length"></param>
-        /// <returns></returns>
-        public static UInt16 GetBits(this UInt16 value, Int32 position, Int32 length)
-        {
-            if (length <= 0 || position >= 16) return 0;
+    /// <summary>获取数据位</summary>
+    /// <param name="value">数值</param>
+    /// <param name="position"></param>
+    /// <param name="length"></param>
+    /// <returns></returns>
+    public static UInt16 GetBits(this UInt16 value, Int32 position, Int32 length)
+    {
+        if (length <= 0 || position >= 16) return 0;

-            var mask = (2 << (length - 1)) - 1;
+        var mask = (2 << (length - 1)) - 1;

-            return (UInt16)((value >> position) & mask);
-        }
+        return (UInt16)((value >> position) & mask);
+    }

-        /// <summary>获取数据位</summary>
-        /// <param name="value">数值</param>
-        /// <param name="position"></param>
-        /// <returns></returns>
-        public static Boolean GetBit(this Byte value, Int32 position)
-        {
-            if (position >= 8) return false;
+    /// <summary>获取数据位</summary>
+    /// <param name="value">数值</param>
+    /// <param name="position"></param>
+    /// <returns></returns>
+    public static Boolean GetBit(this Byte value, Int32 position)
+    {
+        if (position >= 8) return false;

-            var mask = (2 << (1 - 1)) - 1;
+        var mask = (2 << (1 - 1)) - 1;

-            return ((Byte)((value >> position) & mask)) == 1;
-        }
+        return ((Byte)((value >> position) & mask)) == 1;
    }
 }