Rindrics Mumbles

第 1 章: ドメイン駆動設計入門

Wed, 13 Nov 2024 00:00:00 +0900

“1. Introducing Domain-Driven Design” from “Domain Modeling Made Functional: Tackle Software Complexity with Domain-Driven Design and F#” 📚

ソフトウェア開発者の仕事とは:

not only コードを書くこと
but also ソフトウェアを通して問題を解決すること

要件が不明瞭だったり、設計が悪ければコーディングをどれだけ頑張ろうとよい価値は得られない

つまり garbage in, garbage out
- 📝 この表現はソフトウェア自体への入力と出力に対して使われることが多いが、ここでは input が「要件」、output を「得られる価値」というかなり高レイヤな意味で使われている

“garbage in” を減らすのに必要なもの:

明解なコミュニケーション
共有ドメイン知識に基づく設計アプローチ

ドメイン駆動設計（DDD）をによってこれらを実現できる。

共有モデルの重要性

まず開発者が問題を正しく理解することが重要

とりうるアプローチを 3 つ紹介:

仕様書・要件定義書を整備する 💣
ドメインエキスパートを開発プロセスに入れる ⚠️
ドメイン駆動設計 ✅

1. 仕様書・要件定義書を整備する 💣

これはだめなやり方。

理由:

ドメインエキスパートと開発チームの距離が遠くなってしまう ❌
“伝言ゲーム” のようなことが実際に起こり、これはプロジェクトにおいては致命的 ❌

2. ドメインエキスパートを開発プロセスに組み込む ⚠️

いわゆるアジャイルなやり方。一見良さそうに思えるがベストではない。

誤りをすぐに修正できるようにするために、ドメインエキスパートを開発プロセスのフィードバックループに組み入れる。

デメリット:

開発者の働きがドメインエキスパートのメンタルモデルの単なる翻訳者でしかなくなってしまう ❌
必ず抜け落ちてしまう情報がある ❌
将来、ドメインエキスパートからの入力なしにコードをメンテする開発者は容易に方針を誤ってしまう ❌

3. ドメイン駆動設計 ✅

プロジェクトに関わる人々（下記）が共通のメンタルモデルを共有した状態で開発を進める:

ドメインエキスパート
開発者
ステークホルダー

ソフトウェアのコードはメンタルモデルを直接反映したものになるので、DDD では “翻訳” という作業は存在し得ない。

メリット:

市場投入スピード ✅
得られるビジネス価値の大きさ ✅
無駄の排除 ✅
スムーズなメンテナンス ✅

（コラムでは、開発者自身がドメインエキスパートになる重要性が示されている）

共有メンタルモデルを作るためのガイドライン:

データ構造ではなく、ビジネスイベントとワークフローに着目せよ
ドメインを小さいサブドメインに分割せよ
それぞれのサブドメインについてモデルを作れ
会話やコードで使われる共通言語を作れ

ビジネスイベントからドメインを理解する

共有メンタルモデルの構築はどこから始めたらいい？ → イベントから始めよ ✅データ構造から始めるな ❌

理由:

ビジネスがデータをただ持っているだけで終わることは有り得ないため
ビジネスは何らかの方法でデータを変換するため

ビジネスプロセスとは、データやドキュメントの変換処理の集まり → これらの変換がどう行われ、どう関連しているかを理解することが重要

使われずにただ置かれているだけのデータは何の価値も生まない。これらのデータから価値を引き出すためのプロセスはどうやって始まるか？ → ドメインイベントによって始まる

ドメインイベントの例:

外部トリガー
スケジュールに基づいたトリガー
観測に基づくトリガー

ドメインイベントは事実である変化しないため必ず過去形で表現される。

（中略）

下記の 2 節で、イベントストーミングの説明と実例が書いてある:

Using Event Storming to Discover the Domain
Discovering the Domain: An Order-Taking System

イベントストーミング自体を理解するには提唱者の解説を読むほうがいい。

イベントストーミングで重要な点:

「“我々” vs “彼ら” 思考」から脱却できること
意見が合わなかったら、それは問題ではなくチャンス

イベントを境界にまで拡張する

要件の取りこぼしを防ぐために下記に注意を払う:

最初のイベントと思っていたイベントをトリガーする他のイベントがないか
最後のイベントと思っていたイベントにトリガーされる後続のイベントはないか

全てを一気に変える必要はない。最も価値を生む一部分から取りかかれ。

コマンドを記述する

イベントストーミングによってイベントが見えるようになった。それらのイベントはどのように発生するのか？ → そのイベントが起こることを誰かが要求したから

全てのイベントがコマンドに紐付いている必要はない。スケジュールによるトリガーや監視に基づくトリガーなどがあるため。

DDD ではこれらの要求を「コマンド」という。コマンドは常に命令形で表現される。紛らわしいが、OO のコマンドパターンとは違う。

コマンドが成功するとワークフローがトリガーされ、ドメインイベントが作られる。

例:

「X を起こせ」というコマンドによってワークフローが X を起こし、「X が起こった」というドメインイベントが発行される
「注文書を会社 A に送れ」というコマンドによってワークフローが注文書を送ると、「注文書が送信された」というドメインインベントが発行される
コマンド「注文を確定せよ」 → ドメインイベント「注文が確定された」
コマンド「配送を顧客 B に送れ」 → 「配送が送られた」

📝 「配送が送られた」は日本語としておかしいが、DDD ではモデルを記述する用語（ユビキタス言語）が重要なのでこのままにしておく。原著が英語なので限界がある。自然な日本語にしようとして「配送」の代わりに「商品」とするのは絶対に NG。いずれにせよ、ドメインエキスパートが使う言葉に合わせることが重要。

これから、コマンド、ワークフロー、イベントの組み合わせでビジネスプロセスを記述していく。これはまさに関数プログラミングの動きと同じ。

ドメインをサブドメインに分ける

イベントストーミングによってイベントとコマンドを洗い出したことで、多数のビジネスプロセスの中身を理解できた状態になった。しかし全体像がまだ整理されていない。コードを書き始める前に整理する必要がある。

本文中では、受注プロセスを例として分割の様子が示されている。

受注プロセスとは:

受注
配送
請求
その他

部署が既に分かれていれば、サブドメイン分割の強力な手がかりとなる。

ドメインとは？ → DDD において、一貫した知識領域のこと。 …わかりにくい。言い換えると、ドメインエキスパートが専門性を持っている領域。この理解はかなり実用的。なぜなら辞書で「請求」を調べて頭を悩ませるのではなく、シンプルに「請求部門のドメインエキスパートがやっていること」と表現できるようになるため。

ドメインは重複しうるため、分割する際には注意が必要。はっきり分けたくなるが、現実世界はそれほど単純ではない。

ドメインは少し重複しているので、例えば受注部門の担当者は請求部門や配送部門の業務を少しだけ知っている必要がある。

境界づけられたコンテキストを使って解決策を作る

ドメインの情報全てを反映する必要はない。得られた情報の中から、解こうとしている問題に関するもののみを抽出する。ほとんどは無関係なはず

なので「問題領域」と「解決領域」を分け、両者を別物として扱う必要がある:

問題領域は現実世界
解決領域はドメインモデル

問題領域は設計プロセスを経て解決領域になる

なぜ「サブシステム」でなく「境界づけられたコンテキスト」という表現なのか？

理由: 解決策を考える際に、本当に重要なものに集中できるようになるため

コンテキストと境界を常に意識せよ。

