Util应用框架基础(五) - 异常处理

本节介绍Util应用框架如何处理系统错误.

概述

系统在运行过程中可能发生错误.

系统错误可以简单分为两类:

• 系统异常

  系统本身出现的错误.

• 业务异常

  不满足业务规则出现的错误.

如何处理系统异常

如果发生系统异常,大多数情况下,你除了记录异常日志外,可能无法处理它们.

一个例外是并发异常.

当发生并发异常,可以通过重试再次提交,有可能成功处理.

另外一个问题,是否应该将系统异常消息返回给客户端?

系统异常消息与技术相关,客户无法理解它们.

而且系统异常消息可能包含敏感信息,返回给客户端可能更易受到攻击.

如何处理业务异常

业务异常表明没有满足某些业务规则,通常也无法自动处理.

如果能够自动处理的业务异常,应定义专用异常类型.

对于业务异常,除了记录异常日志外,还应把业务异常消息返回给客户端,以指示用户调整操作.

基础用法

.Net 使用异常 Exception 及派生异常来处理系统异常,但没有明确规定处理业务异常的类型.

Warning 业务异常

Util应用框架定义了 Util.Exceptions.Warning 异常类型,Warning 从 Exception 派生,代表业务异常.

当你抛出 Exception 或派生异常类型时,异常消息仅在开发阶段返回给客户端.

一旦发布到生产环境,系统异常消息将被屏蔽,客户端收到消息: 系统忙，请稍后再试 .

throw new Exception( "未将对象引用设置到对象的实例" );

对于业务规则导致的错误,你需要抛出 Warning 异常.

Warning 抛出的异常消息将返回到客户端,提示用户进行修改.

throw new Warning( "必须填写姓名" );

GetMessage 工具方法

Warning 除了代表业务异常外,还提供了一个静态工具方法 GetMessage.

异常可能被其它异常包裹,要获得异常真正的消息,需要使用递归.

Warning.GetMessage 工具方法传入异常实例,递归获取异常消息,

var message = Warning.GetMessage( exception );

ConcurrencyException 并发异常

Util应用框架定义了并发异常 Util.Exceptions.ConcurrencyException.

不同的 .Net 组件抛出的并发异常类型可能不同, Util使用 ConcurrencyException 进行统一包装.

可以通过重试的方式来解决并发异常.

下面是Util应用框架Dapr集成事件增加计数时并发处理的代码片断.

public virtual async Task IncrementAsync( CancellationToken cancellationToken = default ) {
    try {
        await Store.IncrementAsync( cancellationToken );
    }
    catch ( ConcurrencyException ) {
        Log.LogDebug( "更新集成事件计数出现并发异常,即将重试" );
        await IncrementAsync( cancellationToken );
    }
    catch ( Exception exception ) {
        Log.LogError( exception, "更新集成事件计数失败" );
    }
}

全局错误日志记录

Util应用框架使用 ErrorLogFilterAttribute 过滤器来记录全局错误日志.

已在 Web Api控制器基类 WebApiControllerBase 设置 [ErrorLogFilter] 过滤器.

全局异常处理

Util应用框架使用 ExceptionHandlerAttribute 过滤器来处理全局异常.

已在 Web Api控制器基类 WebApiControllerBase 设置 [ExceptionHandler] 过滤器.

[ExceptionHandler] 过滤器对异常消息进行处理,只有 Warning 异常消息才会返回给客户端.

源码解析

Warning 业务异常

Warning 代表业务异常,它的异常消息会返回给客户端.

GetMessage 方法使用递归获取内部异常消息.

/// <summary>
/// 应用程序异常
/// </summary>
public class Warning : Exception {
    /// <summary>
    /// 初始化应用程序异常
    /// </summary>
    /// <param name="exception">异常</param>
    public Warning( Exception exception )
        : this( null, exception ) {
    }

    /// <summary>
    /// 初始化应用程序异常
    /// </summary>
    /// <param name="message">错误消息</param>
    /// <param name="exception">异常</param>
    /// <param name="code">错误码</param>
    /// <param name="httpStatusCode">Http状态码</param>
    public Warning( string message, Exception exception = null, string code = null, int? httpStatusCode = null )
        : base( message ?? "", exception ) {
        Code = code;
        HttpStatusCode = httpStatusCode;
        IsLocalization = true;
    }

