メインコンテンツまでスキップ

ドメインを探る: イベントストーミングとユビキタス言語

前の章で、注文の API の要件を、ストーリー・受け入れ条件・ユースケースで書きました。要件の文書は、書いた人の言葉で書かれています。同じ「在庫」でも、店の人は棚にある数を思い浮かべ、開発者は表の列を思い浮かべるかもしれません。また、前の章では「一部の商品だけ在庫が足りないとき」の扱いを、未決の問いとして残しました。

この章では、注文するときに起きる出来事を時系列に並べて、関わる人のあいだで語と流れをそろえます。使う道具は、Alberto Brandolini の本『Introducing EventStorming』が扱うイベントストーミングです。並べた結果から未決の問いに答え、語を用語集にまとめ、要件の文書がその語を守っていることをテストで確かめます。

イベントストーミングとは​

イベントストーミングは、業務で起きる出来事を付箋に書いて壁に貼り、時間の流れに沿って並べていくワークショップです。本の事例では、参加者に、業務の重要な出来事を過去形の動詞でオレンジの付箋に書いてもらい、時間の流れに沿って並べるよう頼んでいます (Introducing EventStorming のサンプル)。

このガイドが出来事から並べるのは、出来事が業務で起きた事実だからです。「注文が受け付けられた」は、画面の有無や API の形に関わらず、店にとって起きたことです。事実から並べると、画面や API の形に引きずられずに業務の流れを確かめられます。

このガイドでは、1 周目の注文に要る範囲だけを使います。ワークショップの粒度の違いや進め方の段階は、Laravel × DDD ガイドのイベントストーミングの章で扱っています。

付箋の種類​

付箋は、書くものの種類ごとに色を分けます。色は、Brandolini の本の前書きの配色と、本文の事例の説明に合わせています。

種類色書くことこの章の例
ドメインイベントオレンジ業務で起きた出来事。過去形で書く注文が受け付けられた
コマンド青人の意図・行動・判断注文する
アクター小さな黄色人の区分購入者
リードモデル緑判断に要る情報商品の価格と在庫
ポリシーライラック出来事の直後に起きて、別のコマンドを起こす決まり。本の例は「新しい端末からログインしたら、SMS で警告を送る」1 周目には無い
外部システム大きめのピンク外部の組織・サービス・オンラインのアプリ1 周目には無い (後の周回の決済サービスなど)
ホットスポットマゼンタ問題・リスク・さらに調べること・情報が足りずに決められない選択・重要な要件を持つところなど一部の商品だけ在庫が足りないとき

公開されているサンプル版 (2021 年 8 月の版) の中でも、ホットスポットの色は、前書きではマゼンタ、本文の事例では紫と書かれています。色は資料によって違うので、色そのものより、種類を分けて書くことを守ってください。このガイドのボードは、上の表の色で付箋の種類を分け、色だけに頼らないよう、種類をノードの先頭にも書きます。

時系列に並べる手順​

  1. 出来事を書き出す: 業務で起きる出来事を、過去形で書き出します。1 人しか知らない出来事も出します
  2. 時間の順に並べる: 左から右へ、起きる順に並べます。同じときに起きる出来事は縦に並べます
  3. 出来事を起こしたものを足す: Brandolini は、出来事を起こすものとして、人が起こすコマンド・外部システム・時間の経過・別の出来事の 4 つを挙げています。人が起こすならアクターとコマンドを、別の出来事から続くならポリシーを、あいだに置きます
  4. 判断に要る情報を足す: コマンドを起こす人が、決めるのに見る情報を、リードモデルとして横に置きます
  5. 分からないことを残す: 誰も答えられないこと、人によって答えが違うことを、ホットスポットとして貼ります。その場で決めずに残すのが大事です

1 周目のボード​

1 周目のボードは、サンプルリポジトリの docs/model/event-storming.md に Mermaid の図で置きました。

購入者は、商品の価格と在庫を見て、注文するかを決めます。リードモデルには、API で扱うかどうかに関わらず、業務の判断に使う情報を書きます (1 周目の API では、購入者は商品を探せません。前の章の「1 周目に入れないもの」)。注文すると、在庫が引き当てられ、注文が受け付けられます。受け付けられた注文は、内容と状態として購入者が確かめられます。注文するコマンドには、前の章の未決の問いがホットスポットとして付いています。

ボードの出来事は 2 つしかありません。1 周目は注文の作成と取得だけなので、出来事も少なくなります。後の周回で取り消しや決済を足すと、出来事とポリシーと外部システムが増えていきます。

2 つの出来事の名前​

出来事は、前の章のユースケースの主な流れから拾いました。手順 6 の「システムが、在庫を引き当て、注文を受付の状態で記録する」には、店にとって意味のある事実が 2 つ入っています。在庫が減ったことと、注文を受けたことです。

名前は、業務の語で付けます。

  • 「在庫の数が更新された」ではなく「在庫が引き当てられた」。注文のために在庫を差し引くことを、この題材では引き当てと呼びます。「更新された」は、システムがデータをどう変えたかを言うだけで、業務で何が起きたかを言いません
  • 「注文が保存された」「注文が作られた」ではなく「注文が受け付けられた」。店が購入の依頼を受けたという事実で、作られた直後の注文の状態の名前 (受付) とも合います

2 つは同じコマンドから同じときに起きるので、ボードでは縦に並べます。2 つの出来事が 1 つのまとまりとして一緒に起きなければならないのか、別々に起きてよいのかは、次の章でドメインモデルを考えるときに決めます。

在庫が足りないときや、入力に誤りがあるときは、注文するコマンドが断られ、出来事は起きません。断られる条件は、ユースケースの別の流れと受け入れ条件に書いてあるので、ボードには出来事として書いていません。

ホットスポットから要件へ戻る​

前の章の未決の問いは、「2 種類以上の商品を頼み、一部の商品だけ在庫が足りないとき、注文全体を断るか、足りる注文明細だけで受け付けるか」でした。ワークショップなら、ここで店の人に聞きます。このガイドでは、書き手が店の役を兼ねて、店の方針として次のように決め、決めたことと理由をボードと同じファイルに書きました。

## ホットスポットと決めたこと

| ホットスポット | 決めたこと | 理由 |
| --- | --- | --- |
| 2 種類以上の商品を頼み、一部の商品だけ在庫が足りないとき、注文全体を断るか、足りる注文明細だけで受け付けるか | 注文全体を断り、在庫が足りない商品を返す。どの商品の在庫も変えない | 購入者は商品をまとめて頼んでいて、一部だけを受け付けると購入者の意図と違いうる。一部だけを受け付けると、合計と消費税額が、購入者が見込んだ額から変わる。断られた購入者は、数量を変えて頼み直せる |

決めたことは、要件に戻して書いた (docs/requirements/use-cases.md の別の流れ 4a と、docs/requirements/stories.md の受け入れ条件「一部の商品の在庫が足りないと、注文全体が受け付けられない」)。

決めたことは、モデルの記録だけに残さず、要件の文書に戻します。ユースケースの別の流れ 4a から「決めていない」を消し、未決の問いの節を消しました。

### 別の流れ

- **2a** 注文明細が無い、数量が 1 より小さい、連絡先メールアドレスが無いか形が正しくない: システムは注文を記録せず、誤りのある項目を返す
- **3a** 登録されていない商品がある: システムは注文を記録せず、その商品を返す
- **4a** 在庫が数量より少ない商品がある: システムは注文を記録せず、どの商品の在庫も変えず、在庫が足りない商品を返す。一部の商品だけが足りないときも、注文全体を断る

決めたことを確かめられるように、受け入れ条件も足しました。前の章の「在庫より多い数量を頼むと、注文は受け付けられない」は商品が 1 種類だけで、どちらの方針でも結果が同じでした。違いが出るのは、在庫の足りる商品と足りない商品を一緒に頼んだときです。

### 受け入れ条件: 一部の商品の在庫が足りないと、注文全体が受け付けられない

- **Given** 受け入れ条件の前提の商品と在庫がある
- **When** 購入者が、りんごを 2 個と保存容器を 4 個、連絡先メールアドレス `taro.test@example.com` で注文する
- **Then** 注文は作られない
- **And** 在庫が足りない商品が保存容器だと分かる
- **And** 在庫は、りんごが 10、保存容器が 3 のまま

