Akka HTTP：自定义指令（Directive）

自定义指令

有3种建立自定义指令的基本方法：

1. 将已有指令经过命名配置（好比经过组合的方式）的方式来定义新的指令
2. 转换已存在的指令
3. 从头开始实现一个指令

命名配置

建立自定义指令最简便的方法就是将一个或多个已有指令经过配置的方式分配一个新的名字来定义。事实上Akka HTTP预约义的大多数指令都由以较低级别指令命名配置的方式来定义的。如：

val getPut = get & put

def postEntity[T](um: FromRequestUnmarshaller[T]): Directive1[T] = post & entity(um)

def completeOk: Route = complete(HttpEntity.Empty)

def completeNotImplemented: Route = complete(StatusCodes.NotImplemented)

转换已存在的指令

第二种方式是经过“转换方法”来转换现有指令，这是在Directive类上定义的方法：

• map/tmap
• flatMap/tflatMap
• require/trequire
• recover/recoverPF

map、tmap

map、tmap就和Scala集合库上的map转换相似，它能够将值映射转换成另外一个值。map用于Directive1类型的指令（单值指令），而tmap用于值为其它元组的状况，它的签名以下：

def tmap[R](f: L => R): Directive[Out]

tmap能够用来将提取的元组转换成另外一个元组，提取的数量和类型均可以改变，而map只用改变变换后的类型。以下是一个虚构的例子：

val twoIntParameters: Directive[(Int, Int)] =
  parameters(("a".as[Int], "b".as[Int]))

val myDirective: Directive1[String] =
  twoIntParameters.tmap {
    case (a, b) => (a + b).toString
  }

// tests:
Get("/?a=2&b=5") ~> myDirective(x => complete(x)) ~> check {
  responseAs[String] mustBe "7"
}

flatMap、tflatMap

经过map、tmap能够将指令抽取的值转换成其它值，但不能改变其“抽取”的性质。当须要抽取一个对它作一些转换操做，并将结果交给一个嵌套的指令使用时，map、tmap就无能为力了。同map、tmap相似，flatMap也是用于单值指令，而tflatMap用于其它元组值。tflatMap的函数签名以下：

def tflatMap[R: Tuple](f: L => Directive[R]): Directive[R]

能够看一个例子，预约义的method指令，它的定义以下：

def method(httpMethod: HttpMethod): Directive0 =
  extractMethod.flatMap[Unit] {
    case `httpMethod` => pass
    case _            => reject(MethodRejection(httpMethod))
  } & cancelRejections(classOf[MethodRejection])

val get: Directive0 = method(HttpMethods.GET)
val post: Directive0 = method(HttpMethods.POST)

1. 经过调用extractMethod指令获取请求的HTTP方法，再经过flatMap[Unit]转换方法对它进行处理。由于extractMethod是一个单值指令且转换后值为Unit（也是个单值），这里调用flatMap方法。
2. 当请求的实际HTTP方法与传入参数httpMethod匹配时，调用pass指令使其经过，不然调用reject(MethodRejection(httpMethod))拒绝。

require、trequire

require方法将单个指令转换为没有抽取值的指令，该指令根据谓词函数过滤请求，全部谓词函数调用后为false的请求都被拒绝，其它请求保持不变。它的定义以下：

def require(predicate: T => Boolean, rejections: Rejection*): Directive0 =
  underlying.filter(predicate, rejections: _*).tflatMap(_ => Empty)

从定义能够看出，它其实是先经过谓词函数调用filter方法对请求进行过滤，而后再调用tflatMap函数将指令抽取的值去掉。

recover、recoverPF

recover方法容许“捕获”由底层指令向上冒泡产生的rejections，并生成且有相同抽取类型的替代指令。这样就能够恢复指令来经过而不是拒绝它。它们的定义分别以下：

def recover[R >: L: Tuple](recovery: immutable.Seq[Rejection] => Directive[R]): Directive[R] =
  Directive[R] { inner => ctx =>
    import ctx.executionContext
    @volatile var rejectedFromInnerRoute = false
    tapply({ list => c => rejectedFromInnerRoute = true; inner(list)(c) })(ctx).fast.flatMap {
      case RouteResult.Rejected(rejections) if !rejectedFromInnerRoute => recovery(rejections).tapply(inner)(ctx)
      case x => FastFuture.successful(x)
    }
  }

def recoverPF[R >: L: Tuple](recovery: PartialFunction[immutable.Seq[Rejection], Directive[R]]): Directive[R] =
  recover { rejections => recovery.applyOrElse(rejections, (rejs: Seq[Rejection]) => RouteDirectives.reject(rejs: _*)) }

从头开始实现一个指令

能够经过调用Directive.apply或它的子类型来从头开始定义一个指令，Directive的简化定义看起来像下面这样：

abstract class Directive[L](implicit val ev: Tuple[L]) {
  def tapply(f: L => Route): Route
}

object Directive {

  /**
   * Constructs a directive from a function literal.
   */
  def apply[T: Tuple](f: (T => Route) => Route): Directive[T] =
    new Directive[T] { def tapply(inner: T => Route) = f(inner) }

}

Directive类型有一个抽象方法tapply，参数f是一个函数类型，将类型L传入并返回Route。Directive的伴身对象提供了apply来实现自定义指令。它的参数是一个高阶函数(T => Route) => Route，就像小括号那样，咱们应把（T => Route)当作一个总体，它是函数参数，返回类型为Route。

f为咱们自定义指令用于从RequestContext里抽取值（值的类型为Tuple[L]），而inner就是f抽取值后调用的嵌套路由，在调用inner时将抽取出的值做为参数传入。

对于一个抽取访问host和port的指令，能够这样实现：

def hostnameAndPort: Directive[(String, Int)] = Directive[(String, Int)] { inner => ctx =>
  // inner: (String, Int) => Route
  // ctx: RequestContext

  val authority: Uri.Authority = ctx.request.uri.authority
  val tupleValue: (String, Int) = (authority.host.address(), authority.port)
  val route: Route = inner(tupleValue)
  route(ctx) // Future[RouteResult]
}

Full source at GitHub

让咱们来分析下这个例子：

1. 首先是hostnameAndPort指令的类型Directive[(String, Int)]，它从请求上下文（RequestContext）中抽取出的值是Tuple2[String, Int]。
2. apply方法执行的代码参数是：inner => ctx => ....其实能够当作：inner => ((ctx: RequestContext) => Future[RouteResult])，inner就是f函数参数(T => Route）部分。
3. inner(tupleValue)执行后结果route的类型是Route，这时这段代码为的类型就为inner => ctx => Route，而实际上Directive.apply须要的参数类型为inner => Route。以前咱们知道，Route是一个类型别名RequestContext => Future[RouteResult]，因此咱们须要将ctx => Route转换为Route。而将tupleValue做为参数调用route后将获取结果类型Future[RouteResult]，这段代码的类型就是inner => ctx => Future[RouteResult] -> inner => Route。

本文节选自《Scala Web开发》，更多内容请访问：https://www.yangbajing.me/scala-web-development/server-api/routing-dsl/custom-directive.html 。