异常处理

ABP提供了用于处理Web应用程序异常的标准模型.

  • 自动 处理所有异常 .如果是API/AJAX请求,会向客户端返回一个标准格式化后的错误消息 .
  • 自动隐藏 内部详细错误 并返回标准错误消息.
  • 为异常消息的 本地化 提供一种可配置的方式.
  • 自动为标准异常设置 HTTP状态代码 ,并提供可配置选项,以映射自定义异常.

自动处理异常

当满足下面任意一个条件时,AbpExceptionFilter 会处理此异常:

  • controller action方法返回类型是object result(而不是view result)并有异常抛出时.
  • 当一个请求为AJAX(Http请求头中X-Requested-WithXMLHttpRequest)时.
  • 当客户端接受的返回类型为application/json(Http请求头中acceptapplication/json)时.

如果异常被处理过,则会自动记录日志并将格式化的JSON消息返回给客户端.

错误消息格式

每个错误消息都是RemoteServiceErrorResponse 类的实例.最简单的错误JSON只有一个 Message 属性,如下所示:

  1. {
  2. "error": {
  3. "message": "This topic is locked and can not add a new message"
  4. }
  5. }

其它可选字段可以根据已发生的异常来填充.

错误代码

错误 代码(code) 是异常信息中一个有唯一值并可选的字符串值.抛出的异常应实现IHasErrorCode 接口来填充该字段.示例JSON如下:

  1. {
  2. "error": {
  3. "code": "App:010042",
  4. "message": "This topic is locked and can not add a new message"
  5. }
  6. }

错误代码同样可用于异常信息的本地化及自定义HTTP状态代码(请参阅下面的相关部分).

错误详细信息

错误的 详细信息(Details) 是可选属性.抛出的异常应实现IHasErrorDetails 接口来填充该字段.示例JSON如下:

  1. {
  2. "error": {
  3. "code": "App:010042",
  4. "message": "This topic is locked and can not add a new message",
  5. "details": "A more detailed info about the error..."
  6. }
  7. }
验证错误

当抛出的异常实现IHasValidationErrors 接口时,validationErrors是一个可被填充的标准字段.示例JSON如下:

  1. {
  2. "error": {
  3. "code": "App:010046",
  4. "message": "Your request is not valid, please correct and try again!",
  5. "validationErrors": [{
  6. "message": "Username should be minimum length of 3.",
  7. "members": ["userName"]
  8. },
  9. {
  10. "message": "Password is required",
  11. "members": ["password"]
  12. }]
  13. }
  14. }

AbpValidationException已经实现了IHasValidationErrors接口,当请求输入无效时,框架会自动抛出此错误. 因此,除非你有自定义的验证逻辑,否则不需要处理验证错误.

日志

被捕获的异常会被自动记录到日志中.

日志级别

默认情况下,记录异常级别为Error .可以通过实现IHasLogLevel 接口来指定日志的级别,例如:

  1. public class MyException : Exception, IHasLogLevel
  2. {
  3. public LogLevel LogLevel { get; set; } = LogLevel.Warning;
  4. //...
  5. }
异常自定义日志

某些异常类型可能需要记录额外日志信息.可以通过实现IExceptionWithSelfLogging 接口来记录指定日志,例如:

  1. public class MyException : Exception, IExceptionWithSelfLogging
  2. {
  3. public void Log(ILogger logger)
  4. {
  5. //...log additional info
  6. }
  7. }

扩展方法ILogger.LogException 用来记录异常日志. 在需要时可以使用相同的扩展方法.

业务异常

大多数异常都是业务异常.可以通过使用IBusinessException 接口来标记异常为业务异常.

BusinessException 除了实现IHasErrorCode,IHasErrorDetails ,IHasLogLevel 接口外,还实现了IBusinessException 接口.其默认日志级别为Warning.

通常你会将一个错误代码关联至特定的业务异常.例如:

  1. throw new BusinessException(QaErrorCodes.CanNotVoteYourOwnAnswer);

QaErrorCodes.CanNotVoteYourOwnAnswer 是一个字符串常量. 建议使用下面的错误代码格式:

  1. <code-namespace>:<error-code>

code-namespace,应在指定的模块/应用层中保证其唯一.例如:

  1. Volo.Qa:010002

Volo.Qa在这是作为code-namespace. code-namespace 同样可以在 本地化 异常信息时使用.

  • 你可以直接抛出一个 BusinessException 异常,或者需要时可以从该类派生你自己的Exception类型.
  • 对于BusinessException 类型,其所有属性都是可选的.但是通常会设置ErrorCodeMessage属性.

异常本地化

这里有个问题,就是如何在发送错误消息到客户端时,对错误消息进行本地化.ABP提供了2个模型.

用户友好异常

如果异常实现了 IUserFriendlyException 接口,那么ABP不会修改 MessageDetails属性,而直接将它发送给客户端.

UserFriendlyException 类是内建的 IUserFriendlyException 接口的实现,示例如下:

  1. throw new UserFriendlyException(
  2. "Username should be unique!"
  3. );