受け入れ条件のテスト (test/acceptance.test.ts) にも、同じ名前の it.todo を同じ位置に足しました。足し忘れると、前の章の test/requirements.test.ts が、文書とテストの並びの食い違いとして落とします。

ボードを作ると、要件に戻って直すことが出てきます。要件・モデル・仕様は 1 回で決まるものではなく、後の段で分かったことを前の段に戻して、両方をそろえていきます。

付箋の語から用語集を作る​

ボードと要件に出てきた語を集め、1 つずつ意味を決めて用語集にします。関わる人みんなが同じ意味で使う語の集まりを、ドメイン駆動設計ではユビキタス言語と呼びます (Laravel × DDD ガイドの戦略的設計の章のユビキタス言語の節)。この章の用語集は、注文の API のユビキタス言語を書き留めたものです。

用語集は、サンプルリポジトリの docs/glossary.yaml に置きました。語ごとに、文書で使う語 (name)、コードで使う名前 (code)、意味 (definition)、代わりに使わない語 (avoid) を書きます。

# 注文 API の用語集。要件・モデル・仕様・コードで、同じものを同じ語で呼ぶための一覧。
# name は文書で使う語、code はコードで使う名前 (決めたものだけ)、avoid はこの語の代わりに使わない語。
# avoid には、どの文脈でも使わない語だけを書く。文脈で使い分けること (注文明細の金額を「価格」と呼ばないなど) は definition に書く。
# test/glossary.test.ts が、docs/ の .md に avoid の語が無いことを、書いたとおりの文字の並びで探して確かめる (大文字小文字・全角半角はそろえない)。
# allowed には、avoid の語を含むが、別の意味の語として使ってよい語を書く (ユーザーストーリーの中のユーザーなど)。
allowed: [ユーザーストーリー, ユーザーエージェント]
terms:
- name: 注文
code: Order
definition: 1 回の購入の依頼。1 つ以上の注文明細を持つ。
- name: 注文明細
code: OrderLine
definition: 注文に含まれる 1 行。どの商品を、いくつ、いくらで買うかを持つ。
avoid: [OrderItem]
- name: 商品
code: Product
definition: 注文できる品物の 1 種類。
- name: 在庫
code: Inventory
definition: 商品ごとに持つ、注文に引き当てられる数量。
avoid: [Stock]
# ...
- name: 消費税額
code: taxAmount
definition: 注文の合計に含まれる消費税の額。税率ごとに、合計から割り戻して求める。
avoid: [税額, 外税]
- name: 引き当て
code: allocate
definition: 注文明細の数量を、その商品の在庫から差し引くこと。差し引かずに押さえておく別の仕組みと紛れるので、確保・予約・reserve とは呼ばない。
# ...
- name: 取り消し
code: cancel
definition: 注文を、購入の依頼として無効にすること。注文は消さずに、取消の状態で残る。
avoid: [キャンセル]

使わない語を書くのは、同じものに 2 つの呼び名があると、読む人が 2 つの別のものがあると受け取るからです。注文明細を OrderItem とも呼ぶと、OrderLine と OrderItem の違いを探すことになります。在庫と Stock、取り消しとキャンセルも同じです。取り消しは 1 周目では扱いませんが、よく使われる言い換えがあるので、先に語を決めておきます。

使わない語には、どの文脈でも使わない語だけを書きます。「価格」は商品の今の金額を指す語で、注文明細の金額は「単価」と呼びます。ここで「価格」を単価の使わない語にすると、商品の価格を書いた文まで誤りになってしまいます。引き当てを「確保」と呼ばない決まりも同じで、「整合性を確保する」のような別の意味の文まで誤りにしないよう、意味 (definition) の側に書きます。

使わない語を含んでいても、別の意味の語として使ってよい語があります。「ユーザー」は会員の呼び名としては使いませんが、前の章の「ユーザーストーリー」や HTTP の「ユーザーエージェント」は別の語です。こうした語は allowed に書きます。

用語集の語とコードの名前​

code は、コードの中で使う名前です。注文は Order、注文明細は OrderLine、在庫は Inventory のように、文書の語とコードの名前を 1 対 1 に対応させます。第 2 部でクラスとプロパティを書くときは、この名前を使います。