コンテキストが重要な理由: それぞれのコンテキストは解決策に独自の知識を反映するからコンテキスト内では言語は共通し、デザインも一貫しているが、これらはコンテキストの外では使えなくなる
境界が重要な理由: 現実世界では境界はぼやけているが、ソフトウェアの場合にはそれぞれを独立して開発できるようにするために分割したい。ソフトウェアでは API を使うなどして達成できるが、裏を返せばそのように作ったドメインモデルは現実世界に比べて情報量が減るということ。しかしこれは複雑さを減らし、メンテナンス性を手に入れるためのトレードオフ

問題領域のドメインは必ずしも解決領域のコンテキストと一対一対応しない:

あるドメインが複数の境界づけられたコンテキストに分割されることもある
複数のドメインが一つの境界づけられたコンテキストになるケースもある（レガシーソフトウェア）
- 例: ある企業が「受注」と「請求」をひとまとめに扱うシステムを既にインストールしていた場合、このレガシーシステムと連携するにはそれを一つの境界づけられたコンテキストとして扱う必要がある

ドメインを分けるなら、それぞれの境界づけられたコンテキストが明確な責務を持つ必要がある

理由: モデルを実装するとき、境界づけられたコンテキストはそのままソフトウェアコンポーネント（DLL、サービス、名前空間など）になるため

コンテキストを正しくする

聞くは易し、実行するは難し。というか DDD で1番難しいのがこの境界を正しく定めることで、これは科学ではなく一種の芸術といえる。

ガイドライン:

【ドメインエキスパートの声を聞け】彼らが共通言語を話し、同じ問題に注目しているならばおそらく同じサブドメインにいる。それが境界づけられたコンテキストになる
【既存チームや部署の境界に着目せよ】ビジネスが何をドメイン・サブドメインと認識しているかの強力な手がかり。必ずしも一致はしない（部署内で違うことしてたり、他部署とコラボしたり）
【境界づけられたコンテキストの「境界」に着目せよ】スコープクリープに気をつけろ。要求が変化する複雑なプロジェクトでは、無慈悲なまでに境界を守る必要がある。大きすぎる境界は何もないのと同じ。よいフェンスはよい隣人を作る
【自律可能性が生まれるように設計せよ】足を結ばれた 2 人のランナーは独立した 2 人のランナーよりも速くなることはない。それぞれの境界づけられたコンテキストを独立して開発できるようにしろ
【ビジネスフローの摩擦の摩擦を最小化するように設計せよ】複数の境界づけられたコンテキストと関わるビジネスワークフローがそれらによって遅くなっているなら、デザインを損ねてでもワークフローをスムーズにしろ。純粋なデザインよりもビジネスと顧客が重要

変わらない設計などない。いかなるモデルも、ビジネス要件が変わるたびに進化する必要がある。これは受注システムに要件を追加する例として 13 章で話す。

コンテキストマップをつくる

コンテキストマップとは:

境界づけられたコンテキスト間の関係を示した全体像。これによって、コンテキスト同士の関係性について技術的詳細に囚われずにコミュニケーションできるようになる
コンテキストマップは高次に保つ。複雑なシステムにおいては、それぞれのコンテキストの詳細にフォーカスした個別のマップが必要になる

📝 境界づけられたコンテキスト同士が連携するならば、当然それらのコンテキストは、交換可能な共有メッセージのフォーマットについて合意している必要がある。

フォーマットの決定については主に上流側のコンテキストが主導権を持つ
- 例外: 【レガシーシステムが下流側にある場合など】上流側のコンテキストが、下流側のコンテキストが要求するフォーマットに合わせないといけない。その場合には翻訳コンポーネントが必要

最も重要な境界づけられたコンテキストに着目せよ

ここまでで、いくつか境界づけられたコンテキストを見つけた。ドメインでの作業をすすめる過程でも、追加で見つかるだろう。それらは等しく重要だろうか？

どこから着手すべきだろう？ → 需要なところから

全ての境界づけられたコンテキストを同時に実装したりするのは NG ❌
優先順位を付ける必要がある。何が重要かについて、コンセンサスがないこともあるが（各部署は自分こそが最重要だと思っている）

重要とは: ビジネス優位性を生むドメインや売上げを生むドメイン

ドメインの大分類:

コアドメイン: ビジネスの根幹となるもの
補助ドメイン: 業務に必要であるもののビジネスの核ではないもの
汎用ドメイン: 他のビジネスでも見られるもの（認証や配送など）。これは安全にアウトソースできる

📝 補助ドメインに見えるものがコアドメインになりうる例: 物販ビジネスにおいて、どの商品も常に出荷可能な状態が保たれていることが顧客満足に決定的に重要な場合、在庫管理ドメインはコアドメインになりうる。

ユビキタス言語をつくる

コードとドメインエキスパートは同じモデルを共有しなければならない

ドメインエキスパートが「注文」と言ったならば、コードでもそれに対応し、同じように振る舞う「注文」というものを定義する ✅
逆に、ドメインエキスパートのメンタルモデルにないもの（注文ファクトリ、注文マネージャ、注文ヘルパーなど）は設計に含めてはならない ❌
- ドメインエキスパートはそれらの意味を理解できないので害にしかならない。もちろんそれらの技術的概念はコードベースの方には出てくるだろうが、それらを設計に入れてはいけない

ユビキタス言語で設計せよ

ユビキタス言語とは: プロジェクトの関係者全員に共有される概念や用語のまとまり。これがビジネスドメインの共通メンタルモデルを定義する。プロジェクトのあらゆる場所で一貫して使われるべき。あらゆる場所とは、コードも含む。

（確か、ドメインモデルを正確に反映するためにコード中のユビキタス言語も日本語で書いている日本のチームの事例があった。言語は Ruby だったと思う）

ユビキタス言語の構築プロセス: 常に WIP。設計とともに進化する

not ドメインエキスパート起点の一方通行 ❌
but プロジェクトみんなによるコラボレーション ✅

⚠️ ドメインの「方言」に注意

ある用語が意味する概念が、ドメインによって微妙に異なる場合がある。イベントストーミング時には特にこれに気をつける必要がある
- 例: 配送部門が言う「注文」は請求部門が言うそれとは微妙に違う。配送部門の関心は在庫つまり数にあるが、請求部門の関心は価格と支払いにある。もし「注文」をコンテキストの明示なしにさまざまな場所で使ってしまうと誤解が生じてしまう

→ 全てのドメインとコンテキストをカバーするユビキタス言語を作るのは無理

ドメイン駆動設計の概念をまとめる

【ドメイン】解こうとする問題に関係する知識領域。ドメインエキスパートが専門とする
【ドメインモデル】特定の問題に関わるドメインの側面を単純化したものの集合。ドメインモデルは解決領域の一部で、ドメインは問題領域。
【ユビキタス言語】ドメインと関連し、チームメンバーとソースコードに共有される概念や語彙の集合
【境界づけられたコンテキスト】明解な境界によって他と区別される、解決領域の子要素。
【コンテキストマップ】境界づけられたコンテキスト間の関係を示した高次の概念図
【ドメインイベント】システム内で起こった事実の記録。必ず過去形で記述され、何らかのコマンド（原文では “activity” と書いてある）をトリガーすることが多い
【コマンド】何らかのプロセスへの開始要求。人やイベントによってトリガーされる。プロセスが成功するとシステムが変化し、一つ以上のドメインイベントとが記録される

まとめ

イベントとプロセス

