nobodyxiaomi 2018-10-14
有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
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)
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
让我们来分析下这个例子: