akka-http入门

Home

akka-http入门

Akka Cook

Directory

Akka HTTP是Lightbend提供的HTTP服务框架,它提供全面而且简单的API来创建HTTP服务器和客户端。这里注意区分,akka-http自身的定位并不是一个”web框架”。

其实之前用稍早版本的akka-http做过线上服务,吃压能力特别强,有简单的笔记,区别于之前构建方式,本文将会用最新的akka-http中的HttpApp trait新特性创建一个具备路由功能的简单的http服务器。体验学习过程建议在IntelliJ IDEA中进行。具体的配置方法可以参考链接:

GETTING STARTED WITH SCALA IN INTELLIJ

构建项目过程中需要用到包管理工具sbt,国内使用sbt下载包由于不可描述的原因比较慢,建议解决办法是:

  1. 系统全局翻墙,不保证速度和下载过程稳定,需要耐心
  2. 使用repox,目前国内使用sbt的首选,如果未来会经常用到sbt,建议自己搭一个

希望你可以在1~2个小时内搞定基础环境,折腾sbt的过程真的很受挫,而且在这方面一直也没有什么最优解。

build.sbt

在IDEA里创建scala sbt项目后,会自动创建好如下的结构:

├── build.sbt
├── project
│   ├── plugins.sbt
│   ├── ......
│── src
│   ├── main
│      └── java
│      └── scala
│── target
.....

build.sbt中添加项目依赖配置,保存后IDEA会自动下载依赖,相当于命令行下执行sbt update

name := "Hello-Akka"

version := "1.0"

scalaVersion := "2.11.7"

libraryDependencies += "com.typesafe.akka" %
  "akka-http_2.11" % "10.0.5"

Akka是一个活跃的项目,各种激进升级,为了保证能顺利练习,一定要用相同的版本号。

Minimal Http Server Code

接下来核心代码,在src/main/scala下右击New-Package创建一个包,这里起名叫package com.yangcongchufang.miniserver,然后在包下面右击new-scala class创建一个点选kind创建一个scala object,这里起名叫MinimalHttpServer

一切都还空空如也,现在我们在MinimalHttpServer.scala下面完成核心代码:

package com.yangcongchufang.miniserver

object MinimalHttpServer {

}

来了,今天的主角新特性HtppApp。akka-http引入该特性的目标就是为了精简一下构建http server代码的成本,目前尚属于一个试验性的特性。在过去如果想使用路由和各种控件需要引入一堆包,如今只需要一个akka.http.scaladsl.server.HttpApp就够了。

package com.yangcongchufang.miniserver

import akka.http.scaladsl.server.HttpApp

object MinimalHttpServer extends HttpApp {
}

object MinimalHttpServerApplication extends App {
  MinimalHttpServer.startServer("0.0.0.0", 8099)
}

一鼓作气,添加路由,在这里构建了两条路由,里面有一些控件get()/ post() / pathPrefix() / path() / complete() / entity() / Segment都是从HttpApp里继承而来,根据下面的测试例子跑一遍,相信你能猜出是干什么的:

package com.yangcongchufang.miniserver

import akka.http.scaladsl.server.HttpApp

object MinimalHttpServer extends HttpApp {
  def route =
    pathPrefix("v1") {
      path("id" / Segment) { id =>
        get {
          println("server get " + id)
          complete(s"got get request")
        } ~
          post {
            entity(as[String]) { entity =>
              println("server get " + entity)
              complete(s"got post request")
            }
          }
      }
    }
}

object MinimalHttpServerApplication extends App {
  MinimalHttpServer.startServer("0.0.0.0", 8099)
}

启动MinimalHttpServer.scala,右击该文件然后Run...

Press RETURN to stop...
[INFO] [09/15/2017 13:44:36.787] [MinimalHttpServer-akka.actor.default-dispatcher-3] [akka.actor.ActorSystemImpl(MinimalHttpServer)] Server online at http://0:0:0:0:0:0:0:0:8099/

直接使用curl测试API GET/POST /v1/id/ 请求,留意控制台上的所有log:

curl -X GET http://127.0.0.1:8099/v1/id/42

curl -X POST \
  http://127.0.0.1:8099/v1/id/42 \
  -d '{
	"to": "seek truth"
}'

截止目前,我们用HttpApp创建了一个简单的HTTP服务器程序,HttpApp特性提供了我们可能用到所有工具,它们被统称为routing DSL。使用HttpApp的过程好像一个堆积木的过程,我们用各种DSL最终拼凑成一个http程序。

JSON Support

最后部分,我们希望在已经构建好的路由中添加让它支持JSON,其实akka-http的前辈叫Spray,在Spray里提供了一个json库叫spray-json,就靠它了。akka-http官方项目中没有提供JSON支持,是因为akka的团队认为特殊数据格式序列化的事情不该归他们管,但是官方推荐了spray-json作为json序列化库。下面介绍如何用起来这个库。

首先在build.sbt中添加依赖:

name := "Hello-Akka"

version := "1.0"

scalaVersion := "2.11.7"

libraryDependencies += "com.typesafe.akka" %
  "akka-http_2.11" % "10.0.5"

libraryDependencies += "com.typesafe.akka" %
  "akka-http-spray-json_2.11" % "10.0.5"

等待依赖下载的过程中,在com.yangcongchufang.miniserver包中创建OrderModel.scala,我们将在这个文件里声明一堆表示数据结构的子类,并且用scala语言中的trait特性去让主工作函数继承实现对消息的序列化和反序列化的功能。