業務の語とコードの名前が対応していると、要件の文書の「引き当て」を読んだ人が、コードの allocate を探せます。逆に、コードで reserve と書くと、文書の語と結び付かなくなります。

code は、コードでの名前を決めた語にだけ書きます。購入者や会員のように、まだ決めていない語には書いていません。取り消しは後の周回で扱う語ですが、名前を先に決めたので cancel を書いています。JSON のキーの書き方 (unitPrice か unit_price か) は、表現の設計の章で決めます。

使わない語が無いことをテストで確かめる​

用語集を書いても、文書を書く人が使わない語を書いてしまえば、語はそろいません。そこで、サンプルリポジトリのテスト (test/glossary.test.ts) で、docs/ の下の Markdown の文書に、用語集の使わない語が出てこないことを確かめます。

このテストは、用語集を読み、docs/ の下の .md をすべて (下のディレクトリも) 読んで、使わない語を書いたとおりの文字の並びで探します (部分一致)。見つけたら、ファイルと、使わない語と、見るべき用語集の語を並べて落ちます。

探す前に、1 つ手間をかけています。「消費税額」の中には、使わない語の「税額」が入っています。そのまま探すと、正しく「消費税額」と書いた文で落ちてしまいます。そこで、使わない語ごとに、その語を含む用語集の語と allowed の語 (税額なら消費税額) を消してから探します。用語集の語をすべて消すわけではありません。すべて消すと、使わない語の「税込価格」の中の「価格」も消えて、「税込価格」と書いた文を見落とすからです。

探す前には、用語集の形も確かめます。avoid のキーを綴り違えたり、値を書き忘れたりすると、その語の確かめが黙って抜けてしまうからです。知らないキーがある、name や definition が無い、avoid が 1 つ以上の語の配列でない、のどれでも落ちます。あわせて、用語集の語が重なっていないこと、使わない語が 1 つ以上あること、使わない語がほかの語の名前になっていないことを確かめます。docs/ の下に .md が 1 つも見つからないときも落ちます。何も読まずに通ることを防ぐためです。

書いたとおりの文字で比べるので、大文字と小文字の違い (stock)、全角と半角の違い、送り仮名の違い (「引当」と「引き当て」) は捕まえません。大文字と小文字、全角と半角の違いまで捕まえたいときは、比べる前に文字をそろえる処理を足します。送り仮名の違いは、違う書き方を使わない語として用語集に足します。

要件の文書のどこかに「キャンセル」と書くと、このテストは落ちます。同じ確かめを、仕様の lintの章で、OpenAPI の仕様にも lint の規則として掛けます。コードは章末の「この章のテストのコード」にあります。

1 人で進めるやり方​

イベントストーミングは、業務を知る人と開発者が集まって行うワークショップです。このガイドのように 1 人で進めるときは、次のように進めています。

  • 要件を材料にする: ユースケースの主な流れと別の流れを手元に置き、手順ごとに、店にとって意味のある事実が起きているかを確かめます
  • 役を替えて読む: 購入者・店の人・在庫を扱う人の立場で、それぞれ何が起きたら困るかを考えます。1 人で書くと、自分の立場から見える出来事に偏るからです
  • 決められないことは残す: その場で答えを決めずに、ホットスポットとして残し、決める人に聞きます。決める人がいないときは、誰の役として決めるかをはっきりさせてから答えます。この章では、前の章で未決の問いとして残したものに、書き手が店の役を兼ねて答えました
  • 時間を区切る: 1 周目のボードのように、扱う範囲が決まっていれば、短い時間で並べられます。範囲の外の出来事は、後の周回のために書き留めるだけにします

記録の残し方​

ワークショップの壁は、終われば片付けます。決めたことが残るように、次のものを記録にします。

  • ボード: Mermaid の図としてリポジトリに置きます。テキストなので、後の周回で付箋を足したときに差分で追えます。紙やオンラインのボードを使ったときは、写真や書き出しを残し、図に書き直します
  • ホットスポットと決めたこと: 決めた内容と理由を一緒に書きます。理由が無いと、後で同じ問いが出たときに、決め直してよいのかが分かりません
  • 要件への反映: 決めたことは要件の文書に戻し、受け入れ条件を足します
  • 用語集: 新しい語や、使わないと決めた語を足し、テストが通ることを確かめます

