Akka（32）： Http：High-Level-Api，Route exception handling
Akka-http routing DSL在Route运算中抛出的异常是由内向外浮出的：当内层Route未能捕获异常时，外一层Route会接着尝试捕捉，依次向外扩展。Akka-http提供了ExceptionHandler类来处理Route运算产生的异常：
trait ExceptionHandler extends ExceptionHandler.PF {
/**
* Creates a new [[ExceptionHandler]] which uses the given one as fallback for this one.
*/
def withFallback(that: ExceptionHandler): ExceptionHandler
/**
* "Seals" this handler by attaching a default handler as fallback if necessary.
*/
def seal(settings: RoutingSettings): ExceptionHandler
}
object ExceptionHandler {
type PF = PartialFunction[Throwable, Route]
private[http] val ErrorMessageTemplate: String = {
"Error during processing of request: '{}'. Completing with {} response. " +
"To change default exception handling behavior, provide a custom ExceptionHandler."
}
implicit def apply(pf: PF): ExceptionHandler = apply(knownToBeSealed = false)(pf)
private def apply(knownToBeSealed: Boolean)(pf: PF): ExceptionHandler =
new ExceptionHandler {
def isDefinedAt(error: Throwable) = pf.isDefinedAt(error)
def apply(error: Throwable) = pf(error)
def withFallback(that: ExceptionHandler): ExceptionHandler =
if (!knownToBeSealed) ExceptionHandler(knownToBeSealed = false)(this orElse that) else this
def seal(settings: RoutingSettings): ExceptionHandler =
if (!knownToBeSealed) ExceptionHandler(knownToBeSealed = true)(this orElse default(settings)) else this
}
def default(settings: RoutingSettings): ExceptionHandler =
apply(knownToBeSealed = true) {
case IllegalRequestException(info, status) ⇒ ctx ⇒ {
ctx.log.warning("Illegal request: '{}'. Completing with {} response.", info.summary, status)
ctx.complete((status, info.format(settings.verboseErrorMessages)))
}
case NonFatal(e) ⇒ ctx ⇒ {
val message = Option(e.getMessage).getOrElse(s"${e.getClass.getName} (No error message supplied)")
ctx.log.error(e, ErrorMessageTemplate, message, InternalServerError)
ctx.complete(InternalServerError)
}
}
/**
* Creates a sealed ExceptionHandler from the given one. Returns the default handler if the given one
* is `null`.
*/
def seal(handler: ExceptionHandler)(implicit settings: RoutingSettings): ExceptionHandler =
if (handler ne null) handler.seal(settings) else ExceptionHandler.default(settings)
}
简单来说ExceptionHandler类型就是一种PartialFunction：
trait ExceptionHandler extends PartialFunction[Throwable, Route]
因为ExceptionHandler就是PartialFunction，所以我们可以用case XXException来捕获需要处理的异常。留下未捕获的异常向外层Route浮出。当未处理异常到达最外层Route时统一由最顶层的handler处理。与RejectionHandler一样，最顶层的handler是通过Route.seal设置的：
/**
* "Seals" a route by wrapping it with default exception handling and rejection conversion.
*
* A sealed route has these properties:
* - The result of the route will always be a complete response, i.e. the result of the future is a
* ``Success(RouteResult.Complete(response))``, never a failed future and never a rejected route. These
* will be already be handled using the implicitly given [[RejectionHandler]] and [[ExceptionHandler]] (or
* the default handlers if none are given or can be found implicitly).
* - Consequently, no route alternatives will be tried that were combined with this route
* using the ``~`` on routes or the [[Directive.|]] operator on directives.
*/
def seal(route: Route)(implicit
routingSettings: RoutingSettings,
parserSettings: ParserSettings = null,
rejectionHandler: RejectionHandler = RejectionHandler.default,
exceptionHandler: ExceptionHandler = null): Route = {
import directives.ExecutionDirectives._
// optimized as this is the root handler for all akka-http applications
(handleExceptions(ExceptionHandler.seal(exceptionHandler)) & handleRejections(rejectionHandler.seal))
.tapply(_ ⇒ route) // execute above directives eagerly, avoiding useless laziness of Directive.addByNameNullaryApply
}
上面的exceptionHandler没有默认值，看起来好像有可能有些异常在整个Route运算里都不会被捕获。但实际上Akka-http提供了默认的handler ExceptionHandler.default：
/**
* Creates a sealed ExceptionHandler from the given one. Returns the default handler if the given one
* is `null`.
*/
def seal(handler: ExceptionHandler)(implicit settings: RoutingSettings): ExceptionHandler =
if (handler ne null) handler.seal(settings) else ExceptionHandler.default(settings)
通过这个ExceptionHandler.seal函数设置了最顶层的exception handler。
我们可以通过下面的方法来定制异常处理的方式：
自定义ExceptionHandler，然后：
1、把Exceptionhandler的隐式实例放在顶层Route的可视域内（implicit scope）
2、或者，直接调用handleExceptions，把自定义handler当作参数传入，把Route结构中间某层及其所有内层包嵌在handleExceptions中，例如：
val route: Route =
get {
pathSingleSlash {
complete(HttpEntity(ContentTypes.`text/html(UTF-8)`,"<html><body>Hello world!</body></html>"))
} ~
path("ping") {
handleExceptions(customExceptionHandler) {
onSuccess(Future.successful("ok"))
complete("PONG!")
}
} ~
path("crash") {
sys.error("BOOM!")
}
}
第一种办法是一种顶层对所有未捕获异常统一处理的方式，第二种办法可以限制处理区域针对某层以内的Route进行异常捕捉。
下面是第一种办法的使用示范：
object ExceptiontionHandlers {
implicit def implicitExceptionHandler: ExceptionHandler =
ExceptionHandler {
case _: ArithmeticException =>
extractUri { uri =>
complete(HttpResponse(InternalServerError, entity = s"$uri: Bad numbers, bad result!!!"))
}
}
def customExceptionHandler: ExceptionHandler =
ExceptionHandler {
case _: RuntimeException =>
extractUri { uri =>
complete(HttpResponse(InternalServerError, entity = s"$uri: Runtime exception!!!"))
}
}
}
第二种方式的使用示范如下：
val route: Route =
get {
pathSingleSlash {
complete(HttpEntity(ContentTypes.`text/html(UTF-8)`,"<html><body>Hello world!</body></html>"))
} ~
path("ping") {
onSuccess(Future.successful("ok"))
complete("PONG!")
} ~
handleExceptions(customExceptionHandler) {
path("crash") {
sys.error("BOOM!")
}
}
}
下面是本次讨论中的示范源代码：
import akka.actor._
import akka.http.scaladsl.Http
import akka.http.scaladsl.model._
import akka.http.scaladsl.server._
import akka.http.scaladsl.server.Directives._
import akka.stream._
import StatusCodes._
import scala.concurrent._
object ExceptiontionHandlers {
implicit def implicitExceptionHandler: ExceptionHandler =
ExceptionHandler {
case _: ArithmeticException =>
extractUri { uri =>
complete(HttpResponse(InternalServerError, entity = s"$uri: Bad numbers, bad result!!!"))
}
}
def customExceptionHandler: ExceptionHandler =
ExceptionHandler {
case _: RuntimeException =>
extractUri { uri =>
complete(HttpResponse(InternalServerError, entity = s"$uriRuntime exception!!!"))
}
}
}
object ExceptionHandlerDemo extends App {
import ExceptiontionHandlers._
implicit val httpSys = ActorSystem("httpSys")
implicit val httpMat = ActorMaterializer()
implicit val httpEc = httpSys.dispatcher
val (port, host) = (8011,"localhost")
val route: Route =
get {
pathSingleSlash {
complete(HttpEntity(ContentTypes.`text/html(UTF-8)`,"<html><body>Hello world!</body></html>"))
} ~
path("ping") {
onSuccess(Future.successful("ok"))
complete("PONG!")
} ~
handleExceptions(customExceptionHandler) {
path("crash") {
sys.error("BOOM!")
}
}
}
val bindingFuture: Future[Http.ServerBinding] = Http().bindAndHandle(route,host,port)
println(s"Server running at $host $port. Press any key to exit ...")
scala.io.StdIn.readLine()
bindingFuture.flatMap(_.unbind())
.onComplete(_ => httpSys.terminate())
}
