Scala下Play框架学习笔记（Body parsers）

2024-12-31 技术教程

什么是Body Parsers

一个HTTP请求是一个头部后面紧随着一个body，头部很小，可以在内存中缓存，因此Play的模型中使用了RequestHeader这个类。Body有时候也可能很长，以致于不能缓存，反而作为一种流而被建模。但是，许多请求体的有效载荷是小的，可以在内存中建模。因此描绘body流对于一个内存中的对象，Play提供BodyParser。

由于Play是一个异步框架，传统的InputStream方法不能用来读请求体，当你调用read方法时，输入流被阻塞，调用它的线程必须等到数据可用为止。Play使用一个异步流的库Akka Streams ，它是Reactive Streams 的一个实现，是一个允许许多异步流API无缝协同工作的SPI。因此虽然传统的InputStream不适合用在Play上，但是Akka Streams以及以Reactive Streams为核心的整个异步库的整个生态系统能提供你一切所需。

更多关于Actions

之前我们说过，Action是一个Request => Result类型的函数，这并不完全正确，让我们更仔细地看一下Action这个特质：

traitAction[A]extends(Request[A]=>Result){defparser:BodyParser[A]}

首先我们看到有一个原生类型A，一个Action必须被定义为BodyParser[A] ，另外Request[A]可以被定义如下：

traitRequest[+A]extendsRequestHeader{defbody:A}

A类型是请求体的类型，我们可以用任何Scala的类型来作为请求体的类型，例如String,NodeSeq,Array[Byte],JsonValue或者java.io.File，只要有一个body parser能够处理它就行。

总而言之，一个Action[A]会使用一个BodyParser[A]来从HTTP请求中检索A类型的值，来建立传递给Action代码的request[A]类型的对象。

使用内置的body parsers

许多典型的web apps都不需要使用客户端的body parsers，它们能使用Play内置的body parsers正常工作。包括JSON、XML、表单的解析器，还包括把plain text当做String来处理，把byte当做byteString来处理。

默认的body parser

当没有明确指定一个body parser的时候，默认的body parser会根据头部的content-type来解析body。举例来说，content-type是Application/json类型的话，会被解析成JSValue，content-type为application/x-www-form-urlencoded类型的会被解析成Map[String, Seq[String]]。

默认解析器产生的AnyContent类型的body，AnyContent能通过as类方法来支持各种类型，譬如asJson，返回body类型的一个Option类型：