    /// <summary>
    /// 错误码
    /// </summary>
    public string Code { get; set; }

    /// <summary>
    /// Http状态码
    /// </summary>
    public int? HttpStatusCode { get; set; }

    /// <summary>
    /// 是否本地化异常消息
    /// </summary>
    public bool IsLocalization { get; set; }

    /// <summary>
    /// 获取错误消息
    /// </summary>
    /// <param name="isProduction">是否生产环境</param>
    public virtual string GetMessage( bool isProduction = false ) {
        return GetMessage( this );
    }

    /// <summary>
    /// 获取错误消息
    /// </summary>
    public static string GetMessage( Exception ex ) {
        var result = new StringBuilder();
        var list = GetExceptions( ex );
        foreach( var exception in list )
            AppendMessage( result, exception );
        return result.ToString().Trim( Environment.NewLine.ToCharArray() );
    }

    /// <summary>
    /// 添加异常消息
    /// </summary>
    private static void AppendMessage( StringBuilder result, Exception exception ) {
        if( exception == null )
            return;
        result.AppendLine( exception.Message );
    }

    /// <summary>
    /// 获取异常列表
    /// </summary>
    public IList<Exception> GetExceptions() {
        return GetExceptions( this );
    }

    /// <summary>
    /// 获取异常列表
    /// </summary>
    /// <param name="ex">异常</param>
    public static IList<Exception> GetExceptions( Exception ex ) {
        var result = new List<Exception>();
        AddException( result, ex );
        return result;
    }

    /// <summary>
    /// 添加内部异常
    /// </summary>
    private static void AddException( List<Exception> result, Exception exception ) {
        if( exception == null )
            return;
        result.Add( exception );
        AddException( result, exception.InnerException );
    }
}

ConcurrencyException 并发异常

ConcurrencyException 表示并发异常,统一包装其它组件产生的并发异常,并处理异常消息.

/// <summary>
/// 并发异常
/// </summary>
public class ConcurrencyException : Warning {
    /// <summary>
    /// 消息
    /// </summary>
    private readonly string _message;

    /// <summary>
    /// 初始化并发异常
    /// </summary>
    public ConcurrencyException()
        : this( "" ) {
    }

    /// <summary>
    /// 初始化并发异常
    /// </summary>
    /// <param name="exception">异常</param>
    public ConcurrencyException( Exception exception )
        : this( "", exception ) {
    }

    /// <summary>
    /// 初始化并发异常
    /// </summary>
    /// <param name="message">错误消息</param>
    /// <param name="exception">异常</param>
    /// <param name="code">错误码</param>
    /// <param name="httpStatusCode">Http状态码</param>
    public ConcurrencyException( string message, Exception exception = null, string code = null, int? httpStatusCode = null )
        : base( message, exception, code, httpStatusCode ) {
        _message = message;
    }

    /// <inheritdoc />
    public override string Message => $"{R.ConcurrencyExceptionMessage}.{_message}";

    /// <inheritdoc />
    public override string GetMessage( bool isProduction = false ) {
        if( isProduction )
            return R.ConcurrencyExceptionMessage;
        return GetMessage(this);
    }
}

ErrorLogFilterAttribute 错误日志过滤器

[ErrorLogFilter] 错误日志过滤器记录全局异常日志.

/// <summary>
/// 错误日志过滤器
/// </summary>
public class ErrorLogFilterAttribute : ExceptionFilterAttribute {
    /// <summary>
    /// 异常处理
    /// </summary>
    public override void OnException( ExceptionContext context ) {
        if( context == null )
            return;
        var log = context.HttpContext.RequestServices.GetService<ILogger<ErrorLogFilterAttribute>>();
        var exception = context.Exception.GetRawException();
        if( exception is Warning warning ) {
            log.LogWarning( warning, exception.Message );
            return;
        }
        log.LogError( exception, exception.Message );
    }
}

ExceptionHandlerAttribute 异常处理过滤器

[ExceptionHandler] 过滤器处理全局异常.