采用这种方式是不需要本地化的.如果需要本地化消息,则可以注入string localizer( 请参阅本地化文档 )来实现. 例:

  1. throw new UserFriendlyException(_stringLocalizer["UserNameShouldBeUniqueMessage"]);

再在本地化资源中为每种语言添加对应的定义.例如:

  1. {
  2. "culture": "en",
  3. "texts": {
  4. "UserNameShouldBeUniqueMessage": "Username should be unique!"
  5. }
  6. }

string localizer 支持参数化信息.例如

  1. throw new UserFriendlyException(_stringLocalizer["UserNameShouldBeUniqueMessage", "john"]);

其本地化文本如下:

  1. "UserNameShouldBeUniqueMessage": "Username should be unique! '{0}' is already taken!"
  • IUserFriendlyException接口派生自IBusinessException,而 UserFriendlyException类派生自BusinessException类.

使用错误代码

UserFriendlyException很好用,但是在一些高级用法里面,它存在以下问题:

  • 在抛出异常的地方必须注入string localizer 来实现本地化 .
  • 但是,在某些情况下,可能注入不了string localizer(比如,在静态上下文或实体方法中)

那么这时就可以通过使用 错误代码 的方式来处理本地化,而不是在抛出异常的时候.

首先,在模块配置代码中将 code-namespace 映射至 本地化资源:

  1. services.Configure<AbpExceptionLocalizationOptions>(options =>
  2. {
  3. options.MapCodeNamespace("Volo.Qa", typeof(QaResource));
  4. });

然后Volo.Qa命名空间下的所有异常都将被对应的本地化资源进行本地化处理. 本地化资源中应包含对应错误代码的文本. 例如:

  1. {
  2. "culture": "en",
  3. "texts": {
  4. "Volo.Qa:010002": "You can not vote your own answer!"
  5. }
  6. }

最后就可以抛出一个包含错误代码的业务异常了:

  1. throw new BusinessException(QaDomainErrorCodes.CanNotVoteYourOwnAnswer);
  • 抛出所有实现IHasErrorCode 接口的异常都具有相同的行为.因此,对错误代码的本地化,并不是BusinessException类所特有的.
  • 为错误消息定义本地化文本并不是必须的. 如果未定义,ABP会将默认的错误消息发送给客户端. 而不使用异常的Message属性. 如果你想要发送异常的Message,使用UserFriendlyException(或使用实现IUserFriendlyException接口的异常类型)
使用消息的格式化参数

如果有参数化的错误消息,则可以使用异常的Data属性进行设置.例如:

  1. throw new BusinessException("App:010046")
  2. {
  3. Data =
  4. {
  5. {"UserName", "john"}
  6. }
  7. };

另外有一种更为快捷的方式:

  1. throw new BusinessException("App:010046")
  2. .WithData("UserName", "john");

下面就是一个包含UserName 参数的错误消息:

  1. {
  2. "culture": "en",
  3. "texts": {
  4. "App:010046": "Username should be unique. '{UserName}' is already taken!"
  5. }
  6. }
  • WithData 支持有多个参数的链式调用 (如.WithData(...).WithData(...)).

HTTP状态代码映射

ABP尝试按照以下规则,自动映射常见的异常类型的HTTP状态代码:

  • 对于 AbpAuthorizationException:
    • 用户没有登录,返回 401 (未认证).
    • 用户已登录,但是当前访问未授权,返回 403 (未授权).
  • 对于 AbpValidationException 返回 400 (错误的请求) .
  • 对于 EntityNotFoundException返回 404 (未找到).
  • 对于 IBusinessExceptionIUserFriendlyException (它是IBusinessException的扩展) 返回403 (未授权) .
  • 对于 NotImplementedException 返回 501 (未实现) .
  • 对于其他异常 (基础架构中未定义的) 返回 500 (服务器内部错误) .

IHttpExceptionStatusCodeFinder 是用来自动判断HTTP状态代码.默认的实现是DefaultHttpExceptionStatusCodeFinder.可以根据需要对其进行更换或扩展.

自定义映射

可以重写HTTP状态代码的自动映射,示例如下:

  1. services.Configure<AbpExceptionHttpStatusCodeOptions>(options =>
  2. {
  3. options.Map("Volo.Qa:010002", HttpStatusCode.Conflict);
  4. });

内置的异常

框架会自动抛出以下异常类型:

  • 当用户没有权限执行操作时,会抛出 AbpAuthorizationException 异常. 有关更多信息,请参阅授权文档authorization.
  • 如果当前请求的输入无效,则抛出AbpValidationException 异常. 有关更多信息,请参阅验证文档.
  • 如果请求的实体不存在,则抛出EntityNotFoundException 异常. 此异常大多数由 repositories 抛出.

你同样可以在代码中抛出这些类型的异常(虽然很少需要这样做)

发送异常详情到客户端

你可以通过 AbpExceptionHandlingOptions 类的 SendExceptionsDetailsToClients 属性异常发送到客户端:

  1. services.Configure<AbpExceptionHandlingOptions>(options =>
  2. {
  3. options.SendExceptionsDetailsToClients = true;
  4. });