defsave=Action{request=>valbody:AnyContent=request.bodyvaljsonBody:Option[JsValue]=body.asJson//ExpectingjsonbodyjsonBody.map{json=>Ok("Got:"+(json\"name").as[String])}.getOrElse{BadRequest("Expectingapplication/jsonrequestbody")}}

默认解析器支持以下类型之间的映射：

text/plain：通过asText转换成String。

application/json:通过asJson转换成JSValue。

application/xml,text/xml或者application/XXX+xml：通过asXML转换成scala.xml.NodeSeq

application/x-www-form-urlencoded：通过asFormUrlEncoded转换成Map[String, Seq[String]]

multipart/form-data：通过asMultipartFormData转换成MultipartFormData

任何其他的类型：通过asRaw转换成rawBuffer。

默认的body parser，出于性能的考虑，如果请求方法中没有定义一个有意义的body，就不会解析该请求方法的body，默认body parser只解析post、put、patch请求，而不会解析get、head、delete请求，如果要为这些方法解析请求体，就需要使用Anycontent Body Parser。

选择显式的body parser

如果需要显式地指定body parser，就需要向Action的apply或async方法传递一个body parser。

Play提供了许多框架之外的body parser，通过用Controllers引入BodyParsers.parse 对象来实现。举例说明，定义一个期望得到json body的Action如下：

defsave=Action(parse.json){request=>Ok("Got:"+(request.body\"name").as[String])}

注意到现在body的类型是JSValue，当它不再是Option类型时，工作变得相对简单。没有Option类型的原因是json body parser要验证一个请求有一个application/json的content-type，如果请求没达到期望，然后回送415 Unsupported Media Type应答。因此我们在Action代码中不用再次校验。

客户端必须发送正确的content-type头部，同时附上他们的请求。如果你想更轻松点，可以使用tolerantJson，这将会忽略content-type，尝试把body解析成json格式：

defsave=Action(parse.tolerantJson){request=>Ok("Got:"+(request.body\"name").as[String])}

另一个例子是把请求体放在文件里：

defsave=Action(parse.file(to=newFile("/tmp/upload"))){request=>Ok("Savedtherequestcontentto"+request.body)}

抽取用户名，给每一个用户一个独有的文件：

valstoreInUserFile=parse.using{request=>request.session.get("username").map{user=>file(to=newFile("/tmp/"+user+".upload"))}.getOrElse{sys.error("Youdon'thavetherighttouploadhere")}}defsave=Action(storeInUserFile){request=>Ok("Savedtherequestcontentto"+request.body)}

我们不是真正写一个自己的body parser，而是结合已有的body parser而已，这已经足够了，能涵盖大多数的实例。

最大内容长度

给予文本的body parser，譬如text,json,xml或者formUrlEncoded这些，使用最大内容长度限制，因为他们要将所有内容加载到内存，默认的能解析的最大内容长度是100KB，通过指定application.conf中的play.http.parser.maxMemoryBuffer就可以实现：

play.http.parser.maxMemoryBuffer=128K

对于一个解析器而言，在磁盘上的缓冲内容，譬如raw parser或者multipart/form-data，最大内容长度通过play.http.parser.maxDiskBuffer这一属性指定，默认10MB。为了数据域的统计，multipart/form-data解析器强制指定了文本最大长度这一属性。

在Action中也可以修改默认最大长度：

//Acceptonly10KBofdata.defsave=Action(parse.text(maxLength=1024*10)){request=>Ok("Got:"+text)}

写一个自定义的body parser：

通过实现body parser特质，可以实现一个自定义的body parser，body parser特质定义如下：

traitBodyParser[+A]extends(RequestHeader=>Accumulator[ByteString,Either[Result,A]])

这个特质传入的是一个RequestHeader对象，用来验证请求的合法性，只有得到content-type，请求才能被正确解析。特质的返回类型是Accumulator，一个accumulator在Akka StreamsSink中是轻量级的。一个accumulator会异步地将元素流汇集到result中，这可以通过在Akka StreamsSource中传递来执行。当accumulator结束工作的时候，会返回一个Future对象，这就相当于Sink[E, Future[A]]，一个类的封装类，不过有一个大的区别是，Accumulator提供便利的方法，如map,mapFuture,recover等。处理的是Result类型，因此好像是一个promise，可是Sink实际上所有类似的操作都被封装在mapMaterializedValue回调里。

Apply方法返回的accumulator产生ByteString类型的元素。这些实际上是Bytes数组，但和byte[]又有所区别， ByteString是不可变的，譬如切分和追加等操作都是在常量时间内完成的。

如果accumulator的返回类型是Either[Result, A] ，那么它会返回一个Result类型或A类型。A一般是抛出异常时返回的错误类型，这些错误包括解析失败、content-type和body parser接受的类型不匹配，或者缓冲区溢出。如果body parser 返回Result类型，它会缩短Action的过程，body parsers的Result会马上返回，Action永远不会被调用。

定位另一处的body

一个普通的用例是，当你向解析一个body，并且你希望在另一个地方流式化，此时需要自定义一个body parser：

import javax.inject._import play.api.mvc._import play.api.libs.streams._import play.api.libs.ws._import scala.concurrent.ExecutionContextimport akka.util.ByteStringclass MyController @Inject() (ws: WSClient)(implicit ec: ExecutionContext) { def forward(request: WSRequest): BodyParser[WSResponse] = BodyParser { req => Accumulator.source[ByteString].mapFuture { source => request // TODO: stream body when support is implemented // .withBody(source) .execute() .map(Right.apply) } } def myAction = Action(forward(ws.url("https://example.com"))) { req => Ok("Uploaded") }}

通过Akka Streams自定义解析

在极少数情况下会通过Akka Streams来写一个自定义解析器。通常先在ByteString中缓存body是没问题的，另一种更简易的途径在body上是使用必要的方法和随机存取。

当然也有不适合的时候，如果你的body需要解析的内容太长以致于内存中不能匹配合适的空间，这时候你需要写一个自定义解析器。

在来自ByteStrings的流的Parsing Lines下建立起来的CSV Parser，具体使用demo如下，文档来自于Akka Streams cookbook：

import play.api.mvc._import play.api.libs.streams._import play.api.libs.concurrent.Execution.Implicits.defaultContextimport akka.util.ByteStringimport akka.stream.scaladsl._ val csv: BodyParser[Seq[Seq[String]]] = BodyParser { req => // A flow that splits the stream into CSV lines val sink: Sink[ByteString, Future[Seq[Seq[String]]]] = Flow[ByteString] // We split by the new line character, allowing a maximum of 1000 characters per line .via(Framing.delimiter(ByteString("\n"), 1000, allowTruncation = true)) // Turn each line to a String and split it by commas .map(_.utf8String.trim.split(",").toSeq) // Now we fold it into a list .toMat(Sink.fold(Seq.empty[Seq[String]])(_ :+ _))(Keep.right) // Convert the body to a Right either Accumulator(sink).map(Right.apply)}