Akka-HTTP - ルーティングDSLの基本となるPathMatcherのまとめ

2016-05-17

Path を構築するための DSL であるDirectiveとPathMathcerについて。ドキュメントは以下。 The PathMatcher DSL — Akka Documentation

tl;dr

大体ここに書いてある。 The PathMatcher DSL — Akka Documentation

spray も参考になる。 Path Filters · spray/spray Wiki

PathMatcher

Path を作るための型といえるもの。ドキュメントの Overview にあるようにPathMatcherの型は以下のようになっている。

trait PathMatcher[L: Tuple]
type PathMatcher0 = PathMatcher[Unit]
type PathMatcher1[T] = PathMatcher[Tuple1[T]]

リクエストがあった Path に対してマッチするかどうかの判定を行い、マッチする場合は pass して内側の処理に入り、マッチしなかった場合は reject して次の Path 判定にうつる。 PathMatcherNはpathに与えるとDirectiveNが得られるようになっている。

文字列

Path を定義する基本となるはずのやつ。文字列でルーティングを定義する。

val route = path("ping") {
  get {
    complete("pong")
  }
}

これにlocalhost:8080/pingに GET リクエストを送るとpongと返ってくる。 getを使用して GET であることを明示しているが、HTTP メソッドは指定しなければ GET となる

正規表現を使いたい場合

pathにRegexオブジェクトを渡すだけでよい。

val route = path("[abc]+".r) { rgx: String =>
  get {
    complete(s"matched: $rgx")
  }
}

このrgxには正規表現のグループ数によってバインドされる文字列が変化し、グループ数が 0 の場合は正規表現として与えた文字列が、1 の場合はそのグループとしてマッチした文字列が得られる。注意点として、正規表現のグループ数が 1 より大きい場合は使用できず、実行時例外が throw されてしまう。なおグループ数はこのように求められる。(akka/EnhancedRegex.scala)

"regex".r.pattern.matcher("").groupCount()

グループ数が 0 の場合

val route =
  path("hello_.+".r) { rgx: String =>
    get {
      complete(s"matched: $rgx")
    }
  }

正規表現にマッチした文字列全体が得られる。

$ curl 'http://localhost:8080/alice'
The requested resource could not be found.
$ curl 'http://localhost:8080/hello_alice'
matched: hello_alice%

グループ数が 1 の場合

aかbかc(hoge|foo|bar)か、というちょっと変わった例。

val route =
  path("a|b|c(hoge|foo|bar)+".r) { rgx: String =>
    get {
      complete(s"matched: $rgx")
    }
  }

この場合、rgxにはグループにマッチした文字列が入る。つまりcfooにリクエストを送るとfooが得られることとなる。

$ curl 'http://localhost:8080/cfoo'
matched: foo

グループにマッチする文字列が無い場合はnullが渡ってきてしまう点に注意

$ curl 'http://localhost:8080/a'
matched: null

Path に数値を入れたい場合

用意されているIntNumberやHexLongNumberを使えば Path として与えた数字がオブジェクトとして得られる。

val routes = pathPrefix("ping") {
  path(IntNumber) { i =>
    get {
      complete(s"int: $i")
    }
  } ~
  path(LongNumber) { l =>
    get {
      complete(s"long: $l")
    }
  } ~
  path(DoubleNumber) { d =>
    get {
      complete(s"double: $d")
    }
  } ~
  path(HexIntNumber) { hi =>
    get {
      complete(s"hexInt: $hi")
    }
  } ~
  path(HexLongNumber) { hl =>
    get {
      complete(s"hexLong: $hl")
    }
  }
}

$ curl http://localhost:8080/ping/1
int: 1

$ curl http://localhost:8080/ping/10000000000000000
long: 10000000000000000

$ curl http://localhost:8080/ping/1.0
double: 1.0

$ curl http://localhost:8080/ping/fff
hexInt: 4095

$ curl http://localhost:8080/ping/ffffffffffff
hexLong: 281474976710655%

なお、path(HexXxxNumber) { ??? }をpath(XxxNumber) { ??? }より前に持ってくると HexXxxNumberでキャッチされてしまい、XxxNumberの path には入ってこないため、併用する場合は注意が必要。

Map で Path を作る

pathにはMap[String, T]を与えることが出来る。

val map: Map[String, Long] = Map(
  "one" -> 1L,
  "two" -> 2L,
  "three" -> 3L
)

val route =
  path(map) { l: Long =>
    complete(s"long: $l")
  }

深い Path を実装する

深い階層になった Path を表現するにはいくつか方法がある。例としてこのような Path を考える。

GET /nice/user
GET /nice/user/greet
GET /nice/user/hello  # .../greetと同じ挙動とする
GET /nice/user/<name>

pathEnd, pathPrefix, pathSuffix を使う

さっそく、例として上げたルーティングを実装するとこのようになる。

val route =
  pathPrefix("nice") {  // /nice/...
    pathPrefix("user") {  // /nice/user/...
      pathEnd {  // nice/user
        complete("nice user!")
      } ~
        pathSuffix("greet" | "hello") {  // nice/user/.../greet
          complete(s"hello!")
        } ~
        pathPrefix(".+".r) { name =>  // /nice/user/<name>/...
          pathEndOrSingleSlash {  // /nice/user/<name> or /nice/user/<name>/
            complete(s"nice name => $name")
          }
        }
    }
  }