trait的作用其实和Java中的interfaces差不多,主要是为了在类之间共享接口和字段。类和对象都可以通过trait扩展功能,但是trait本身不能被实例化。

package com.packt.chapter9

import akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport
import spray.json.DefaultJsonProtocol

case class Item(
                 id: Int,
                 quantity: Int,
                 unitPrice: Double,
                 percentageDiscount: Option[Double]
               )

case class Order(
                  id: String,
                  timestamp: Long,
                  items: List[Item],
                  deliveryPrice: Double,
                  metadata: Map[String, String]
                )

case class GrandTotal(id: String, amount: Double)

trait OrderJsonSupport extends SprayJsonSupport with DefaultJsonProtocol {
  implicit val itemFormat = jsonFormat4(Item)
  implicit val orderFormat = jsonFormat5(Order)
  implicit val grandTotalFormat = jsonFormat2(GrandTotal)
}

修改httpserver,加入OrderJsonSupport

package com.yangcongchufang.miniserver

import akka.http.scaladsl.server.HttpApp
import scala.util.Random._

object MinimalHttpServer extends HttpApp with OrderJsonSupport{
  def route =
    pathPrefix("v1") {
      path("id" / Segment) { id =>
        get {
          println("server get " + id)
          complete(s"got get request")
        } ~
          post {
            entity(as[String]) { entity =>
              println("server get " + entity)
              complete(s"got post request")
            }
          }
      } ~
      path("json") {
        get {
          complete {
            genRandomOrder()
          }
        } ~
        post {
          entity(as[Order]) {order =>
            complete {
              calcGrandTotal(order)
            }
          }
        }
      }
    }

  private def calcGrandTotal(o: Order) = {
    val amount = o.items.map(
      i => i.percentageDiscount.getOrElse(1.0d)
        * i.unitPrice * i.quantity).sum + o.deliveryPrice
          GrandTotal(o.id, amount)
  }

  private def genRandomOrder(): Order = {
    val items = (0 to nextInt(5)).map(i => {
      Item(i, nextInt(100), 100 * nextDouble(),
        if (nextBoolean()) Some(nextDouble()) else None)
    }).toList
    Order(nextString(4), System.currentTimeMillis(),
      items, 100 * nextDouble(), Map("notes" -> "random"))
  }
}

object MinimalHttpServerApplication extends App {
  MinimalHttpServer.startServer("0.0.0.0", 8099)
}

这里对MinimalHttpServer做的改动需要注意:

  1. 使用with OrderJsonSupport的方式将trait接入
  2. route中新加了path("json"),在新添的route中构建了post和get两种json路由
  3. 最后complete { }返回里调用了两个不同的JSON处理函数

测试一下两条路由:

$ curl -X GET http://localhost:8099/v1/json

# 返回
{
    "deliveryPrice": 25.80591871167591,
    "id": "\u8970\u3977\ubb9c\u84a6",
    "items": [
        {
            "id": 0,
            "quantity": 83,
            "unitPrice": 62.42832568845077
        },
        {
            "id": 1,
            "percentageDiscount": 0.4797392901663512,
            "quantity": 14,
            "unitPrice": 87.56115612044673
        },
        {
            "id": 2,
            "quantity": 36,
            "unitPrice": 66.74811211906629
        },
        {
            "id": 3,
            "quantity": 50,
            "unitPrice": 85.1806727979387
        }
    ],
    "metadata": {
        "notes": "random"
    },
    "timestamp": 1505787587811
}

$ curl -X POST -H "Content-Type:application/json" --data '
{
   "deliveryPrice":95.3433758801223,
   "timestamp":1488135061123,
   "items":[
      {
         "id":0,
         "quantity":42,
         "unitPrice":65.01159569545462,
         "percentageDiscount":0.14585908649640444
      },
      {
         "id":1,
         "quantity":7,
         "unitPrice":27.047124705161696,
         "percentageDiscount":0.06400701658372476
      },
      {
         "id":2,
         "quantity":76,
         "unitPrice":24.028733083343724,
         "percentageDiscount":0.9906003213266685
      },
      {
         "id":3,
         "quantity":18,
         "unitPrice":88.77181117560474,
         "percentageDiscount":0.8203117015522584
      },
      {
         "id":4,
         "quantity":15,
         "unitPrice":29.73662623732769
      }
   ],
   "id":"randomId",
   "metadata":{
      "notes":"random"
   }
}
' http://localhost:8099/v1/json

# 返回
{"id":"randomId","amount":4071.565724845945}

这种处理JSON的情况是我们确认了已知的数据结构,清晰的定义了jsonFormat4、5,但是如果希望处理不定长的json数据结构就麻烦了,总不能为了适应各种情况,就定义jsonFormat4~100。相对容易的做法是使用play.api.libs.json._,文档写得很详细:

Playframework Converting to a JsValue

比如当我们从http消息体中取来一串json字符串,可以直接使用其提供的Json.parse()API将字符串转换成json:

import play.api.libs.json._

val json: JsValue = Json.parse("""
  {
    "name" : "Watership Down",
    "location" : {
      "lat" : 51.235685,
      "long" : -1.309197
    },
    "residents" : [ {
      "name" : "Fiver",
      "age" : 4,
      "role" : null
    }, {
      "name" : "Bigwig",
      "age" : 6,
      "role" : "Owsla"
    } ]
  }
  """)