Exception 的扩展方法 GetPrompt 获取客户端友好的异常消息.

对于生产环境, Exception 异常消息将被替换为 系统忙，请稍后再试.

[ExceptionHandler] 过滤器还对异常消息的本地化进行了处理.

/// <summary>
/// 异常处理过滤器
/// </summary>
public class ExceptionHandlerAttribute : ExceptionFilterAttribute {
    /// <summary>
    /// 异常处理
    /// </summary>
    public override void OnException( ExceptionContext context ) {
        context.ExceptionHandled = true;
        var message = context.Exception.GetPrompt( Web.Environment.IsProduction() );
        message = GetLocalizedMessages( context, message );
        var errorCode = context.Exception.GetErrorCode() ?? StateCode.Fail;
        var httpStatusCode = context.Exception.GetHttpStatusCode() ?? 200;
        context.Result = GetResult( context, errorCode, message, httpStatusCode );
    }

    /// <summary>
    /// 获取本地化异常消息
    /// </summary>
    protected virtual string GetLocalizedMessages( ExceptionContext context, string message ) {
        var exception = context.Exception.GetRawException();
        if ( exception is Warning { IsLocalization: false } ) 
            return message;
        var stringLocalizerFactory = context.HttpContext.RequestServices.GetService<IStringLocalizerFactory>();
        if ( stringLocalizerFactory == null )
            return message;
        var stringLocalizer = stringLocalizerFactory.Create( "Warning",null );
        var localizedString = stringLocalizer[message];
        if ( localizedString.ResourceNotFound == false )
            return localizedString.Value;
        stringLocalizer = context.HttpContext.RequestServices.GetService<IStringLocalizer>();
        if ( stringLocalizer == null )
            return message;
        return stringLocalizer[message];
    }

    /// <summary>
    /// 获取结果
    /// </summary>
    protected virtual IActionResult GetResult( ExceptionContext context, string code, string message, int? httpStatusCode ) {
        var options = GetJsonSerializerOptions( context );
        var resultFactory = context.HttpContext.RequestServices.GetService<IResultFactory>();
        if ( resultFactory == null )
            return new Result( code, message, null, httpStatusCode, options );
        return resultFactory.CreateResult( code, message, null, httpStatusCode, options );
    }

    /// <summary>
    /// 获取Json序列化配置
    /// </summary>
    private JsonSerializerOptions GetJsonSerializerOptions( ExceptionContext context ) {
        var factory = context.HttpContext.RequestServices.GetService<IJsonSerializerOptionsFactory>();
        if( factory != null )
            return factory.CreateOptions();
        return new JsonSerializerOptions {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            Encoder = JavaScriptEncoder.Create( UnicodeRanges.All ),
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
            Converters = {
                new DateTimeJsonConverter(),
                new NullableDateTimeJsonConverter()
            }
        };
    }
}

/// <summary>
/// 异常扩展
/// </summary>
public static class ExceptionExtensions {
    /// <summary>
    /// 获取异常提示
    /// </summary>
    /// <param name="exception">异常</param>
    /// <param name="isProduction">是否生产环境</param>
    public static string GetPrompt( this Exception exception, bool isProduction = false ) {
        if( exception == null )
            return null;
        exception = exception.GetRawException();
        if( exception == null )
            return null;
        if( exception is Warning warning )
            return warning.GetMessage( isProduction );
        return isProduction ? R.SystemError : exception.Message;
    }

    /// <summary>
    /// 获取Http状态码
    /// </summary>
    /// <param name="exception">异常</param>
    public static int? GetHttpStatusCode( this Exception exception ) {
        if ( exception == null )
            return null;
        exception = exception.GetRawException();
        if ( exception == null )
            return null;
        if ( exception is Warning warning )
            return warning.HttpStatusCode;
        return null;
    }

    /// <summary>
    /// 获取错误码
    /// </summary>
    /// <param name="exception">异常</param>
    public static string GetErrorCode( this Exception exception ) {
        if ( exception == null )
            return null;
        exception = exception.GetRawException();
        if ( exception == null )
            return null;
        if ( exception is Warning warning )
            return warning.Code;
        return null;
    }
}