Biff.graph: Clojureコードベースをクエリ可能なグラフとして構造化する
Biff.graph: structure your Clojure codebase as a queryable graph (github.com)
要約
Biff.graphは、Clojureコードベースのデータモデルをクエリ可能なグラフとして構造化するためのライブラリです。データベースとビジネスロジック/派生データを統合されたグラフとして照会でき、コードの理解とテストを容易にします。これはPathomの軽量版として位置づけられ、よりシンプルなアプローチでグラフデータモデリングパターンを提供します。
全文翻訳
biff.graph
データモデルをクエリ可能なグラフとして構造化します。
biff.graphを使用すると、データベースとビジネスロジック/派生データの両方を、統一された拡張可能なグラフとしてクエリできます。データモデルコードは、小さく独立したチャンク(「リゾルバ」)に分割でき、アプリケーションコードは、そのデータをどのように取得するかを知る必要なしに、必要なデータの形状を宣言できます。これにより、コードベースは、特に大きくなるにつれて、理解しやすくテストしやすくなります。
biff.graphは基本的にPathomの軽量版です。Pathomの機能の一部のみを実装しており、理解しやすくすることを意図しています。最大の Сdifference は、biff.graphにはクエリ計画ステップがないため、Pathomほど効率的に一部のクエリを実行できない可能性があることです。(ただし、バッチリゾルバとキャッシュはサポートしています。)一方で、biff.graphのコードベースは約600行で、クエリ実行コードは約200行です。
私がbiff.graphを作成したのは、仕事でもサイドプロジェクトでもPathomを使うのが好きでしたが、Biffにデフォルトで含めることについて懸念があったからです。Pathomについてまだ聞いたことがない小規模プロジェクトに取り組んでいる人々にとって、コード構造のメリットが、必要な追加学習コストを上回るとは確信が持てません。そのため、biff.graphはこのグラフデータモデリングパターンのアプローチしやすさをどこまで高められるかを見る試みです。biff.graphを使い続けるBiffユーザーは、コードの構造化方法に関してPathomと同じ概念的なアイデアを学ぶ必要がありますが、次のステップである、コードが実際に何をしているのかを理解して問題が発生したときにデバッグできるようにすることは、より簡単になるはずです。
依存関係
com.biffweb/graph {:mvn/version "2.0.0-rc26"}
ステータス
このライブラリは、他のすべてのBiff 2ライブラリがリリースされるまでリリース候補版となります。それまでは破壊的な変更が発生する可能性がありますが、予期していません。
参考資料
コンセプト
-
biff.graphは、EQL / Datomic pullパターンをわずかに変更したサブセットを使用して、データの形状を記述します。
-
「リゾルバ」は、関連付けられた入力と出力クエリを持つ関数です。関数は、入力クエリの形状のデータを受け取り、出力クエリの形状のデータを返します。
-
いくつかのリゾルバを定義した後、biff.graphのクエリエンジンはそれらを使用して、クエリする形状のデータを返します。
例
このスニペットでは:
-
シミュレートされたデータベースアクセスリゾルバ(
rss-feedとpost)をいくつか定義し、指定された主キーのエンティティを返します。 -
派生データリゾルバ(
clean-post-title)を定義し、:post/title属性を受け取り、絵文字がフィルタリングされたバージョンを返します。 -
データベースから取得される属性と派生される属性のどちらを知る必要もなく、
com.biffweb.graph/queryを介してデータモデルグラフをクエリします。
(require '[com.biffweb.graph :as biff.graph :refer [defresolver]])
(require '[clojure.string :as str])
(defresolver rss-feed
{:input [:rss-feed/id]
:output [:rss-feed/title]}
[_ctx {:rss-feed/keys [id]}]
(get {1 {:rss-feed/title "My Blog"}}
id))
(defresolver post
{:input [:post/id]
:output [:post/title
:post/url
{:post/rss-feed [:rss-feed/id]}]}
[_ctx {:post/keys [id]}]
(get {2 {:post/url "https://example.com/my-post"
:post/title "My Post 🎅"
:post/rss-feed {:rss-feed/id 1}}
3 {:post/title "My Other Post 🎅"
:post/rss-feed {:rss-feed/id 1}}}
id))
(defn remove-emojis [s]
(str/replace s #"🎅" ""))
(defresolver clean-post-title
{:input [:post/title]
:output [:post/clean-title]}
[_ctx {:post/keys [title]}]
{:post/clean-title (-> title
remove-emojis
str/trim)})
(def resolvers [rss-feed
post
clean-post-title])
(def ctx (biff.graph/new-ctx resolvers))
(biff.graph/query ctx
[{:post/id 2}
{:post/id 3}]
[:post/id
:post/clean-title
;; Optional attributes are denoted with [:? ...]
[:? :post/url]
;; Join attributes are denoted with nested maps
{:post/rss-feed [:rss-feed/title]}
;; An optional join attribute looks like this:
;; {[:? :post/rss-feed] [:rss-feed/title]}
])
;; =>
[{:post/id 2,
:post/clean-title "My Post",
:post/url "https://example.com/my-post",
:post/rss-feed {:rss-feed/title "My Blog"}}
{:post/id 3,
:post/clean-title "My Other Post",
:post/rss-feed {:rss-feed/title "My Blog"}}]
使用方法
リゾルバの定義
まず、データベーススキーマ(例ではpostとrss-feedが自動生成される)に基づいてリゾルバを自動生成できるような関数を用意するのが一般的です(defresolverではなくcom.biffweb.graph/resolverを使用)。ガイドラインは以下の通りです。
- テーブル/エンティティタイプごとに1つのリゾルバが必要です。
- 入力クエリは主キーのみであるべきです(例:
[:person/id])。 - 出力クエリには、他のすべての列/属性を含めるべきです(例:
[:person/age, :person/favorite-color, ...])。 - 出力クエリには、各外部キー/参照属性の結合キーも含めるべきで、結合サブクエリはそのエンティティの主キーであるべきです(例:
[{:person/pet [:pet/id]}, ...])。 - リゾルバオプションには、データベースクエリが一度に複数のエンティティを取得できるように、
:batch trueを含めるべきです。この設定を持つリゾルバは、入力マップのベクトルを受け取り、同じ順序で出力マップのベクトルを返す必要があります。 - リゾルバ関数は、各入力主キーに対して基本的に
SELECT *を実行し、結合キーが存在し、ネストされたマップとしてフォーマットされていることを確認する必要があります。
まだリリースされていないbiff.sqliteライブラリには、sqlite用のそのような関数が含まれています(コンテンツ警告: 未編集のAIコード)。
次に、必要に応じて役立つ追加のリゾルバをcom.biffweb.graph/defresolverで定義できます。ヘルパー関数からリゾルバへロジックを必要に応じて徐々に移動できます。リゾルバの記述に関する詳細については、参考ドキュメントを参照してください。
最後に、リゾルバをcom.biffweb.graph/new-ctxに渡します。これは、クエリエンジンが必要とする簡単なインデックス作成を行います。new-ctxは、キャッシュや検証などを処理するミドルウェアでリゾルバをラップします。
クエリの実行
リゾルバを定義した後、Ringリクエストハンドラの開始時など、必要な場所からクエリを実行できます。
(defn settings-page [{:keys [session] :as ctx}]
(let [user (biff.graph/query ctx
{:user/id (:uid session)}
[:user/email
:user/display-name
:user/subscribed])]
...
))
上記の例は、com.biffweb.graph/new-ctxの出力を受信Ringリクエストにマージするミドルウェアがあることを前提としています。
デバッグ
com.biffweb.graph/query内で発生した例外には、例外データ内に:biff.graph/traceキーが含まれています。これは、例外が発生したときにグラフトラバーサルのどこにいたか(例外がどのクエリ部分から発生したか、入力の解決を試みていたリゾルバは何かなど)を示します。この情報を使用して、失敗したパスにクエリを集中させることで、必要に応じて最小限の再現手順を作成できます。
テスト
リゾルバ関数は:biff.graph/resolve-fnキーの下に格納されます。これらは単一の引数(ctxマップ)を受け取り、リゾルバ入力が:biff.graph/inputの下に格納されていることを期待します。
(defresolver my-resolver
{:input [:user/id]
:output [...]}
[ctx input]
...)
(deftest test-my-resolver
(is (= ((:biff.graph/resolve-fn my-resolver)
{:biff.graph/input {:user/id 1}})
...)))
biff.fxとの統合
biff.fxを使用する場合、com.biffweb.graph/fx-handlersをハンドラマップにマージできます。これは:biff.graph.fx/queryキーの下でcom.biffweb.graph/queryを公開します。
(require '[com.biffweb.fx :refer [defmachine]])
(defmachine do-something
:start
(fn [{:keys [session]}]
{:user [:biff.graph.fx/query
{:user/id (:uid session)}
[:user/email
...]]
:biff.fx/next :next})
...)
リゾルバ内でエフェクト(データベースクエリや外部サービス呼び出しなど)を処理するためにbiff.fxを使用したい場合、defresolverはリゾルバ本体をbiff.fxマシンとして定義する形式もサポートしています。
(defresolver my-resolver
{:input [...]
:output [...]}
:start
(fn [ctx input]
...)
:next
(fn [ctx output-from-start]
...))
:start関数は、ctxの後にリゾルバ入力を受け取ります。後続の状態関数は、前の状態の出力マップを受け取ります。
biff.coreとの統合
(com.biffweb.graph/module)をモジュールに含めると、他のモジュール上の:biff.graph/resolversベクトルにリゾルバを配置できます。
アプリケーションのスキーマをcom.biffweb.core/registerで登録すると、biff.graphはリゾルバの出力がそのスキーマに準拠することを保証します。
ヒント
-
私はリゾルバを
model/ディレクトリの下に配置し、そこにある各名前空間が:biff.graph/resolversを設定したbiff.coreモジュールを公開するようにしています。 -
ヒックプ(またはヒックプを返す関数のいずれか)を返すリゾルバを作成することさえできます(例:
(defresolver ... {:com.example/my-component (fn [{:keys [href]}] [:div ...])}))。これは、データモデルに固有の再利用可能なUIコンポーネント(「ボタン」や「モーダル」などのより汎用的なコンポーネントとは対照的に)を作成するのに役立ちます。私はこれらをui_components/の下に配置しています。 -
入力クエリを持たない「グローバル」リゾルバを作成することが、時には理にかなっています。たとえば、バックグラウンドジョブは、特定の基準を満たすデータベース内のすべてのユーザーをクエリしたい場合があります。また、
ctxからデータを返すリゾルバ(例::output [{:session/user [:user/id]}])を作成すると、セッションからユーザーIDを明示的に取得する必要がなくなります。 -
その観点から、認証については、パス/クエリパラメータからエンティティIDを取得し、現在のユーザーがそのエンティティを読み取る権限があることを確認してから、結合として返す「パラメータ」リゾルバを使用しています(例:
:output [{:params/widget [:widget/id]}])。ユーザーに権限がない場合、例外をスローするか、単にリゾルバ出力からエンティティを省略できます。どちらのアプローチも4XX HTTPレスポンスに変換する方法はいくつかあります。私はまだ自分で実験中です。