ClojureのDuctでWeb API開発してみた

Clojurianでラブライブ!ファン(海未🏹&曜⛵推し)の[lagénorhynque](https://twitter.com/lagenorhynque) (a.k.a. カマイルカ)です。

[Opt Technologies](https://www.opt.ne.jp/opttechnologies/)所属で、普段は広告運用に関わる社内向けプロダクトをPHP, TypeScript, Clojureで開発しています。

最近までに[Clojureをプロダクトに導入](http://tech-magazine.opt.ne.jp/entry/2017/09/06/074020)したり、[Haskell/Elmプロダクトの開発者を募集](https://twitter.com/OptTechnologies/status/936123304259104768)したりと、社内でもClojureやHaskellといった言語への注目度がこれまで以上に高まっています(改めて断言)。

そこで再び、今年11月から新たに始まったClojure勉強会[clj-nakano](https://clj-nakano.connpass.com/)での課題を題材に、ClojureとDuctフレームワークでWeb APIを開発してみました。

ちなみにclj-nakanoといえば、Clojure開発者Rich HickeyのClojure/conj 2017でのキーノート[Effective Programs - 10 Years of Clojure](https://youtu.be/2V1FtfBDsLU)を解説した[日本語資料](https://gitpitch.com/clj-nakano/effective-programs-ja/)も先日一部で話題になっていたようです。

# situated-program-challenge

clj-nakanoでは、Rich Hickeyのキーノートでも出てきた表現"situated program"というものについて探求するべく、[situated-program-challenge](https://github.com/clj-nakano/situated-program-challenge)という課題に取り組んでいます。

詳しくはリポジトリの[README](https://github.com/clj-nakano/situated-program-challenge/blob/master/README.md)に書かれていますが、所定のデータベースにアクセスするREST APIのサーバとクライアントを複数言語で実装し、典型的なWeb APIをいかに簡潔に実装できるか、仕様変更に対していかに柔軟に対応できるか、検証してみようというものです。

第2回clj-nakanoではClojureとScalaでの実装例が紹介されました。

- Clojure版 by @iku000888 さん: [iku000888/situated-program-challenge at clj-solution](https://github.com/iku000888/situated-program-challenge/tree/clj-solution)
- Scala版 by @shinichy さん: [shinichy/situated-program-challenge at version1](https://github.com/shinichy/situated-program-challenge/tree/version1)

また先日、私自身もHaskell版を実装してみました。

[ClojurianがHaskellでWeb API開発に入門してみた - Qiita](https://qiita.com/lagenorhynque/items/f8b14ff70a26cfd27976)

- [lagenorhynque/situated-program-challenge at hs-version1](https://github.com/lagenorhynque/situated-program-challenge/tree/hs-version1)

そこで今回は、↑の記事執筆時に間に合わなかったClojure (Duct)版の実装を簡単にご紹介します。

基本的なビジネスロジックはHaskell (Yesod)版と同様なパターンで実装しているので、両者を見比べてみると面白いかもしれません。

# Clojure版の実装

仕様version1のClojure (Duct)版実装はこちら:

[lagenorhynque/situated-program-challenge at clj-version1](https://github.com/lagenorhynque/situated-program-challenge/tree/clj-version1)

国内のClojureコミュニティでも注目度の高い(と思われる) [Duct](https://github.com/duct-framework/duct)は、アプリケーション状態管理ライブラリ[Integrant](https://github.com/weavejester/integrant)を基礎とした、データ駆動(data-driven)/データ指向(data-oriented)な設計が特徴的なWebフレームワークです。

以前から気になりつつも本格的に試したことがなかったため、今後のプロダクト利用を見据えた技術検証も兼ねて、Web API開発に使ってみることにしました。

## 1. プロジェクトの生成

[Getting Started · duct-framework/duct Wiki](https://github.com/duct-framework/duct/wiki/Getting-Started)やDuct作者のブログ記事[Building Web Services with Duct](https://www.booleanknot.com/blog/2017/05/29/building-web-services-with-duct.html)などを参考にプロジェクトを生成し、ローカル設定ファイルをセットアップする。

今回はWeb API向けの構成で、ルーティングにAtaraxy、DBとしてPostgreSQLを利用する想定なので、

```sh
$ lein new duct rest-server +api +ataraxy +postgres
$ cd rest-server
$ lein duct setup
```

## 2. DB接続設定 & システムの起動

[docker-compose.yml](https://github.com/lagenorhynque/situated-program-challenge/blob/hs-version1/docker-compose.yml)で利用するPostgreSQLのデータベース接続情報が与えられているので、Ductの設定ファイルに反映する。

今回はproduction環境設定(`resources/rest_server/config.edn`)で直接 `database-url` を指定し、development環境設定(`dev/resources/dev.edn`)からはDB接続設定を削除することにした(ちなみに、環境変数 `DATABASE_URL` で外から与えることもできる)。

- [rest-server/resources/rest_server/config.edn](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/resources/rest_server/config.edn)

```clojure
{:duct.profile/base
 {:duct.core/project-ns  rest-server}

 :duct.profile/dev   #duct/include "dev"
 :duct.profile/local #duct/include "local"
 :duct.profile/prod  {}

 :duct.module/logging {}
 :duct.module.web/api {}
 :duct.module/sql
 {:database-url "jdbc:postgresql://localhost:5432/meetup?user=meetup&password=password123"}}
```

- [rest-server/dev/resources/dev.edn](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/dev/resources/dev.edn)

```clojure
{}
```

REPLからシステム(開発環境)を起動するには、

```clojure
$ lein repl
Warning: implicit middleware found: lein-duct.plugin/middleware
Please declare all middleware in :middleware as implicit loading is deprecated.
nREPL server started on port 64722 on host 127.0.0.1 - nrepl://127.0.0.1:64722
REPL-y 0.4.3, nREPL 0.5.3
Clojure 1.10.0
Java HotSpot(TM) 64-Bit Server VM 11+28
    Docs: (doc function-name-here)
          (find-doc "part-of-name-here")
  Source: (source function-name-here)
 Javadoc: (javadoc java-object-or-class-here)
    Exit: Control+D or (exit) or (quit)
 Results: Stored in vars *1, *2, *3, an exception in *e

user=> (dev)  ; 開発環境をロード
:loaded
dev=> (go)  ; システムを起動
:duct.server.http.jetty/starting-server {:port 3000}
:initiated
dev=> (reset)  ; システムをリフレッシュ(ソースコードの変更を反映)
:reloading (rest-server.util rest-server.boundary.db.core rest-server.boundary.db.group rest-server.boundary.db.member rest-server.boundary.db.venue rest-server.handler.member rest-server.boundary.db.meetup rest-server.handler.venue rest-server.handler.meetup rest-server.handler.group rest-server.main dev user)
:resumed
dev=>
```

コマンドラインからシステムを起動するには、

```sh
$ lein run
```

jarをビルドしてシステムを起動するには、

```sh
$ lein uberjar
$ java -jar target/rest-server-0.1.0-SNAPSHOT-standalone.jar
```

## 3. ルーティングの定義

ルーティングライブラリとして、Ductのモジュールとしても利用可能になっている[Ataraxy](https://github.com/weavejester/ataraxy)を利用する。

AtaraxyではClojureのデータとしてルーティングの定義を表現し、リクエストデータ(Clojureのマップ)に対して必要に応じて分配束縛や型変換を行うことができる。

ただのデータなのでDuctでは設定ファイルに書くようになっている。

- [rest-server/resources/rest_server/config.edn](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/resources/rest_server/config.edn)

```clojure
{:duct.profile/base
 {:duct.core/project-ns  rest-server

  :rest-server.handler.meetup/list {:db #ig/ref :duct.database/sql}
  :rest-server.handler.meetup/create {:db #ig/ref :duct.database/sql}
  :rest-server.handler.meetup/fetch {:db #ig/ref :duct.database/sql}
  :rest-server.handler.meetup/join {:db #ig/ref :duct.database/sql}
  :rest-server.handler.member/list {:db #ig/ref :duct.database/sql}
  :rest-server.handler.member/create {:db #ig/ref :duct.database/sql}
  :rest-server.handler.member/fetch {:db #ig/ref :duct.database/sql}
  :rest-server.handler.venue/list {:db #ig/ref :duct.database/sql}
  :rest-server.handler.venue/create {:db #ig/ref :duct.database/sql}
  :rest-server.handler.group/list {:db #ig/ref :duct.database/sql}
  :rest-server.handler.group/create {:db #ig/ref :duct.database/sql}
  :rest-server.handler.group/join {:db #ig/ref :duct.database/sql}}

 :duct.profile/dev #duct/include "dev"
 :duct.profile/local #duct/include "local"
 :duct.profile/prod {}

 :duct.module/logging {}
 :duct.module.web/api {}
 :duct.module/sql
 {:database-url "jdbc:postgresql://localhost:5432/meetup?user=meetup&password=password123"}

 :duct.module/ataraxy
 {"/members"
  {:get [:member/list]
   [:post {member :body-params}] [:member/create member]
   ["/" member-id]
   {:get [:member/fetch ^int member-id]
    "/meetups"
    {["/" meetup-id]
     {:post [:meetup/join ^int member-id ^int meetup-id]}}
    "/groups"
    {["/" group-id]
     {[:post {group-member :body-params}] [:group/join ^int member-id ^int group-id group-member]}}}}
  "/groups"
  {:get [:group/list]
   [:post {group :body-params}] [:group/create group]
   ["/" group-id]
   {"/meetups"
    {:get [:meetup/list ^int group-id]
     [:post {meetup :body-params}] [:meetup/create ^int group-id meetup]
     ["/" meetup-id]
     {:get [:meetup/fetch ^int group-id ^int meetup-id]}}
    "/venues"
    {:get [:venue/list ^int group-id]
     [:post {venue :body-params}] [:venue/create ^int group-id venue]}}}}}
```

例えば、 `/members/{member-id}/meetups/{meetup-id}` への `POST` は、キー `:duct.module/ataraxy` に対するルーティング定義マップの

`"/members"` -> `["/" member-id]` -> `"/meetups"` -> `["/" meetup-id]` -> `:post`

というパスで表現し、その値 `[:meetup/join ^int member-id ^int meetup-id]` でハンドラー関数のコンポーネントに対応付けている。

対応するハンドラー関数のコンポーネントはルーティング定義マップの下にある

```clojure
 :rest-server.handler.meetup/join {:db #ig/ref :duct.database/sql}
```

で定義している(これに紐付く関数はDBアクセスを行うため、Integrantで `:duct.database/sql` に依存させている)。

## 4. ハンドラーの実装1

ルーティングを定義したら、対応するハンドラー関数を定義する。

Ductではアプリケーション状態管理ライブラリとして[Integrant](https://github.com/weavejester/integrant)を利用しているため、ここでは↑で設定したハンドラー関数のコンポーネントの初期化処理をClojureのマルチメソッドによって実装する。

まずは仮実装として、個々のコンポーネントのキーに対するマルチメソッド `integrant.core/init-key` でルーティング定義に対応する引数を受け取り、常にHTTPレスポンスOK (ステータスコード200)を返す関数として実装してみる。

- [rest-server/src/rest_server/handler/member.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/handler/member.clj)

```clojure
(ns rest-server.handler.member
  (:require [ataraxy.response :as response]
            [integrant.core :as ig]))

(defmethod ig/init-key ::list [_ {:keys [db]}]
  (fn [_] [::response/ok]))

(defmethod ig/init-key ::create [_ {:keys [db]}]
  (fn [{[_ member] :ataraxy/result}]
    [::response/ok]))

(defmethod ig/init-key ::fetch [_ {:keys [db]}]
  (fn [{[_ member-id] :ataraxy/result}]
    [::response/ok]))
```

他の名前空間に設定したハンドラー関数のコンポーネントも同様に実装する。

- [rest-server/src/rest_server/handler/meetup.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/handler/meetup.clj)
- [rest-server/src/rest_server/handler/group.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/handler/group.clj)
- [rest-server/src/rest_server/handler/venue.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/handler/venue.clj)

これでルーティング定義とハンドラー関数が正しく紐付き、REPLで `(reset)` するとコンパイルが通ってRESTサーバが動作するようになる。

## 5. DBアクセス層の実装

DBのデータを参照/更新するためにDBアクセス層を実装する。

ここでは[clojure.java.jdbc](https://github.com/clojure/java.jdbc)に[Honey SQL](https://github.com/jkk/honeysql)を適宜組み合わせて利用する。

複数レコードのSELECT、1レコードのSELECT、1レコードのINSERT、複数レコードのINSERTというよくあるパターンをユーティリティとしてまとめてみた。

また、DBのテーブルでは識別子がsnake_caseだが、Clojureのマップでは通常kebab-caseのキーワードを利用するので、DBアクセスの前後に適宜変換するようにしている。

- [rest-server/src/rest_server/boundary/db/core.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/boundary/db/core.clj)

```clojure
(ns rest-server.boundary.db.core
  (:require [clojure.java.jdbc :as jdbc]
            [honeysql.core :as sql]
            [rest-server.util :as util]))

(defn select [{db :spec} sql-map]
  (->> sql-map
       sql/format
       (jdbc/query db)
       util/transform-keys-to-kebab))

(defn select-one [{db :spec} sql-map]
  (->> sql-map
       sql/format
       (jdbc/query db)
       util/transform-keys-to-kebab
       first))

(defn insert! [{db :spec} table row-map & {:keys [id-col]
                                           :or {id-col :id}}]
  (->> row-map
       util/transform-keys-to-snake
       (jdbc/insert! db table)
       first
       id-col))

(defn insert-multi! [{db :spec} table row-maps]
  (->> row-maps
       util/transform-keys-to-snake
       (jdbc/insert-multi! db table)))
```

Ductでは、DBなど外部リソース/サービスとのやり取りをビジネスロジックと疎結合にするため、Clojureのプロトコルで外部リソース/サービスに対するインターフェースとして「境界」(boundary)を定義し、それに対して実装する仕組みが提供されている。

ここでは、DBのエンティティへの各種参照/更新アクセスをメソッドとしたプロトコルを定義し、↑で用意したユーティリティやHoney SQLを利用してDBアクセス操作を実装している。

- [rest-server/src/rest_server/boundary/db/member.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/boundary/db/member.clj)

```clojure
(ns rest-server.boundary.db.member
  (:require [duct.database.sql]
            [honeysql.core :as sql]
            [rest-server.boundary.db.core :as db]))

(defprotocol Members
  (list-members [db])
  (create-member [db member])
  (fetch-member [db member-id])
  (fetch-members [db member-ids]))

(extend-protocol Members
  duct.database.sql.Boundary
  (list-members [db]
    (db/select db (sql/build :select :*
                             :from :members)))
  (create-member [db member]
    (db/insert! db :members member))
  (fetch-member [db member-id]
    (db/select-one db (sql/build :select :*
                                 :from :members
                                 :where [:= :id member-id])))
  (fetch-members [db member-ids]
    (db/select db (sql/build :select :*
                             :from :members
                             :where [:in :id member-ids]))))
```

SQLを書くのに利用しているHoney SQLはClojureのデータでSQLを表現するDSLで、(ここでは簡潔さのために `honeysql.core/build` 関数を利用するだけにとどまっているが)ただのデータなので非常に柔軟にクエリを組み立てることができる。

- [rest-server/src/rest_server/boundary/db/meetup.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/boundary/db/meetup.clj)

```clojure
(ns rest-server.boundary.db.meetup
  (:require [duct.database.sql]
            [honeysql.core :as sql]
            [rest-server.boundary.db.core :as db]))

(defprotocol Meetups
  (list-meetups [db group-id])
  (create-meetup [db meetup])
  (fetch-meetup [db meetup-id])
  (fetch-meetup-members [db meetup-id])
  (create-meetup-member [db meetup-member]))

(extend-protocol Meetups
  duct.database.sql.Boundary
  (list-meetups [db group-id]
    (db/select db (sql/build :select :*
                             :from :meetups
                             :where [:= :group_id group-id])))
  (create-meetup [db meetup]
    (db/insert! db :meetups meetup))
  (fetch-meetup [db meetup-id]
    (db/select-one db (sql/build :select :*
                                 :from :meetups
                                 :where [:= :id meetup-id])))
  (fetch-meetup-members [db meetup-id]
    (db/select db (sql/build :select :members.*
                             :from :members
                             :join [:meetups_members [:= :members.id :meetups_members.member_id]]
                             :where [:= :meetups_members.meetup_id meetup-id])))
  (create-meetup-member [db meetup-member]
    (db/insert! db :meetups_members meetup-member)))
```

`JOIN` や `WHERE` などもClojureのデータの組み合わせで簡潔に表現できる。

e.g.

```clojure
(sql/build :select :members.*
           :from :members
           :join [:meetups_members [:= :members.id :meetups_members.member_id]]
           :where [:= :meetups_members.meetup_id meetup-id])
```

その他のDBとのboundaryも同様に実装する。

- [rest-server/src/rest_server/boundary/db/group.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/boundary/db/group.clj)
- [rest-server/src/rest_server/boundary/db/venue.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/boundary/db/venue.clj)

## 6. ハンドラーの実装2

ここまでのボトムアップな下ごしらえで必要な材料はすべてそろったので、最後にハンドラー関数のビジネスロジックを実装する。

HTTPのリクエストもレスポンスもDBとの入出力データも、一貫してClojureの最も基本的な抽象たるマップ(associativeなもの)とシーケンス(sequentialなもの)の組み合わせにすぎないので、マップやシーケンスに対する豊富な関数や言語機能をフル活用して非常に簡潔に実装することができた。

- [rest-server/src/rest_server/handler/member.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/handler/member.clj)

```clojure
(ns rest-server.handler.member
  (:require [ataraxy.response :as response]
            [clojure.set :as set]
            [integrant.core :as ig]
            [rest-server.boundary.db.member :as db.member]))

(defn member-with-id [member]
  (set/rename-keys member {:id :member-id}))

(defmethod ig/init-key ::list [_ {:keys [db]}]
  (fn [_] [::response/ok (map member-with-id
                              (db.member/list-members db))]))

(defmethod ig/init-key ::create [_ {:keys [db]}]
  (fn [{[_ member] :ataraxy/result}]
    (let [id (db.member/create-member db member)]
      [::response/ok (-> member
                         (assoc :id id)
                         member-with-id)])))

(defmethod ig/init-key ::fetch [_ {:keys [db]}]
  (fn [{[_ member-id] :ataraxy/result}]
    (when-let [member (db.member/fetch-member db member-id)]
      [::response/ok (member-with-id member)])))
```

- [rest-server/src/rest_server/handler/meetup.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/handler/meetup.clj)

```clojure
(ns rest-server.handler.meetup
  (:require [ataraxy.response :as response]
            [integrant.core :as ig]
            [rest-server.boundary.db.meetup :as db.meetup]
            [rest-server.boundary.db.venue :as db.venue]
            [rest-server.handler.member :as member]
            [rest-server.handler.venue :as venue]
            [rest-server.util :as util]))

(defn meetup-with-venue-and-members [{:keys [id title start-at end-at]} venue members]
  {:event-id id
   :title title
   :start-at start-at
   :end-at end-at
   :venue (venue/venue-with-address venue)
   :members (map member/member-with-id members)})

(defn fetch-meetup-detail [db {:keys [id venue-id] :as meetup}]
  (let [venue (db.venue/fetch-venue db venue-id)
        members (db.meetup/fetch-meetup-members db id)]
    (meetup-with-venue-and-members meetup venue members)))

(defn get-meetup [db meetup-id]
  (when-let [meetup (db.meetup/fetch-meetup db meetup-id)]
    (fetch-meetup-detail db meetup)))

(defmethod ig/init-key ::list [_ {:keys [db]}]
  (fn [{[_ group-id] :ataraxy/result}]
    [::response/ok (map (partial fetch-meetup-detail db)
                        (db.meetup/list-meetups db group-id))]))

(defmethod ig/init-key ::create [_ {:keys [db]}]
  (fn [{[_ group-id {:keys [start-at end-at] :as meetup}] :ataraxy/result}]
    (let [meetup' (assoc meetup
                         :start-at (util/string->timestamp start-at)
                         :end-at (util/string->timestamp end-at)
                         :group-id group-id)
          id (db.meetup/create-meetup db meetup')]
      [::response/ok (-> meetup'
                         (assoc :id id)
                         ((partial fetch-meetup-detail db)))])))

(defmethod ig/init-key ::fetch [_ {:keys [db]}]
  (fn [{[_ _ meetup-id] :ataraxy/result}]
    (when-let [meetup (get-meetup db meetup-id)]
      [::response/ok meetup])))

(defmethod ig/init-key ::join [_ {:keys [db]}]
  (fn [{[_ member-id meetup-id] :ataraxy/result}]
    (db.meetup/create-meetup-member db {:meetup-id meetup-id
                                        :member-id member-id})
    [::response/ok (get-meetup db meetup-id)]))
```

その他のハンドラーも同様に実装してRESTサーバは完成!

- [rest-server/src/rest_server/handler/group.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/handler/group.clj)
- [rest-server/src/rest_server/handler/venue.clj](https://github.com/lagenorhynque/situated-program-challenge/blob/clj-version1/rest-server/src/rest_server/handler/venue.clj)

# まとめ

- ClojureのフレームワークDuctでデータによる宣言的な記述を主体としてシンプルにWeb APIを実装できた
- Duct, Integrant, Ataraxyのデータ駆動/データ指向な設計には可能性を感じる
- [Luminus](http://www.luminusweb.net/)は十分実用的だし[Arachne](http://arachne-framework.org/)にも期待しているけど、現状Ductが個人的にもかなり良い選択肢かも
- やはりClojureは超楽しい＞ω＜/

# Further Reading

- [ClojureのDuctとClojureScriptのre-frameによるREST API + SPA開発入門](https://qiita.com/lagenorhynque/items/38537fa91300e0ac0070)

- [Clojure/ClojureScript関連リンク集 > Webサーバサイド (Clojure)](https://qiita.com/lagenorhynque/items/68c314c288b75a9492ba#web%E3%82%B5%E3%83%BC%E3%83%90%E3%82%B5%E3%82%A4%E3%83%89-clojure)