実務で効く注意点​

出来事をシステムの動作で書かない​

「注文ボタンが押された」「注文データが登録された」のような付箋は、画面やデータベースの動作を書いています。画面が変われば消える出来事で、業務で何が起きたかを言っていません。業務の担当者が「それが起きたら困る」「それが起きたら次にこれをする」と言える事実を、業務の語で書きます。

ホットスポットをその場で決めない​

ワークショップの途中で答えの出ない問いに当たると、声の大きい人の答えで先へ進みがちです。その答えは記録に残らず、決めた理由も残りません。答えの出ない問いはホットスポットとして貼り、誰がいつまでに決めるかを書いて先へ進みます。

まとめ​

  • イベントストーミングは、業務で起きる出来事を過去形で付箋に書き、時間の流れに沿って並べるワークショップです
  • 付箋は、ドメインイベント・コマンド・アクター・リードモデル・ポリシー・外部システム・ホットスポットに分けます。色は資料で違うので、種類を分けることを守ります
  • 1 周目のボードの出来事は、「在庫が引き当てられた」と「注文が受け付けられた」の 2 つです。出来事の名前は、システムの動作でなく業務の語で付けます
  • ホットスポットで決めたことは、理由と一緒に記録し、要件の文書と受け入れ条件に戻します。この章では、一部の商品だけ在庫が足りないときに注文全体を断ると決めました
  • 付箋と要件の語を用語集にまとめ、コードの名前と使わない語を一緒に書きます。使わない語には、文脈によらず使わない語だけを書きます
  • docs/ の文書に使わない語が無いことを、テストで確かめます

次に読む​

前の章は 要件の整理 です。

次章 ドメインモデル では、この章のボードの語からエンティティ・値オブジェクト・集約を決めます。在庫の引き当てと注文の受け付けを、どのまとまりで一緒に変えるかも考えます。

練習問題​

ボードに「注文データが DB に登録された」という付箋があります。何がまずいでしょうか。どう書き直しますか

解答例

DB に登録されたことは、システムがデータをどう扱ったかで、業務で何が起きたかではありません。保存の仕組みを変えれば消える出来事で、店の人に見せても意味が伝わりません。また「データ」「登録」は用語集の語でもありません。

業務の語で、店にとって起きた事実を書きます。注文するコマンドの結果なら「注文が受け付けられた」です。もし「登録」と書いた人が、在庫を減らしたことも言いたかったのなら、「在庫が引き当てられた」を別の出来事として書き、2 つを縦に並べます。

この章のホットスポットで、店が「足りる注文明細だけで受け付ける」方針を選んだとします。要件とボードのどこが変わるでしょうか

解答例

要件では、ユースケースの別の流れ 4a が変わります。在庫が足りない注文明細を除いて注文を記録し、在庫が足りる商品だけを引き当て、除いた商品を購入者に知らせる流れになります。全部の商品が足りないときは、注文明細が 1 つも残らないので、注文は記録しません。

受け入れ条件の「一部の商品の在庫が足りないと、注文全体が受け付けられない」は、「一部の商品の在庫が足りないと、足りる商品だけで注文が受け付けられる」のような条件に変わります。Then には、次のことを値で書きます。

  • 注文明細がりんごだけになる
  • 合計と消費税額がりんごの分だけになる
  • りんごの在庫だけが減る
  • 除いた商品が保存容器だと分かる

ボードでは、在庫が足りない商品を除いたという事実を、店にとって意味のある出来事として足すかを考えます。購入者に知らせる必要があるなら、「注文明細が除かれた」のような出来事を置きます。また、合計が購入者の見込みと変わるので、購入者に確かめてから受け付けるのかという、新しいホットスポットも出てきます。

この章のテストのコード​

docs/ の文書に、用語集の使わない語が無いことを確かめるテストのコードです。読まなくても本文は追えます。

用語集のテスト (test/glossary.test.ts) です。