.../greetと.../helloが同じ挙動で、それを表現するには|を使用すれば良い。この route に対するリクエストとレスポンスは以下のようになる。

$ curl 'localhost:8080/nice/user'
nice user!
$ curl 'localhost:8080/nice/user/'
The requested resource could not be found.
$ curl 'localhost:8080/nice/user/greet'
hello!
$ curl 'localhost:8080/nice/user/hello'
hello!
$ curl 'localhost:8080/nice/user/greet/'
nice name => greet
$ curl 'localhost:8080/nice/user/alice'
nice name => alice
$ curl 'localhost:8080/nice/user/alice/'
nice name => alice

それぞれの違いを簡単に書くと以下。(ほぼ英単語そのままの意味)

pathEnd, pathEndOrSingleSlash
- Path の終わり
- 後ろに/がつくかどうかの違い
pathPrefix
- Path の先頭に来るもの
- PathPrefixを組み合わせると深い Path を作ることが出来る
pathSuffix
- Path の終端に来るもの

とくにpathSuffixは終端にあればマッチして処理されてしまうため、思ってない動きをすることもある。例えば以下のように、適当な Path へのリクエストを正常に処理してしまう。 (もちろん、 ~ path("greet")とすれば問題ないが、あくまでpathSuffixを使った例として。)

$ curl 'localhost:8080/nice/user/alice/greet'
hello!
$ curl 'localhost:8080/nice/user/foo/bar/baz/greet'
hello!

path のみで実装する

例のルーティングを Path を結合する~と Slash 区切りにする/を組み合わせるとpathのみを使って実現できる。

val route =
  path("nice" / "user") {
    complete("nice user!")
  } ~
    path("nice" / "user" / ("greet" | "hello")) {
      complete("hello!")
    } ~
    path("nice" / "user" / ".+".r ~ Slash.?) { name =>
      complete(s"nice name => $name")
    }

pathのみでの実装は Play Flamework の routes のようにルーティングが明示的なので人間にはわかりやすいが、コードとして重複が多くメンテナンス性がやや下がってしまうのが難点。 /nice/user/greetを明示しているので、先述のPathSuffixを使用した実装とは/nice/user/.../greetの挙動は変わっている。

$ curl 'localhost:8080/nice/user/alice/greet'
The requested resource could not be found.%

また、path("nice" / "user")のようなものであればseparateOnSlashesでも表現できる。

path(separateOnSlashes("nice/user")) {
} ~
  path(separateOnSlashes("nice/user") / ("greet" | "hello")) {
    ...
  }

折衷案

pathPrefixとpathを組み合わせた一般的な(?)実装が以下。

val route =
  pathPrefix("nice" / "user") {
    pathEnd {
      complete("nice user!")
    } ~
      path("greet" | "hello") {
        complete("hello!")
      } ~
      path(".+".r ~ Slash.?) { name =>
        complete(s"nice name => $name")
      }
  }

末尾に/がつくかどうかは~ Slash.?かpathEndOrSingleSlashのどちらでも表現できそうだが、 pathEndOrSingleSlashはその名の通りpathEndであるため、その後に Path がまだ続く場合は~ Slash.?を使う必要が生じる。

複数の PathMatcher1 を組み合わせる

IntNumberや正規表現などのPathMatcher1を複数組み合わせることが可能。

path("hi" / IntNumber / ".+".r) { (n: Int, str: String) =>
  complete(s"n: $n, str: $str")
}

PathMatcher1を 2 つ組み合わせるとDirective[Tuple2[A, B]]となってTuple2を受け取ることが出来るようになる。それぞれ型を書くと以下のようになる。(なお IntelliJ だとうまく型解決出来ないっぽくてエラーが出てしまう)

val pathMatcher: PathMatcher[Tuple2[Int, String]] = "hi" / IntNumber / ".+".r
val directive: Directive[Tuple2[Int, String]] = path(pathMatcher)

Segment

PathMatchers.Segmentは他でマッチしなかった Path を拾うためのもの、というイメージ。関連するのはSegment, Segment.repeat, Segments, Rest, RestPathあたり。

Segment
- ".+".rと同じように使える
- 型はPathMatcher1[String]
Segment.repeat
- Segmentを回数指定(min と max)で繰り返す
- 型はPathMatcher1[List[String]]
Segments
- Segment.repeatを最大 128 回繰り返す
  - min=0, max=128 なSegment.repeat
Rest
- マッチしていない Path の残りを表す
- 型はPathMatcher1[String]で、残りの Path を文字列として得られる
RestPath
- Restと同じで、型がPathmatcher1[Path]となっている
- 残りの Path に何かしら操作したい場合はこちらを使うべき

使用例としてはこんなところ

val route =
  path("foo" / Segment / "yes") { (x: String) =>
    complete(s"foo segment: $x")
  } ~
    path("bar" / Segment / RestPath) { (x: String, y: Path) =>
      complete(s"bar segment: $x, $y")
    } ~
    path("baz" / Segments) { (x: List[String]) =>
      complete(s"baz segment: $x")
    }

この route に対するリクエストとレスポンスはこうなる。

$ curl 'localhost:8080/foo/hello/yes'
foo segment: hello
$ curl 'localhost:8080/bar/a/b/c'
bar segment: a, b/c
$ curl 'localhost:8080/baz/up/down/left/right'
baz segment: List(up, down, left, right)

from: https://qiita.com/petitviolet/items/b74b89820917df7834ba