イベントストーミングによって、ドメイン内の全ての主要なドメインイベントが見えるようになった。受注プロセスは注文書を郵便で受け取るところから始まり、見積書の作成、新規顧客の登録などのワークフローがあることもわかった。

受注チームが注文を処理し終わると、そのイベントが配送部門の配送プロセスをスタートさせ、請求部門の請求プロセスをスタートさせることも学んだ

他にもプロセスはたくさんあるが、本書では一つに着目する。

サブドメインと境界づけられたコンテキスト

ここまでで、3 つのサブドメインが見つかった（受注、配送、請求）。これらに対応する 3 つの境界づけられたコンテキストを作り、それぞれの関係を示したコンテキストマップをつくった。

どれが注目すべきコアドメインだろう？ どこを自動化すると価値が最大化されるか？ → 現時点では受注ドメインからとりかかることにしておく

必要ならば、受注ドメインの仕事を紙に出力することで、他のチームが今まで通りの方法で仕事を続けることもできる。

ユビキタス言語

ここまでで、「注文フォーム」「見積もり」「注文」という言葉を見つけた。設計を深める過程でもっと見つかるだろう。ユビキタス言語は、wiki などのライブなドキュメント（印刷した書類は固定化されてしまうが、wiki は更新が前提）でメンテナンスするといい。チームメンバーの足並みが揃うし、新しいメンバーもキャッチアップしやすい。

次にやることは？

本章によって

問題の全体像と、解決策の概略が見えた 💡
しかし詳細設計やコーディングを始めるにはまだ多くの疑問がある 💭
- ❓ 注文処理ワークフローでは何が行われているのだろう？
- ❓ 入出力はどんな感じ？
- ❓ このワークフローが連携する他のコンテキストはある？
- ❓ 配送チームの「注文」と請求チームのそれはどう違う？
- などなど

次の章では注文確定ワークフローに着目して、これらの問いに答えていく

第 2 章: ドメインを理解する

Sun, 17 Nov 2024 00:00:00 +0900

“2. Understanding the Domain” from “Domain Modeling Made Functional: Tackle Software Complexity with Domain-Driven Design and F#” 📚

一つのワークフローに着目して掘り下げていく

何がそれをトリガーするのか？
どんなデータが必要？
どんな境界づけられたコンテキストと協働する必要がある？

ここでは注意深く耳を傾ける能力が重要。自分のメンタルモデルをドメインに押し付けないようにしたい。

ドメインエキスパートへの聞き取り

ドメインエキスパート（文中では受注部門のメンバー）に聞き取り調査をしていく。

ポイント:

イベントストーミングで洗い出したコマンド・イベントを手がかりに、聞き取り調査をいくつかの小さい単位に分ける ✅
- 忙しいドメインエキスパートに時間をとってもらいやすい
インタビューの初期は高次の視点を維持し、ワークフローの入出力だけに着目する ✅
- 詳細に囚われすぎずに済む
顧客がシステムをどう使うかの結論を急がず、人類学者のようにとにかく耳を傾ける ✅
- 文中では「顧客が注文フォームをオンラインで入力してくれたらいいのに」というドメインエキスパートの言葉に対して、開発者は一般的なカート & チェックアウトパターンのシステムを想像しかけた
  - しかしドメインエキスパートが求めるのはそのパターンではなかった 💣
理想的には、設計の前にドメインエキスパートが働く様子を観察したりするとよい ✅

非機能要件を理解する

一歩下がって、ワークフローのスケールとコンテキストについて議論する。

文中では、後のアーキテクチャ決定に関わる下記の要件についてドメインエキスパートに尋ねている:

1 日あたりのリクエスト数
リクエスト数の年間変動
ユーザーの属性（ビギナー or プロフェッショナル）
サービスに期待されているレスポンス

ワークフローの残りを理解する

ドメインエキスパートへの聞き取りによってドメインの知識を獲得していく。

文中では「受け取ったそれぞれの注文フォームで何をするのか？」という質問から始めて、下記のドメイン知識を発見した:

検証作業
協調すべき境界づけられたコンテキスト
集計作業
注文確認の返信作業
同じ入力を利用する別のワークフロー（見積もり作業）

入出力について考える

ワークフローの入出力について、聞き取りから学んだことを書き留める

入力: 明らかに注文フォーム ✅
出力:
- 「処理済みの注文」という概念があることはわかった。しかしそれ自体は特に出力として使い道がない ❌
- 注文確認はどうか？これは注文確定ワークフローの副作用であり、出力ではない ❌
- 出力は常に生成イベントであるべき ✅
  - 他の境界づけられたコンテキストのアクションをトリガーするもの
  - ここでは注文が確定されたイベント

データベース駆動設計したくなる衝動と戦う ⚠️

📝 この節は目からウロコだった・・・！この節を読むべきなのは初学者よりむしろ、ビジネス要件から DB スキーマを設計することに慣れている人だと思う。

ある程度経験を積んだプログラマなら、もう詳細設計して実装に入りたくなるだろう。テーブル間の関連について、下記のように設計を始めるかもしれない:

erDiagram
    Customers ||--o{ Orders : places
    Customers {
        string name
        string custNumber
        string sector
    }
    Orders ||--|{ OrderLines : contains
    Orders {
        string customerId
        string shippnigAddressId
        string billingAddressId
        bool isQuote
    }
    OrderLines {
        string orderId
        string productId
        float quantity
    }
    Addresses ||--|{ Orders : referred

・・・しかしこれをやってしまったらオシマイ 💣（マジか）

DDD ではドメインを正確にモデリングすることに集中するために「永続性の無視」というアプローチで設計する:

ドメインに設計を駆動させる ✅
DB スキーマではない ❌
- 実際、現実の紙ベースのシステムではデータベースなど存在しない
- データベースはユビキタス言語には入らない
  - ユーザーはデータがどう永続化されているかには興味がない

なぜこれが重要？ → データベースの視点からデザインすると、データベースモデルに合うようにデータを歪めないといけなくなるから

例:

既に先ほどの ER 図では注文と見積りの違いを無視してしまっている 💣
- 同じ外部キー（orderId は quoteId としても使われる）が二つのリレーションで責務を持つ状況は、データベースの機能ではサポートできない 💣（なるほど・・・！！）

とにかく、技術的な先入観なしにドメインエキスパートの言葉に耳を傾けることに集中するのが重要。ドメイン駆動で設計したモデルを関係データベースに永続化する方法は第 12 章で見ていく。

クラス駆動デザインへの衝動と戦う ⚠️

📝 本節のおかげで、私は個人開発でこの過ちを犯していたことを自覚した

オブジェクト指向の経験があるなら、特定の DB 実装に縛られないことの重要性は理解していることだろう。しかし、ドメインではなくオブジェクトの観点で考えることによって、モデルに偏見を持ち込んでしまう（マジか）。

クラス駆動デザインも、要求をちゃんと聞いていないという点でデータベース駆動デザインと同じくらい危険 💣

こんなふうに設計するかもしれないが

classDiagram
    OrderBase <|-- Order
    OrderBase <|-- Quote

    OrderBase "n" -- "1" Customer
    Order "n" -- "1" Address : shipping address
    Order "n" -- "1" Address : billing address

    OrderBase "1" *-- "n" OrderLine
    OrderLine "1" -- "n" Product

注文と見積りの違いは表現できているできているものの、現実世界に存在しないOrderBaseという人工的なクラスを持ち込み、ドメインを歪めてしまった 💣 （まぁ「ドメインモデルと詳細設計は区別しましょう」で片付く話ではあるか）

心をオープンに保て。技術的な思考をドメインに持ち込むな。

ドメインを文書化する

技術的な実装による偏見に陥らず、要求をどのように記述すべきだろう？ UML のような可視化ダイアグラムを使うこともできるが、労力がかかる割にドメインの機微をとらえられるほどの表現力がない。

正確なドメインモデルをコードで表現する方法は後ほど学ぶとして、今は、ドメインモデルを捉えられる簡単なテキストベース言語を使う:

ワークフローの表現法: 入出力を記述し、ビジネスロジックを記述するシンプルな疑似コードを使う
データ構造の表現法
- 二つの部分が共に必要なときには かつを使う
- どちらかだけでいい時にはまたはを使う

このミニ言語を使って、注文確定ワークフローを記述すると下記のようになる:

境界づけられたコンテキスト: 受注

ワークフロー: 注文確定
  トリガー: "注文フォームを受け取った" イベント（"見積もり" にチェックが入っていたとき）
初期入力:
  注文フォーム
その他の入力:
  商品カタログ
出力イベント:
  "注文が確定した" イベント
副作用:
  注文確定に伴って注文確認が顧客に送信された

データ構造は下記のように表現される:

境界づけられたコンテキスト: 受注

注文 データ =
  顧客情報
  かつ 配送先住所
  かつ 請求先住所
  かつ 注文明細 のリスト
  かつ 請求金額

注文明細 データ =
  商品
  かつ 数量
  かつ 価格

顧客情報 データ = ???   // まだ不明
請求先住所 データ = ??? // まだ不明

これはドメインを少し構造化された方法で捉えただけで、クラス構造もデータベーステーブルもない:

ノンプログラマにとってもこわくない ✅
- ドメインエキスパートにも見てもらい、一緒に取り組んでもらえる
❓ コードもこれくらいシンプルにできるのか？
- → 第 5 章で学ぶ

受注ワークフローを掘り下げる

入出力を記述できたので、聞き取り調査を再開してワークフローを掘り下げていく。

下記のドメイン知識が明らかになった:

注文か見積り依頼かを判別
- 見積り依頼はあとで処理する
  - 売上げを生む注文のほうが重要だから
検証作業におけるサードパーティサービスの利用
用途の異なる書類の山
- 実装ではキューになるだろうが、聞き取り調査では技術的詳細からは距離を保っておく
商品コード のチェック
- 技術的に言うとシンタックスチェック
商品コード の照合
- 技術的に言うとデータベースルックアップ
依存管理
- 「もし、商品部門のだれかがあなたの問い合わせに即座に答えられるとしても、商品カタログをやはり手元に持っておきたい？」「もちろん。電話が使えなかったり、彼らが忙しかったりしても、私の仕事が止まらずに済むから。」
数量単位の仕様

複雑さをドメインモデルに反映させる

ワークフローを掘り下げたことによって、ドメインモデルがかなり複雑になった

これは良いこと ✅
- 実装する段になって複雑性が判明するのは大きな時間の無駄になる
- 初期段階で、ドメインの理解に時間をかけるべき
  - 「数週間のコーディングによって設計にかかる時間を数時間節約できる」という皮肉がある

制約を表現する

聞き取り調査の結果、商品コードと数量が単なる文字列あるいは整数でないことがわかった。これをドキュメントに反映する。

ウィジェットコード、ギズモコード、商品コードの制約は下記のように表現される:

コンテキスト: 受注

ウィジェットコード データ = "W" から始まり 4 つの数字からなる文字列
ギズモコード データ = "G" から始まり 3 つの数字からなる文字列
商品コード データ = ウィジェットコード または ギズモコード

❓ この制約は厳しすぎるだろうか？
- ❓ 新しい商品コードを追加したくなったらどうする？
  - 正しい答えはコンテキストによるが、設計をドメインエキスパートの視点からすることが重要

ここでは、この制約はドメインの設計に反映させるべきだろう。なぜなら、商品コードのチェックは注文確認プロセスの重要な工程であることを学んだので、最終的には何らかの方法でドキュメント化が必要。 別のドキュメントに分散するより設計として書いた方が良い。

ちなみに、設計が厳しいからといって必ずしも実装まで厳しくする必要はない。不正な入力があったときの実装例:

注文全体を即座に拒否（これは厳しすぎるだろう）
ユーザーに「要確認」の通知を出す（よい落とし所かもしれない）

数量に関する制約もドキュメントにしておく:

単位数量 データ = 1 から 1000 までの整数
キログラム数量 データ = 0.05 から 100.00 までの小数

注文のライフサイクルを表現する

注文（型）に着目し、学んだことを記述する。

初期のバージョンでは下記のように表現したが、これはドメインを表現し切れていないことがわかった。

境界づけられたコンテキスト: 受注

注文 データ =
  顧客情報
  かつ 配送先住所
  かつ 請求先住所
  かつ 注文明細 のリスト
  かつ 請求金額

聞き取り調査の結果、下記を学んだ:

注文にはライフサイクルがある
- 注文は初めは請求金額を持たないが最後には必ず持つようになる
未検証の注文や未集計の注文は他と区別できる
- 紙ベースの現在の業務では進捗をフォームに記録しているため

これらをモデルにも反映する必要がある。

未検証の注文 データ =
  未検証の顧客情報
  かつ 未検証の配送先住所
  かつ 未検証の請求先住所
  かつ 未検証の注文明細 のリスト

未検証の注文明細 データ =
  未検証の商品コード
  かつ 未検証の注文数量

各情報のステータスがわかるようになった（DB のフラグで済ませない！！！！）。

注文が確認されると下記のようになる:

検証済の注文 データ =
  検証済の顧客情報
  かつ 検証済の配送先住所
  かつ 検証済の請求先住所
  かつ 検証済の注文明細 のリスト

検証済の注文明細 データ =
  検証済の商品コード
  かつ 検証済の注文数量

次は注文に金額を入力する:

集計済の注文 データ =
  検証済の顧客情報
  かつ 検証済の配送先住所
  かつ 検証済の請求先住所
  かつ 集計済の注文明細 のリスト  // 知識が反映されている
  かつ 請求金額                   // 知識が反映されている

集計済の注文明細 データ =
  検証済の商品コード
  かつ 明細料金                   // 知識が反映されている

ドメインモデルがビジネスロジックを反映するようになった 🎉 初めに考えていたよりも複雑になったが、逆に言えばもしモデルがこのように複雑でなかったとしたら、それは要件を正しく捉えられていなかったということ。

ワークフロー中のステップを肉付けする

ワークフローが小さいステップに分割されることがわかった:

確認作業
集計作業
などなど

これらのステップにも入力出力アプローチを適用しよう

ワークフロー: 注文確定
  入力: 注文フォーム
  出力:
    "注文が確定した" イベント（他のチームに送るための山に置く）
    または "不正な注文" （それ用の山に置く）

  // ステップ 1
  do 注文を検証
  if 注文 が 不正 then:
    add 不正な注文 to 山
    stop

  // ステップ 2
  do 注文集計

  // ステップ 3
  do 顧客に確認を送る

  // ステップ 4
  return 注文が確定された イベント（if エラーがないならば）

それぞれのサブステップもドキュメント化する

ワークフロー: 注文を検証
  入力: 未検証の注文
  出力: 検証済の注文 また 検証エラー
  依存: 商品コードの存在チェック, 住所の存在チェック

  顧客の名前を検証する
  配送先住所と請求先住所が存在することを確認する

  for each 注文明細:
    商品コードをチェック
    商品コードが商品カタログに存在することをチェック

  if 全て OK ならば, then:
    return 検証済の注文
  else:
    return 検証エラー

ほぼ丸写しになってしまうのであとのステップは割愛。

まとめ

次のモデリングフェーズでたくさんやることがあるので、要件の収集はここまで。

ここで学んだことをまとめる:

設計時には実装の詳細に立ち入らないことが重要
代わりに、先入観やコーディング手法にとらわれずにドメインを捉えることに集中しよう

本文中で例として使われている受注システムのようなはかなり単純化されているが、それでもドメインエキスパートの言葉に耳を傾けると、多くの複雑性が明らかになることがわかる。例えば一口に注文といっても、ライフサイクルを通して、データや振る舞いの異なるのバリエーションがあった。

次にやることは？

受注ワークフローを F# の型システムを使ってどのようにモデリングするかをみていきたい。次章ではその前に、一歩下がって全体像を見て、システム全体をどうソフトウェアアーキテクチャに翻訳するかを議論する。

第 3 章: 関数型アーキテクチャ

Thu, 21 Nov 2024 00:00:00 +0900

“3. A Functional Architecture” from “Domain Modeling Made Functional: Tackle Software Complexity with Domain-Driven Design and F#” 📚

次の課題: これまで得てきたドメインに対する理解を、どのように関数型プログラミングに基づいたソフトウェアアーキテクチャに翻訳するか

⚠️ 注意点: 現時点ではまだ具体的なアーキテクチャについて考えすぎないようにすること
時間を使うならば: 引き続きイベントストーミングや聞き取り調査などによってドメインと要件をより深く理解する

本章で学ぶ内容:

関数指向ドメインモデルのための典型的なソフトウェアアーキテクチャ
DDD の概念（境界づけられたコンテキスト、ドメインイベントなど）がどのようにソフトウェアに翻訳されるのか
ラフな実装方針

本書が使うアーキテクチャ概念:

システムンテキスト: 業務システム全体
- コンテナ¹: システムコンテキストを構成するデプロイ可能単位
  - コンポーネント: 各コンテナを構成するコードの大きい構成単位
    - クラス（あるいはモジュール）: コンポーネントの構成要素

自律的なソフトウェアコンポーネントとしての境界づけられたコンテキスト

DDD の概念である “境界づけられたコンテキスト” とソフトウェアアーキテクチャとの関連を示す。

コンテキストとは: うまく定義された境界に基づく自律的なサブシステム

このように定義を定めたとしても、アーキテクチャとしての構成方法はいくつものパターンをとりうる
- コンテナとドメインのマッピング例:
  - コンテナ = 業務: システム=コンテナでもある。このとき、境界づけられたコンテキストはインターフェイスによって定義された個別のモジュール（.NET でいう “アセンブリ”）
  - コンテナ = 境界づけられたコンテキスト: 伝統的なサービス指向アーキテクチャ
  - コンテナ = ワークフロー: こうなるとマイクロサービスアーキテクチャ

ただし、ドメインについて理解しきれていないフェーズでは、まだ特定のアーキテクチャパターンを選ぶ必要はない。最重要なのは境界づけられたコンテキストを疎結合に設計し、自律可能に保つこと。

境界を正しく定めることの重要性は述べたが、実際にはプロジェクト初期から正しく定めるのは難しい

理由: 知識を得るにつれて境界は変わりうるから
よって、開発初期にはまずはモノリスパターンで始めることをおすすめする
- マイクロサービスパターンを使う明確なメリットが見えているならばこの限りではない
- 本当に疎結合なマイクロサービスアーキテクチャを実現するのは難しいからでもある
  - あるマイクロサービスを止めたときに別の場所が壊れるならば、それはただの “分散モノリス”

境界づけられたコンテキスト間におけるコミュニケーション

どうコミュニケーションする？→ ドメインイベントを通じて

注文処理を終えた受注部門が配送部門に対して配送を依頼する場合の例:
- 受注コンテキストは注文が確定されたイベントを発行する
- 注文が確定されたイベントはキューに入るか、直接発行される
- 配送コンテキストは注文が確定されたイベントをリッスンする
- 配送コンテキストがイベントを受け取ると注文を配送せよコマンドが作られる
- 注文を配送せよコマンドは注文配送ワークフローをトリガーする
- 注文配送ワークフローが完了すると注文が配送されたイベントが発行される

このように設計すれば、受注・配送の両コンテキストは互いについて知る必要なく、イベントを通じてコミュニケーション可能。

イベントを実際に発行する方法
- 選定したアーキテクチャによる
  - キューや関数呼び出しなどが考えうるが、今はまだ決めなくていい
- 各コンテキストが自律できるよう、設計を疎結合に保つことが重要
イベントをコマンドに変換するハンドラ
- これも複数の実装パターンが考えうる
  - 下流コンテキストの一部としたり、独立したルータやプロセスマネージャにしてもいい
  - 選定するアーキテクチャや、イベントとコマンドの対応づけをどこでしたいかによって決めればいい

📝 イベントを利用したコミュニケーションの特徴は互いを意識せずに済むところ。確かにイベント経由通信を使わなくとも、ある程度の疎結合性は「インターフェイス契約+非同期コミュニケーション」で獲得できる。それでもやはり、通信時には相手にデータを投げるなり、相手のメソッドを呼び出すなり、コード中に必ず「相手」が出てきてしまう。

境界づけられたコンテキスト間におけるデータのやりとり

コミュニケーションに使われるイベントは、下流コンテキストが処理に必要としている全てのデータを含む。

例:
- 注文が確定されたイベントは注文データ全体を含む
  - 注文を配送せよコマンドを作るのに必要な情報全てを配送コンテキストに渡すため

データがイベントに含めるのには大きすぎるなら、共有データストレージを利用してもよい。

このデータオブジェクト──Data Transfer Objects（DTO）と呼ぶ──は、境界づけられたコンテキスト内で定義されたオブジェクトと同じに見えるが、厳密には違う。

シリアライズしてコンテキスト間で共有できるよう設計されている
- 上流コンテキストの境界付近でドメインオブジェクトは DTO に変換される
  - JSON や XML などにシリアライズされる
下流コンテキストでは、このプロセスが逆方向に実行されてドメインオブジェクトが作られる

（例） 注文が確定されたイベントの DTO の構造:

イベント DTO
- 注文 DTO
  - 注文明細 DTO のリスト

信頼性境界と検証

境界づけられたコンテキストの輪郭は信頼性境界としてはたらく

境界の内側: 全て信頼可能で、有効であるとみなされる
境界の外側: いかなるものも未検証で、不正になり得る

このような境界が機能するように、ワークフローの入口と出口にゲートを設置する必要がある。

入力ゲート

渡された DTO がドメインの制約（例: ある属性が非null かつ 50 文字以内であること）を満たしていることを保証するために、入力を必ず検証する。検証失敗時には、残りのワークフローはスキップされて例外が送出される。

出力ゲート

非公開情報が境界の外に出ないようにする役割を担う。

目的:

コンテキスト間の意図しないカップリング（なるほど！）
セキュリティ向上

これらの目的を果たすため、出力ゲートはドメインオブジェクトを DTO に変換する際に、情報を意図的に捨てる。

境界づけられたコンテキスト間の契約

境界づけられたコンテキスト間のカップリングをできるだけ減らしたい

しかし共有コミュニケーションは常に何らかの結合をもたらす
- イベントと、関連する DTO は境界づけられたコンテキスト間に一種の契約をもたらす
- コミュニケーションを可能にするにはコミュニケーションに使う共通形式について両コンテキストが同意している必要がある

誰が契約の締結を決定する？→コンテキスト間の関係性による

関係性の例:

共有カーネル: 二つのコンテキストが共通のドメイン設計をいくつかもつ
- よって関係するチームは協働する必要がある
  - 例: 受注コンテキストは配送先住所を受け取り、検証する。配送コンテキストは配送にその住所を使う
- イベントや DTO の定義を変えるときには関係者のレビューが必要
顧客/供給者（または顧客駆動契約）: 下流のコンテキストが上流コンテキストに供給してほしいものを定義する
- 上流が契約を守っている限り、両ドメインは独立に進化できる
  - 例: 請求コンテキストが契約を定義し、受注コンテキストがそれを供給する
順応者: 顧客駆動とは逆に、上流の定義を下流が受け入れ、自らのドメインモデルをそれに合うように適応させる
- 例: 受注コンテキストは製品カタログが決めた契約に従っている

腐敗防止層

外部システムと通信したいとき、利用可能なインターフェイスが自コンテキストのドメインモデルと全く合わないことがある

腐敗防止層（入力ゲートがこの役割を果たすことが多い）を使って、やりとりやデータをコンテキストに合うものに変換する必要がある
- 理由: ドメインモデルが外部のシステムに合わせようとして「壊れて」しまうのを防ぐため

コンテキストマップと関係性

設計が進み、コンテキスト間の関係が決まったとする:

受注・配送コンテキスト間: 共有カーネル
- なのでコミュニケーション契約を一緒に決める
受注・請求コンテキスト間: 顧客駆動契約
- 請求コンテキストが契約を決め、受注コンテキストがそれを提供する
受注・製品カタログ間: 適合者パターン
- 受注コンテキストは製品カタログが定めたモデルを使う
外部の住所確認サービス: 本システムのドメインモデルと全然合わない
- 腐敗防止層を介して利用する

コンテキストマップコンテキストをもつチームがどのように連携すべきかも示す

技術的な課題であると同時に組織的な課題でもある

境界づけられたコンテキスト内におけるワークフロー

ビジネスワークフローの表現:

DDD の概念に基づく表現: コマンドにより起動され、いくつかのドメインイベントを発するミニプロセス
関数型アーキテクチャにおける表現: コマンドオブジェクトを入力とし、イベントオブジェクトのリストを出力とする一つの関数

本文中の模式図を使った説明:

ワークフローは常にただ一つの境界づけられたコンテキストに含まれる
公開ワークフロー（コンテキスト外からトリガーされる）は境界の外側に少しはみ出している

ワークフローの入力と出力

入力: 常にコマンドとひもづくデータ
出力: 他のコンテキストと通信するためのイベントのリスト

受注ワークフローにおける例:

入力:
- 注文を確定せよコマンド
- 紐づくデータ
出力: 注文が確定されたイベントなどのイベントのリスト

請求コンテキストにおける例: （顧客/供給者パターンであることに注意）

ただの注文が確定されたイベントを出すだけでなく、イベントに含めるデータはは請求に必要なデータのみに限る必要がある
- 例: 請求先住所と合計金額だけ。配送先住所と商品リストは入れない

つまり、我々は新しいイベント（言うなれば請求可能な注文が確定したイベント）を発行する必要があることを意味する。

また注文確認が送信されたイベントも送りたいなので前に作ったダイアグラムはもう古いので新しくしたい

ワークフローの模式図の中で重要なのは、関数はイベントを発行してはおらず、単に返しているだけであるところ

理由: どのように発行するかは別の関心事なため

境界づけられたコンテキスト内のドメインイベントを避ける

オブジェクト指向設計でよく見られるパターン: 境界づけられたコンテキスト内で、ドメインイベントを受けたリスナーが別のドメインイベントを発行 ⚠️

関数型アプローチではやらない

理由: 隠れた依存を生み出してしまうから
- リスナーが必要な場合にはワークフローの終端に置く
  - 効果:
    - ミュータブルなグローバルイベントマネージャがいないことが明示される ✅
    - 理解・メンテナンスしやすい ✅

境界づけられたコンテキスト内のコード構造

伝統的な「レイヤーアプローチ」では、コードは下記のような層に分けられる:

コアドメインまたはビジネスロジック
データベース
サービス
API またはユーザーインターフェイス

ワークフローは表面のインターフェイスから始まって最深部のデータベースに到達し、また表面に戻る

この手法の問題点 ⚠️:

「同時に変更されるコードは同じ場所に属するべき」という設計原則を破っている
層が「水平に」組み合わさっているので、ワークフローの動きを変えようとする場合には全ての層を変更する必要がある

よりよい方法 ✅: 「垂直な」構成に移行

それぞれのワークフローは各自の仕事を終えるために必要なコードを全て含む
ワークフローに対する要求が変わったら特定の垂直スライスだけを変えればいい

これは理想論ではなく実際に可能

オニオンアーキテクチャ

オニオンアーキテクチャ:

ドメインを真ん中に置く
その周りにその他の側面を配置する
- 配置ルール: それぞれの層は外側にでなく、内側にだけ依存する

この構造に対して関数型の依存注入を使う方法は第 9 章で述べる

I/O を外側に保つ

関数型プログラミングの主な狙い: 予測可能で、内部を見ることなく簡単に説明できる関数を使って仕事をすること

そのために、関数を下記のように設計する:
- 可能な限りイミュータブルなデータを使うことで依存を明示する
- ランダム性・関数外の変数の更新などの副作用や、いかなる I/O も持たないようにする

DB やファイルシステムを使って読み書きするシステムは「不純」とみなされる → そのような関数はコアドメインから取り除く

❓ データの読み書きはどうやったらいい？ → I/O をオニオンアーキテクチャの最外殻に保つ

データベースにアクセスするのは、ワークフローの内部ではなく最初と最後のみ
- ドメインモデルに DB が登場しないのなら、ワークフローでも内部から DB にアクセスできてはいけない
利点:
- 関心が異なるもの同士を分離できる
  - コアドメインはビジネスロジックのみに集中
  - 永続化や他の I/O はインフラが管理する

まとめ

DDD に関する概念と定義をいくつか紹介した

ドメインオブジェクト: BC 内側でのみ使われるオブジェクト
DTO: シリアライズされて bc 間で共有されるためのオブジェクト
共有カーネル、顧客/サプライヤ、適合者: 境界づけられたコンテキスト間の関係パターン
腐敗防止層: あるドメインの概念を他のドメインのものに翻訳するコンポーネント。カップリングを減らし、各ドメインが独自に進化できるようにする
永続化の無視: ドメインモデルはドメイン自体の概念のみ基づくべきであり、永続化メカニズムへの意識は含むべきでない

次に学ぶこと

ドメインを理解し、解決策を設計するアプローチを理解したことで、それぞれのワークフローの設計と実装に取り組めるようになった。

続く数章でやること:

F# の型システムを使ってワークフローとデータを定義する
実際にコンパイル可能ながら、ドメインエキスパートや非開発者にも理解可能なコードを書く

そのために次の章で学ぶこと:

関数プログラマにとって型とは何を意味するのか
クラスとどう違うのか

Docker などの仮想環境技術の文脈における “コンテナ” ではないので注意 ↩︎

義元左文字

Thu, 04 Dec 2025 00:00:00 +0900

概要

frasyrを利用したStrangler Figアプローチで、資源評価事業全体のwebアプリケーション化を試みるプロジェクト。

開発経緯

本プロジェクトの前身となった三日月宗近では、パラメータ最適化など、科学計算部のパフォーマンスが問題となった。そこで、frasyrをモノリスアプリケーションとして動かしたうえで、その周囲に関心領域の分かれたマイクロサービスを追加していくアプローチを検証する。

現在の状態

進行中

村正

Thu, 01 Jan 2026 00:00:00 +0900

概要

Excel/CSVのシートから、空行で区切られた複数の表を検出し、それぞれをタイトル行、ヘッダー行、データ行に分けて読み取るJavaSrcipt用ツール。

印刷物の表のようなレイアウトでデータが配置されたシートでは、1枚に複数の表が並び、表の上にタイトルが書かれていることが多い（いわゆるネ申エクセル）。村正は次のルールで、こうしたシートを機械が扱える矩形のデータとして読み込む:

空行で区切られた行のまとまりを、表の候補（ブロック）とみなす
ブロックの先頭行が、ブロック内の最大列数より少なければタイトル行とみなす
タイトルの次の行をヘッダー行とみなす。正規表現でヘッダー行を指定することも、ヘッダーなしと指定することもできる

開発経緯

資源評価事業をドメインモデリングに基づいてアプリケーション化する三日月宗近プロジェクトで、査読者用のデータアップロード機能が必要だった。このような外部との連絡部分では、自アプリのモデルを外部のデータ型式から守るためのいわゆる「腐敗防止層」が必要となる。腐敗防止層のうち、Excelファイルからデータを取り出す部分を、汎用パッケージとして切り出した。

現在の状態

npmで公開中（“muramasa” ではまずいのでさすがにまともな名前をつけた）: @rindrics/tblparse

基本的にはnpmパッケージだが、GUIから使えるデモサイトを下記でホストしている:

tblparse Demo | tblparse.rindrics.com

https://tblparse.rindrics.com/

recurring-backlog-item-creator

Sun, 09 Nov 2025 00:00:00 +0900

概要

設定ファイルに基づいて、GitHub Projectsのバックログアイテム（issue）を定期的に自動作成するGitHub Actions。作成周期（毎月、四半期、年1回など）の異なる定期issueは、種類ごとにGitHub Action workflowが必要なため嵩張る。これを設定ファイル一つで管理できるようにした。

設定できる項目:

issueごとの作成月
タイトルの接頭辞・接尾辞（{{YearMonth}} などのテンプレート変数を使える）
Projectのカスタムフィールド

目的

振る舞いをコードではなく、データとしての設定ファイルで表現する感覚をつかむこと。

設定をデータとして扱うと、「今月どのissueを作るか」は、設定と月からissueの一覧を求める変換として書ける。そこで、CLIとActionとに分けて設計した:

CLI: 設定ファイルと月を受け取り、作るべきissueをJSONで返す
- Goを使うことで楽に書けた
- 副作用のない関数を中心に実装した。フィールドの検証やIDの解決でGitHubを読む部分はインターフェースで抽象化し、テスト時にモックに差し替え可能にした
Action: GitHubへの外部副作用（issueの作成、Projectへの追加、フィールドの設定）を担当

現在の状態

GitHub Marketplaceで公開中: rindrics/recurring-backlog-item-creator

ppap-cli

Sat, 01 Jun 2024 00:00:00 +0900

概要

PPAP（Password付きZIPファイルを送ります / Passwordを送ります / Angoka Protocol）を使った添付ファイル送信を助けるCLI。

目的

ブラックジョークのソフトウェア表現の模索。

現在の状態

リポジトリで公開している。

数珠丸

Mon, 01 Jan 2024 00:00:00 +0900

概要

独自ドメインのメールをSlackをクライアントとして送受信するツール。

受信: SESで受けたメールをS3に保存し、Lambdaで解析してSlackに投稿する。本文がSlack Block Kitの文字数制限を超える場合は、ファイルとしてスレッドに添付する
送信: botにテンプレートを出させ、記入して投稿したメッセージのURLをbotに渡すと、プレビューが表示される。確認して送信ボタンを押すとSESから送る。同じメッセージからの二重送信は防いでいる

目的

独自ドメインのメール送受信環境を作ること
- 商用サービスほどの可用性は必要ないので作ってみた。
- 常時稼働のサーバーがないので運用コストが低い。受信したメールはまずS3に保存するので、Slackへの投稿に失敗してもメール自体は失われない
「インフラがインターフェイスを実装する」という考え方が、クラスレベルだけでなくパッケージやデプロイレベルでも成り立つことを実感すること
- メールの解析や送信の判断はcoreパッケージにまとめ、ストレージやメールサーバーとのやり取りはリポジトリのインターフェースとして抽象化したので、一応クラウドプロバイダの種類にも依存しない設計になっている

現在の状態

coreパッケージはnpmで公開中（さすがにまともな名前をつけた）: @rindrics/slackmail

独自ドメイン宛てのメールは、すべて本ツールで受信している。

三日月宗近

Wed, 01 Jan 2025 00:00:00 +0900

概要

資源評価のプロセス全体をwebアプリケーション化する試み。計算部だけでなく、業務プロセスの進行: 評価ステータスの遷移などもドメインモデリングされている。

デモとドキュメントは下記から利用できる:

資源評価Web | mikazuki-munechika.rindrics.com

https://mikazuki-munechika.rindrics.com

資源評価Web 📖 | docs.mikazuki-munechika.rindrics.com

https://docs.mikazuki-munechika.rindrics.com

開発経緯

下記はプロジェクト開始時のモチベーション文:

資源評価事業をwebアプリケーション化する実験をしている。資源計算だけでなく、計算・執筆・提案・議論・合意形成の流れからなる資源評価「事業」全体の話だ。

この事業の難しさは、科学的・政治的要求にもとづく課題を解決する数値計算方法を開発するところにあるのはもちろんだが、そもそもコミュニケーションの難しさのほうがより重要なのではないか: 立場や知識背景がまったく異なるステークホルダーが、資源評価という関心領域（ドメイン）の下に集まって、漁獲可能量という一つの数値について議論し・意思決定しないといけない。

ソフトウェア設計者たちは、これと同じ問題が（広義の）ビジネスがある場所には必ず潜んでいることに気づいており、その解決のために「ドメイン駆動設計（Domain-Driven Development. DDD）」を2000年代前半に確立した。ドメイン駆動設計では、開発過程における思考資源の投資先を、プログラミングのような技術的詳細ではなく、ビジネスの営みを抽出した「ドメインモデル」をつくることに集中する。ドメインモデルは一度作って終わりではなく、ステークホルダー間で認識の齟齬が見つかるたびに、その新たな知識はモデルに反映される。このようにして磨き上げたドメインモデルを中心としてアプリケーションを開発するこの手法は、資源評価事業においてもヒントになると考えている。

現在の状態

開発停止（検証完了）

資源評価プロセスを型で表現し、コード補完などやコンパイル時チェックで開発を支援できることを確かめられた。

計算のフローチャートを実際のコードから生成できることがわかった
日本語を使うことで、細かいニュアンスの違いも吟味しながらドメインモデリングできることがわかった
- 参考: ドメインモデリングに日本語を使う

検証の過程でわかったこと

Node.jsではパラメータ最適化部分で速度が出ず、科学計算に適した言語を呼び出す必要がある
- frasyrを入れたRを呼び出すのが自然
  - frasyrモノリスを使ったStrangler Figアプローチの後継プロジェクト義元左文字で検証する
  - 三日月宗近と義元左文字は背反ではなく、必要であれば両者をつなぐこともできる
ドキュメントとしてエクスポートする型は、ドメインエキスパートに見せるものに絞るのがよさそう
- あまり考えず生成したらこうなったが、これを見たドメインエキスパートを圧倒してしまうと思う
評価のステータスを型で表すこと自体はいいが、状態をオブジェクトに持たせる旨味はなかった
- ユースケースを考慮しても、状態はイベントから導出するほうがよいだろう

データ登録処理に関する技術選定: Revision IDの生成アルゴリズム

Mon, 28 Sep 2026 00:00:00 +0900

data-registryによるRevision ID生成アルゴリズムにUUID v7を選択した。

背景

資源評価に利用するデータの永続化を担うdata-registryの開発をすすめている。

Tag "data-registry" | rindrics.com

https://rindrics.com/tags/data-registry/

前回の記事では、冪等性キー生成に用いるハッシュアルゴリズムを選んだ。本記事では、永続化処理が実行される際のRevision IDの生成方法について考える。

要件

現時点で、data-registryには下記のユースケースが見つかっている:

版の履歴閲覧: あるデータセットの変更履歴を時系列で表示したい
データ登録要求の並行受信: 複数人のユーザーが複数シナリオを並列計算し、それらのクライアントからの登録要求を受信した

上記から、Revision IDの生成は、以下の要件を満たす必要がある:

要件	説明	要件ID
一意性	各Revisionは一意のIDを持つ	SR001
不変性	一度生成されたら変更されない	SR002
時系列順序付け可能性	同じRevision chain内で自然にソート可能	SR019
分散生成可能性	Coordinatorなしで各プロセスから生成可能	SR020

ここで、不変性（SR002）については実装の責務として考慮外とし、残りの要件を満たすID生成アルゴリズムを選定する。アルゴリズムには複数の候補が考えうるが、詳細な検討の手間を軽減するには、まず時系列順序付け可能性を根拠に選択肢を刈り込むとよさそう。

候補アルゴリズム

ID群が時系列で順序付けされるためには、IDは時刻情報を含むtimestamp-basedな手法で生成される必要がある。

これに着目すると、例えばNanoidやUUID v3, v4, v5, v8は検討対象から除外でき、候補としては下記が残る:

なお、timestamp-basedな手法としてはUUID v1およびv6も含まれるが、これらと比較した場合にはv7が推奨されている（スーパー意訳）ため検討候補から除外した。

候補アルゴリズムの比較検討

連番（✘ 不採用）

その名の通り、連番の整数をIDに使う方法。

ID: 1, 2, 3, 4, ...

この手法の利点はストレージのオーバーヘッドが少ないことだろう。表現はシンプルだが、それを実現するアーキテクチャや実装は必ずしもシンプルとは限らない。 2種類の実現方法「データベースレベル」「アプリケーションレベル」それぞれについて、pros/consを整理してみる。

方法A: データベースレベル

PostgreSQL の SERIAL/BIGSERIAL（自動採番機能）を利用する方法。

pros:
- ✔ 採番の責務をデータベースに持たせられる
- ✔ ロック時間が短い
cons:
- ✘ 単一のprimary writerに依存
- ✘ スケーラビリティ: 並行タスクが全て同じDBに集約

方法B: アプリケーションレベル

採番の責務をアプリケーションで持つ構成。この方法をとるとデータベースについては水平スケールが自由になるが、結局ほアプリケーションレベルに移ってきた採番の責務がボトルネックになる。

つまり、連番形式は宿命的に「最後の値は何か」というグローバルな状態管理に依存する方法で、この状態は必ずどこかに集約されることになる。結果として、SR020（分散生成可能性）を満たさないため不採用とする。

Snowflake ID（✘ 不採用）

Twitterなどの大規模分散システムで運用実績のある手法。

ID: 175638572750991360
     ├─ timestamp(ms)
     ├─ machine id
     └─ sequence

pros:
- ✔ 大規模分散システムでの運用実績あり
- ✔ ストレージ効率がよい
cons:
- ✘ Machine IDの事前割り当てが必須（新規マシン追加時に管理が必要）
- ✘ 各machineが自身のsequenceを管理する必要がある

ストレージ効率の良さは魅力的だが、プラットフォームの潜在ユーザーの規模を考慮すると、machine IDの割り当てなどの運用オーバーヘッド増加がペイされるとは考えにくい。 data-registryにおける採用は見送ることにする。

UUID v7（✔ 採用）

UUIDの一つ。タイムスタンプベースのフィールドを備えつつ、同タイプの先行バージョン（v1およびv6）に比べてランダム特性が向上している。

ID: 0189a5c5-a92b-7b47-b5ad-e6c3cb6c41e9
   └─ from timestamp ─┘

pros:
- ✔ 決定的に生成できるため各ノードで独立生成可能
- ✔ 高いB-tree局所性による高速書き込み
- ✔ 標準性（cf: RFC 9562）
- ✔ エコシステム充実: Clojureでもライブラリを利用可能
cons:
- ✘ タイムスタンプ衝突にはランダム¹部分のみで対処する必要がある
  - TODO: ランダム部分のビット長が最悪ケースをカバーするか確認する

短所もあるものの、これらはdata-registryのユースケースにおいては問題にならないかもしれないので、実際に試算してみる。

同タイムスタンプ内における一意性違反リスク

UUID v7では、同じミリ秒内に複数のIDを生成する場合、一意性の保証はランダム部分（74ビット）で対処する必要がある。この問題をキューイングなどのアーキテクチャで解決しない場合において、UUID v7のエントロピー性能がdata-registryの最悪ケースをカバーできるかを見積もる。

この問題は誕生日問題と同じなので、並行プロセス数を$n$は、ランダム部分のビット長を$b$とすると、衝突確率は下式で表される:

$$ P(\text{1組以上が衝突}) = 1 - \frac{1}{e^{\frac{n (n - 1)}{2^{b+1}}}} $$

いま1,000,000の並行プロセス（1,000ユーザー × 1,000シミュレーション）が同ミリ秒内にIDを生成する場合、$n = 10^6$、$b = 74$なので、衝突確率は

$$ \begin{aligned} P(\text{1組以上が衝突}) &= 1 - \frac{1}{e^{\frac{10^6 (10^6 - 1)}{2^{75}}}} \\ &\approx 1 - \frac{1}{e^{\frac{10^{12}}{3.8 \times 10^{22}}}} \\ &\approx \frac{10^{12}}{3.8 \times 10^{22}} \\ &\approx2.63\times10^{-11} \\ &= 2.63\times10^{-9} \text{\%} \end{aligned} $$

となり、ピーク時リクエストに対してアーキテクチャによる緩衝を挟まない場合にも、UUID v7のエントロピー性能は充分な安全マージンを持つことがわかった。

以上から、data-registryにおけるRevision IDの生成したアルゴリズムにはUUID v7を採用する。

所感

本記事でも、前回の記事と同様に、最悪ケースに対するキャパシティ見積もりに基づいて技術選定した。実際には、最悪ケースに対してアーキテクチャ的な解決を挟まない場合にはID衝突以前に別の問題（スループットなど）が生じそうだが、ひとまずの物理的な猶予は把握できた。大規模アーキテクチャにおける成功例: Snowflake IDも一応は検討したが、個人開発における運用性を考えると選べなかった。

次回は、Revision IDと冪等性キーの永続化方法について考える予定。

疑似乱数であり、実際は決定的に生成する。 ↩︎