/*
* docs/ の文書に、用語集 (docs/glossary.yaml) の使わない語が無いことを確かめる。
* 同じものを別の語で書くと、読む人は別のものを指していると受け取るため。
*/
import { readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { expect, it } from 'vitest';
import { parse } from 'yaml';

interface Term {
name: string;
code?: string;
definition: string;
avoid?: string[];
}

interface Glossary {
allowed?: string[];
terms: Term[];
}

const docs = fileURLToPath(new URL('../docs/', import.meta.url));
const raw: unknown = parse(readFileSync(join(docs, 'glossary.yaml'), 'utf8'));

function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}

function isText(value: unknown): value is string {
return typeof value === 'string' && value !== '';
}

function isWords(value: unknown): value is string[] {
return Array.isArray(value) && value.length > 0 && value.every(isText);
}

/**
* 用語集の形の崩れを、見つけた順に文で返す。avoid のキーを綴り違えたり値を書き忘れたりすると、
* その語の確かめが黙って抜けるので、知らないキーと、空の avoid も崩れとみなす。
*/
function shapeProblems(value: unknown): string[] {
if (!isRecord(value)) return ['用語集が、キーと値の組でない'];
const problems = Object.keys(value)
.filter((key) => key !== 'allowed' && key !== 'terms')
.map((key) => `知らないキー: ${key}`);
if ('allowed' in value && !isWords(value.allowed)) problems.push('allowed が、1 つ以上の語の配列でない');
if (!Array.isArray(value.terms) || value.terms.length === 0) return [...problems, 'terms が、1 つ以上の項の配列でない'];
value.terms.forEach((term: unknown, index) => {
const where = `terms の ${index + 1} 番目`;
if (!isRecord(term)) {
problems.push(`${where} が、キーと値の組でない`);
return;
}
for (const key of Object.keys(term)) {
if (!['name', 'code', 'definition', 'avoid'].includes(key)) problems.push(`${where}: 知らないキー ${key}`);
}
if (!isText(term.name)) problems.push(`${where}: name が無い`);
if (!isText(term.definition)) problems.push(`${where}: definition が無い`);
if ('code' in term && !isText(term.code)) problems.push(`${where}: code が空`);
if ('avoid' in term && !isWords(term.avoid)) problems.push(`${where}: avoid が、1 つ以上の語の配列でない`);
});
return problems;
}

const problems = shapeProblems(raw);
const glossary: Glossary = problems.length === 0 ? (raw as Glossary) : { terms: [] };
const names = glossary.terms.map((term) => term.name);

/** docs/ の下の .md を、下のディレクトリまで含めて、docs/ からの相対パスで返す。 */
function markdownFiles(): string[] {
return readdirSync(docs, { recursive: true, encoding: 'utf8' })
.filter((file) => file.endsWith('.md'))
.sort();
}

/**
* 使わない語を探す前に、その語を含む用語集の語と allowed の語を消す。消さないと、「消費税額」の中の「税額」のように、
* 正しい語の一部を使わない語として見つける。消すのはその語を含む語だけにする。用語集の語をすべて消すと、
* 「税込価格」の中の「価格」も消えて、使わない語を見落とす。
*/
function containsAvoided(text: string, word: string): boolean {
const masked = [...names, ...(glossary.allowed ?? [])]
.filter((other) => other !== word && other.includes(word))
.reduce((rest, other) => rest.replaceAll(other, '\n'), text);
return masked.includes(word);
}

it('用語集の形が崩れておらず、語が重ならず、使わない語がほかの語の名前になっていない', () => {
expect(problems).toEqual([]);
expect(new Set(names).size).toBe(names.length);
const avoided = glossary.terms.flatMap((term) => term.avoid ?? []);
expect(avoided.length).toBeGreaterThan(0);
expect(avoided.filter((word) => names.includes(word))).toEqual([]);
});

it('docs/ の文書に、用語集の使わない語が無い', () => {
const files = markdownFiles();
expect(files.length).toBeGreaterThan(0);
const found: string[] = [];
for (const file of files) {
const text = readFileSync(join(docs, file), 'utf8');
for (const term of glossary.terms) {
for (const word of term.avoid ?? []) {
if (containsAvoided(text, word)) found.push(`${file}: ${word} (用語集の ${term.name} を見る)`);
}
}
}
expect(found).toEqual([]);
});