リソースの設計: 集約とコマンドから URL とメソッドを決める
ドメインモデルの章で、注文・在庫・商品の 3 つの集約を決めました。REST の考え方の章では、このガイドの API を、リソースを URL で識別し、メソッドとステータスコードを HTTP の意味どおりに使う形で作ると決めました。この章では、その 2 つをつないで、1 周目の API の URL とメソッドを決めます。
決めたものは、サンプルリポジトリの docs/api-design/ に置きました。endpoints.md がエンドポイントの一覧と決めた理由を、operations.yaml がユースケースから操作の名前までの対応表を持ちます。
集約とコマンドからリソースを見つける
リソースの候補は、前の章までに作った 3 つの記録から拾います。
| 記録 | 1 周目にあるもの | リソースとの関係 |
|---|---|---|
| ドメインモデルの集約 | 注文・在庫・商品 | リソースの候補。集約ルートを URL で指せるようにするかを決める |
| イベントストーミングのボードのコマンド | 注文する | リソースに対する操作になる。どのリソースに、どのメソッドで送るかを決める |
| ボードのリードモデル | 商品の価格と在庫、注文の内容と状態 | 読む操作の候補になる。API で読ませるかと、どのリソースを GET で読むかを決める |
Google の API の設計の指針 (AIP) は、API を設計するときに考えることを、おおむねリソース (名詞)・リソースの間の関係と階層・各リソースのスキーマ・各リソースのメソッド (動詞) の順に並べています (AIP-121)。AIP は Google の中で生まれ、Google の API を書く人に向けたものですが、多くは Google の外でも役に立つとしています (Adopting AIPs)。AIP-121 は、リソース指向設計を RPC の API を定めるための型と呼び、REST から多くの原則を借りつつ、適切な場面では独自の型も定めると書いています。この章では、リソースから考える順だけを借ります。
1 周目のユースケースは、注文すると注文を確かめるの 2 つです。どちらも注文を対象にしています。そこで、1 周目にリソースとして出すのは注文だけにしました。
- 注文: 注文するコマンドで作り、注文を確かめるで読む。リソースにする
- 在庫: 注文するときにサーバーの中で引き当てるだけで、購入者が直接読んだり変えたりする操作は 1 周目に無い。リソースにしない
- 商品: 注文明細の中で商品 ID で指す。商品を探したり読んだりする操作は 1 周目に無い。商品の API は 2 周目で足す
商品の API を 2 周目に回すので、1 周目の購入者は、注文する商品の商品 ID を API の外から知っていることになります。ユースケースの事前条件は、商品と在庫が登録されていることだけを書いていて、この前提は書いていません。1 周目はこれを仮定として置きます。商品の一覧と、その続きのリンクは、第 4 部で扱います。
API のモデルは集約の写しではない
AIP-121 によれば、API の設計者は、API がデータベースのスキーマを写したものになると考えるべきではありません (SHOULD NOT)。スキーマと同じ形の API はアンチパターンで、API の表面を下の仕組みに強く結び付けるからです (AIP-121)。
このガイドは、同じ考え方をドメインモデルにも当てます。集約は、不変条件を守る範囲として決めたもので、利用者が読み書きする単位として決めたものではありません。在庫は集約ですが、1 周目の API には出しません。注文の表現に何を入れるか (合計や消費税額を入れるか、どんな名前で入れるか) も、集約のフィールドの写しとしてではなく、利用者が使う形として次の章で決めます。
コレクションと個々のリソース
AIP-121 は、リソース指向の API を、一般にリソースの階層としてモデル化するよう求めています (SHOULD)。階層の各点は、1 つのリソースか、同じ型のリソースのコレクションです (AIP-121)。
注文の API は、注文のコレクションと、その中の 1 件の注文の 2 つのリソースを持ちます。
## リソース
| リソース | パス | 表すもの |
| --- | --- | --- |
| 注文のコレクション | `/orders` | 受け付けた注文の集まり。注文を作るときの送り先 |
| 注文 | `/orders/{orderId}` | 1 件の注文。`{orderId}` は注文 ID |
- 注文明細は、注文の表現に含める。注文明細だけを指す URL は作らない
- 商品は、注文明細の中で商品 ID で指す。商品の表現は埋め込まない
- 商品と在庫は、1 周目の API にリソースとして出さない。商品の API は 2 周目で足す
{orderId} は、パスのその位置に注文 ID が入ることを表します。注文 ID が abc の注文の URL は /orders/abc です。
注文明細と商品の扱いは、この章の後半で、ほかの案と比べて理由を書きます。
URL の命名
URL の名前は、利用者が一度使い始めると変えにくい約束です。決まりを先に書き、1 周目のどのリソースにも同じ決まりを当てます。
## 名前の決まり
1 周目の 2 つの操作に当てた決まり。標準のメソッドで表せない操作の形と、API の版の表し方は、後の周回で比べて決める。
- パスのセグメントは、小文字の英語にする。2 語以上なら `-` でつなぐ
- コレクションは複数形にする (`orders`)
- パスの変数の名前は、用語集の code にする (`orderId`)
- 標準のメソッドで表せる操作では、パスに動詞を入れない。何をするかはメソッドで表す
- 基底のパス (`/api` など) は付けない。1 周目は、API の版をパスに入れない
この決まりを、3 つの公開されている指針と比べました。どれも、ほかの組織に向けた規則で、このガイドの API を縛るものではありません。共通する考え方を確かめるために読みます。
| 決まり | Google の AIP | Zalando の指針 | Azure の指針 |
|---|---|---|---|
| コレクションを複数形にする | コレクションの識別子は複数形の名詞でなければならない (MUST) | リソース名を複数形にしなければならない (MUST) | コレクションの名前は略さず複数形にする (DO) |
| 区切りと大文字小文字 | コレクションの識別子は小文字で始まる camelCase (MUST) | パスのセグメントは kebab-case (MUST) | kebab-case (推奨) か camelCase (DO)。セグメントが JSON のフィールドを指すときは camelCase |
| 動詞を入れない | 標準メソッドを優先し (SHOULD)、カスタムメソッドはコロンと動詞で表す | URL に動詞を入れない (MUST) | 標準の操作で表せるならアクションを使わない (DO NOT) |
Zalando の指針は、Zalando の API Guild が書いて持つ、同社の API のための規則です (Zalando RESTful API Guidelines)。Azure の指針は、data plane の API を作る Azure のサービスチームが従う規範です (Azure REST API Guidelines)。AIP の表の行は、AIP-122 (コレクションの識別子) と、AIP-121 (メソッド)・AIP-136 (カスタムメソッド) から引いています。
複数形は 3 つとも同じ向きでした。標準のメソッドで表せる操作に動詞を使わないことも、3 つとも同じ向きです。このガイドで標準のメソッドと呼ぶのは、AIP-121 の標準メソッド (取得・一覧・作成・更新・削除) です (AIP-121)。ただし、標準のメソッドで表せない操作には、AIP と Azure の指針は URL の中に動詞を書く形を定めています。区切りは分かれます。このガイドの 1 周目のパスは orders の 1 語なので、どちらを選んでも同じ URL になります。2 語以上のセグメントが出てきたときに迷わないよう、Zalando の決まり (MUST) と Azure の推奨に合わせて - でつなぐと決めました。
パスの変数の名前 (orderId) には、用語集の code を使います。Zalando の指針の kebab-case の規則は、パスの変数の名前には必ずしも当てないとしているので (規則 129)、この決め方とは食い違いません。
基底のパスには /api を付けません。Zalando の指針は、基底のパスに /api を使うべきでない (SHOULD NOT) とし、基底のパスをデプロイの種類ごとの設定の一部に数えています (規則 135)。REST の考え方で読んだとおり、URL の構造はサーバーの持ち主が決めるものです。API の版をパスに入れるかどうかは、第 7 部で方式を比べて決めます。1 周目のパスには版を入れません。
コマンドをメソッドに写す
注文するコマンドは、注文のコレクション /orders への POST に写します。
HTTP の仕様は、POST の用途の 1 つに、オリジンサーバーがまだ識別子を与えていない新しいリソースを作ることを挙げています。POST で 1 つ以上のリソースを作ったら、作った主なリソースを指す Location を付けて 201 を返すべき (SHOULD) としています (RFC 9110 の 9.3.3)。メソッドとステータスコードの章で、商品のサーバーが返した形 (201 と Location) です。
AIP-133 も、コレクションに新しいリソースを作る Create のメソッドについて、HTTP のメソッドを POST にしなければならず (MUST)、リソースを足すコレクションを URI のパスに対応させるよう求めています (SHOULD。AIP-133)。
一方で、Azure の指針は、リソースの作成に PUT か PATCH を使うよう勧めています (YOU SHOULD)。実装が易しく、利用者がリソースに名前を付けられ、冪等だからです。POST で作ってもよい (YOU MAY) としつつ、その場合は冪等にし、作ったリソースの URL を 201 とともに返すよう求めています (PUT か PATCH で作る・POST は冪等にする)。
このガイドは POST を選びました。注文 ID は、購入者でなくサーバーが決めるからです。購入者が注文に自分で名前を付ける必要は無く、注文 ID の形と一意さはサーバーが保ちます (注文 ID の形は次の章で決めます)。HTTP の仕様も、状態を変えるリクエストを受けてサーバーがクライアントに代わって URL を選ぶなら、PUT でなく POST で実装すべき (SHOULD) としています (RFC 9110 の 9.3.4)。
POST は冪等ではありません。応答が届かずに購入者が送り直すと、注文が 2 つできるおそれがあります。送り直しても注文が 1 つで済む仕組み (冪等性キー) は、第 4 部で扱います。1 周目の API は、この問題をまだ解いていません。
注文の取得
注文を確かめるユースケースは、注文 /orders/{orderId} への GET に写します。注文があれば 200 と注文の表現を返し、その注文 ID の注文が無ければ 404 を返します。HTTP の仕様は、404 を、オリジンサーバーが対象リソースの今の表現を見つけられなかったか、それがあることを明かすつもりが無いことを示すコードとしています (RFC 9110 の 15.5.5)。
AIP-131 も、1 つのリソースを取る Get のメソッドを GET にしなければならない (MUST) としています (AIP-131)。リソースが無いときのコードは AIP-131 自身では決めず、エラーの指針 (AIP-193) に任せています。
注文するコマンドの失敗 (入力の誤り・登録されていない商品・在庫が足りない) のステータスコードと本文の形は、エラーの設計の章で決めます。この章では、成功したときと、注文が無いときの 404 だけを決めます。
エンドポイントの一覧
ここまでの 2 つの操作を、エンドポイントの一覧にまとめました。
## 一覧
| メソッドとパス | 操作の名前 | 成功したとき | 失敗したとき |
| --- | --- | --- | --- |
| `POST /orders` | `placeOrder` | 201。`Location` に作った注文の URL (`/orders/{orderId}`)、本文に注文の表現 | 入力の誤り・登録されていない商品・在庫が足りない。ステータスコードと本文の形は、エラーの設計で決める |
| `GET /orders/{orderId}` | `getOrder` | 200。本文に注文の表現 | その注文 ID の注文が無いと 404 |
注文明細を含めるか、サブリソースにするか
注文明細は、注文の表現の中に並べて返します。/orders/{orderId}/lines/{lineId} のように、注文明細を 1 つずつ指す URL (サブリソース) は作りません。
Zalando の指針は、サブリソースを、そのライフサイクルが主なリソースに (緩く) 結び付いていて、主なリソースがサブリソースのコレクションとして働くときに使うとしています (規則 147)。入れ子にするかどうかは検討してよい (MAY) という書き方です (規則 145)。同じ指針の埋め込みの規則の例は、注文明細を /order/{orderId}/items というサブリソースにしています (規則 158)。この形も選べました。
サブリソースにしなかった理由は、1 周目の注文明細にあります。
- 注文明細を 1 つずつ読む操作も、変える操作も、1 周目には無い
- 注文明細は注文と一緒に作り、作った後に変えない。ドメインモデルでも値オブジェクトにした
- 注文を確かめる購入者は、注文明細をすべて見たい。分けると、もう 1 回のリクエストが要る
注文明細を 1 つずつ変える操作は、注文を変える後の周回で出てきます。そのときに、サブリソースにするかを見直します。
AIP-144 は、配列のフィールドに、1 つのリソースの中身が大きくなりすぎない上限を設けるよう勧め (SHOULD、目安は 100 要素)、大きくなりすぎるおそれがあればサブリソースにするよう勧めています (AIP-144)。注文明細の数に上限を設けるかは、次の章で表現を決めるときに一緒に決めます。
商品を埋め込むか、ID で指すか
注文明細は、商品を商品 ID で指します。商品の表現 (商品名や今の価格) は、注文明細の中に埋め込みません。
AIP-122 は、フィールドが別のリソースを表すときは、相手のリソース名 (publishers/123 のように、コレクションと ID を並べた名前) を持つ文字列にし (SHOULD)、相手のリソースの本体をそのまま入れないよう求めています (SHOULD NOT。AIP-122)。リソース名を使えず ID だけが要る場合は、フィールド名に _id を付けるとしています (SHOULD)。本体を入れないことには例外を 2 つ挙げています。理由の説明としては、依存先が消えたときの扱いや権限の迂回を挙げ、名前で指せばデータの重複も防げるとしています。一方で、Zalando の指針は、クライアントが求めたときに関連するリソースを埋め込めるようにするよう勧めています (SHOULD。規則 158)。リクエストの数を減らせるからです。
このガイドが 1 周目に ID だけで指すと決めた理由は 2 つです。
- 注文明細は、注文した時点の商品の価格と税率を、単価と税率として写して持つ (ドメインモデル)。商品の今の表現を埋め込むと、注文した時点の値と今の値が同じ注文の中に並び、どちらで計算したかが読み取りにくくなる
- 1 周目には商品の API が無い。商品の URL が無いので、リンクで指す先も無い
Zalando の指針は、表現の中で別のリソースへのリンクを入れるなら、少なくとも href を持つ共通の形を使わなければならないとしています (MUST。規則 164)。商品の API を足す 2 周目に、商品 ID のほかにリンクも入れるかを決めます。
ユースケースから操作までの対応表
ここまでで決めたことを、ユースケースから操作の名前まで 1 行でたどれる表にしました。
# ユースケースから API の操作までの対応表。
# useCase は docs/requirements/use-cases.md の「ユースケース:」の見出し、command と readModel は docs/model/event-storming.md のボードの付箋、
# aggregateMethod は docs/model/domain-model.md のクラス図のメソッド、method と path と operationId は docs/api-design/endpoints.md の一覧にそろえる。
# operationId は、API の仕様で操作の名前に使う。
# 状態を変えるユースケースは command と aggregateMethod を持ち、読むだけのユースケースは readModel を持つ。
# aggregateMethod には、コマンドを受ける集約のメソッドを 1 つ書く (同じコマンドで変わるほかの集約のメソッドは書かない)。
# 1 周目は、1 つのユースケースを 1 つの操作に写す。
# test/operations.test.ts が、この表と上の文書が食い違わないことを確かめる。アプリは実行時にこのファイルを読まない。
operations:
- useCase: 注文する
command: 注文する
aggregateMethod: Order.place
method: POST
path: /orders
operationId: placeOrder
- useCase: 注文を確かめる
readModel: 注文の内容と状態
method: GET
path: /orders/{orderId}
operationId: getOrder
operationId は操作の名前で、この部の後半で書く OpenAPI の仕様に同じ名前で入れます。aggregateMethod の Order.place は、コマンドを受ける集約のメソッドで、注文を受付の状態で作ります。同じコマンドで在庫の引き当て (Inventory.allocate) も行いますが、表にはコマンドを受けるメソッドだけを書きます。
この章では、ドメインモデルも 3 か所直しました。クラス図の Order に place(contactEmail, lines)$ を足しました。末尾の $ は、インスタンスでなくクラスに属するメソッド (static) を表す Mermaid の記法です (Mermaid のクラス図)。place は、注文のインスタンスができる前に呼んで注文を作るので、クラスに属するメソッドにしました。作るときの決まりの行に Order.place を書き、境界づけられたコンテキストの表の「1 周目に使う語」を、用語集とクラス図にそろえました。用語集には「注文する」(code は place) を足しました。
操作の名前を placeOrder にしたのは、ユースケースとコマンドの名前 (注文する) を英語にした形だからです。データを作るという意味の名前 (createOrder) でなく、業務の操作の名前を、そのまま操作の名前に写しました。
この表は、文書と仕様と実装をつなぐ基準になります。表は文書の語と名前を写したものなので、片方だけを直すと食い違います。この章で足したテスト (test/operations.test.ts) は、次のことを確かめます。
- 表の形 (キーの綴り、メソッドの種類、パスの形、操作の名前が lowerCamelCase)
- ユースケースの文書のユースケースが、表にちょうど 1 回ずつ現れる
- ボードのコマンドが表にすべて現れ、表のリードモデルがボードにある
- 集約のメソッドが、ドメインモデルのクラス図のそのクラスにある
- パスの変数の名前が、用語集の code にある
- 操作の名前も、メソッドとパスの組も、表の中で重ならない
- エンドポイントの一覧と表が、同じ操作を同じメソッドとパスで持つ
ユースケースを足したのに表に行を足し忘れると、2 つ目のテストで落ちます。コードは章末の「この章のテストのコード」にあります。
この表は、後の章でも照らし合わせの基準に使います。この部の後半で OpenAPI の仕様を書いたら、仕様の操作の名前 (operationId) が表と一致することを、テストで確かめます。第 2 部で実装するときは、実装のメソッドが表の操作に対応していることも、テストで確かめます。どれもテストが表を読むだけで、アプリは実行時にこの表を読みません。
テストが文書から行を拾う書き方には限りがあります。ユースケースの見出し (## ユースケース: )、ボードの付箋 ("コマンド<br/>…")、一覧の行 (| `POST /orders` | `placeOrder` |) を、書いた形のまま正規表現で拾います。見出しのコロンを全角で書いたり、付箋の <br/> を <br> と書いたりすると、その行は数えられません。
見直しの観点
URL とメソッドを決めたら、次の観点で見直します。
- どのユースケースも、操作に写せているか (対応表に行があるか)。1 周目は、1 つのユースケースを 1 つの操作に写した
- 標準のメソッドで表せる操作のパスに、動詞が入っていないか。何をするかがメソッドで表せているか
- コレクションは複数形か。パスの変数は用語集の code か
- 新しいリソースの URL をサーバーが決める作成に、POST を使っているか。成功したときに 201 と
Locationを返すか - リソースの階層は浅いか。Zalando の指針は、入れ子を 3 段以下にするよう勧めています (SHOULD。規則 147)
- 集約やテーブルの形を、そのまま API に写していないか
選ばなかった案
ここまでで比べた案を、サンプルリポジトリにも残しました。
## 選ばなかった案
| 案 | 選ばなかった理由 |
| --- | --- |
| `POST /orders/place` のように、動詞をパスに入れる | 何をするかはメソッドで表し、パスは操作の対象を表す |
| `PUT /orders/{orderId}` で、クライアントが決めた注文 ID で作る | 注文 ID はサーバーが決める。新しいリソースの URL をサーバーが選ぶなら、PUT でなく POST を使う |
| 注文明細をサブリソース (`/orders/{orderId}/lines/{lineId}`) にする | 1 周目には注文明細を 1 つずつ扱う操作が無い。注文明細は注文と一緒に作り、作った後に変えない |
| 商品の表現を注文明細の中に埋め込む | 注文明細は、注文した時点の価格と税率を、単価と税率として写して持つ。商品の今の表現を埋め込むと、写した値と今の値が並ぶ |
動詞をパスに入れる形のうち、AIP-136 のカスタムメソッドと Azure の指針のアクション (どちらも /orders/{orderId}:cancel のように、コロンの後に動詞を書く形) は、標準のメソッドで表せない操作のための形です。1 周目の 2 つの操作は、どちらも POST と GET で表せました。作った注文の状態を移す操作 (取り消しなど) の URL は、第 4 部で、カスタムメソッドを含む案と比べて決めます。
実務で効く注意点
動詞を入れたくなったら、リソースにできないかを考える
Zalando の指針は、動作を避けてリソースで考えるよう求め (MUST)、記事を 1 人だけが編集できるようにロックする例で、lock の動作の代わりにロックをリソースにして PUT /article-locks/{article-id} を送る形を挙げています (規則 138)。ロックの一覧も、そのまま手に入ります。動詞を URL に入れたくなったら、その操作の結果として生まれるもの (ロック・予約・取り消し) を名詞にできないかを先に考えます。
リソースの種類を増やしすぎない
Zalando の指針は、1 つの API のリソースの種類の数を限るよう勧め (SHOULD)、同社の経験では、よく定義された API の種類は 4〜8 を超えないとしています。より多くのリソースが要る複雑な業務の領域の例外はありうるとしたうえで、まず別々の API を持つ下位の領域に分けられないかを確かめるべきとしています (規則 146)。ここでの種類は、コレクション・その要素・直接のサブリソースのような、密接に関連するリソースの集まりです。種類が増えてきたら、別々の API に分けられないかを考えます。
まとめ
- リソースの候補は、集約・コマンド・リードモデルから拾います。1 周目にリソースとして出すのは注文だけで、在庫と商品は出しません
- API は集約の写しではありません。利用者が使う単位で、リソースと表現を決めます
- 注文の API は、注文のコレクション
/ordersと注文/orders/{orderId}を持ちます。コレクションは複数形、標準のメソッドで表せる操作のパスに動詞を入れず、パスの変数は用語集の code です - 注文するコマンドは
POST /ordersに写し、成功したら 201 とLocationを返します。注文 ID をサーバーが決めるので、PUT でなく POST です - 注文を確かめるは
GET /orders/{orderId}に写し、無い注文には 404 を返します - 注文明細は注文の表現に含め、商品は商品 ID で指します
- ユースケースから操作の名前までの対応表を YAML で置き、文書と食い違わないことをテストで確かめます
次に読む
前の章は REST の考え方 です。
次章 表現の設計 では、注文の表現の JSON の形 (キーの名前・ID・金額・日時・状態) を決めます。
練習問題
購入者が、自分の注文の一覧を見たいと言いました。どんな URL とメソッドにするか、ユースケースから操作の名前までの対応表の 1 行として考えてください
解答例
案の 1 つは、注文のコレクション /orders への GET です。ユースケースは「注文の一覧を見る」、読むだけなのでリードモデル (注文の一覧) を持ち、操作の名前は listOrders のような形になります。
ただし、1 周目の API には、誰の注文かを見分ける仕組み (会員と認証) がありません。今のまま GET /orders を足すと、すべての購入者の注文が返ってしまいます。自分の注文の一覧をどの URL に置くか (注文のコレクションを絞るか、会員のリソースの下に置くか) は、会員の概念と認証が入る第 5 部で、管理者がすべての注文を見る操作と一緒に決めます。どの形にしても、ユースケースとボードにリードモデルを足し、対応表に行を足すと、テストがエンドポイントの一覧にも行を足すよう求めます。
注文の数量を後から変えたいという要件が出てきました。注文明細をサブリソースにする案を、もう一度考えるべきでしょうか
解答例
考えるべきです。この章で注文明細を表現に含めた理由のうち、「注文明細を 1 つずつ変える操作が無い」と「作った後に変えない」が成り立たなくなります。
数量を変える操作を、注文明細のサブリソース (/orders/{orderId}/lines/{lineId}) への PATCH にするか、注文全体への PATCH にするかを比べます。注文明細を 1 つずつ指すなら、注文明細に ID が要り、ドメインモデルでは値オブジェクトからエンティティに変わります。在庫の引き当ても、数量の差の分だけやり直すことになります。
この章のテストのコード
ユースケースから操作までの対応表が、要件・モデル・エンドポイントの文書と食い違わないことを確かめるテストのコードです。読まなくても本文は追えます。
/*
* ユースケースから API の操作までの対応表 (docs/api-design/operations.yaml) が、要件・モデル・エンドポイントの文書と
* 食い違わないことを確かめる。表は文書の語と名前を写したものなので、片方だけを直すと、別のものを指すようになるため。
*/
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { expect, it } from 'vitest';
import { parse } from 'yaml';
interface Operation {
useCase: string;
command?: string;
aggregateMethod?: string;
readModel?: string;
method: string;
path: string;
operationId: string;
}
function read(path: string): string {
return readFileSync(fileURLToPath(new URL(`../${path}`, import.meta.url)), 'utf8');
}
const raw: unknown = parse(read('docs/api-design/operations.yaml'));
const useCases = read('docs/requirements/use-cases.md');
const board = read('docs/model/event-storming.md');
const model = read('docs/model/domain-model.md');
const endpoints = read('docs/api-design/endpoints.md');
const glossary: unknown = parse(read('docs/glossary.yaml'));
const methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
const writeKeys = 'aggregateMethod,command,method,operationId,path,useCase';
const readKeys = 'method,operationId,path,readModel,useCase';
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 !== '';
}
/** /orders/{orderId} のように、小文字の英語のセグメントか {lowerCamelCase の変数} を / でつないだパスか。 */
function isPath(value: unknown): boolean {
return isText(value) && /^(\/([a-z][a-z0-9-]*|\{[a-z][a-zA-Z0-9]*\}))+$/.test(value);
}
/**
* 対応表の形の崩れを、見つけた順に文で返す。キーを綴り違えると、その項目の照合が黙って抜けるので、知らないキーも崩れとみなす。
* 状態を変える行は command と aggregateMethod を、読むだけの行は readModel を持つ。
*/
function shapeProblems(value: unknown): string[] {
if (!isRecord(value) || Object.keys(value).join() !== 'operations') return ['最上位のキーが operations の 1 つでない'];
if (!Array.isArray(value.operations) || value.operations.length === 0) return ['operations が、1 つ以上の操作の配列でない'];
const problems: string[] = [];
value.operations.forEach((entry: unknown, index) => {
const where = `operations の ${index + 1} 番目`;
if (!isRecord(entry)) {
problems.push(`${where}: キーと値の組でない`);
return;
}
const keys = Object.keys(entry).sort().join();
if (keys !== writeKeys && keys !== readKeys) {
problems.push(`${where}: キーが、状態を変える行 (${writeKeys}) か読むだけの行 (${readKeys}) の組でない`);
return;
}
for (const [key, field] of Object.entries(entry)) {
if (!isText(field)) problems.push(`${where}: ${key} が空でない文字列でない`);
}
if (!methods.includes(entry.method as string)) problems.push(`${where}: method が ${methods.join('・')} のどれでもない`);
if (!isPath(entry.path)) problems.push(`${where}: path が /orders/{orderId} のような形でない`);
if (!isText(entry.operationId) || !/^[a-z][a-zA-Z0-9]*$/.test(entry.operationId)) {
problems.push(`${where}: operationId が lowerCamelCase でない`);
}
if (keys === writeKeys && (!isText(entry.aggregateMethod) || !/^[A-Z][a-zA-Z0-9]*\.[a-z][a-zA-Z0-9]*$/.test(entry.aggregateMethod))) {
problems.push(`${where}: aggregateMethod が Order.place のような クラス名.メソッド名 の形でない`);
}
});
return problems;
}
const problems = shapeProblems(raw);
const operations: Operation[] = problems.length === 0 ? (raw as { operations: Operation[] }).operations : [];
/** 文書やパスの文字列から、正規表現の 1 つ目の組に当たる文字列を、書いた順に返す。 */
function captures(text: string, pattern: RegExp): string[] {
return [...text.matchAll(pattern)].map((match) => match[1]);
}
/**
* ドメインモデルのクラス図で、クラス name の中括弧の中にある行を返す。クラスが無ければ空。
* .gitattributes で改行を LF にそろえているが、エディタが CRLF で保存した作業ツリーでも読めるよう、行の終わりの \r を許す。
* name と、呼び出し側でメソッドを探す正規表現に埋める methodName は、aggregateMethod の形の確かめ (クラス名.メソッド名) を
* 通った英数字だけなので、正規表現の特別な文字は入らない。
*/
function classMembers(name: string): string[] {
const block = new RegExp(`^\\s*class ${name} \\{\\r?\\n([\\s\\S]*?)^\\s*\\}`, 'm').exec(model);
return block === null ? [] : block[1].split('\n').map((line) => line.trim());
}
it('対応表の形が崩れていない', () => {
expect(problems).toEqual([]);
});
it('ユースケースの文書のユースケースが、対応表にちょうど 1 回ずつ現れる', () => {
const documented = captures(useCases, /^## ユースケース: (.+)$/gm);
expect(documented.length).toBeGreaterThan(0);
expect(operations.map((operation) => operation.useCase).sort()).toEqual([...documented].sort());
});
it('ボードのコマンドが対応表にすべて現れ、対応表の読むものはボードのリードモデルにある', () => {
const commands = captures(board, /"コマンド<br\/>([^"]+)"/g);
const readModels = captures(board, /"リードモデル<br\/>([^"]+)"/g);
expect(commands.length).toBeGreaterThan(0);
expect(operations.flatMap((operation) => operation.command ?? []).sort()).toEqual([...commands].sort());
for (const operation of operations) {
if (operation.readModel !== undefined) expect(readModels).toContain(operation.readModel);
}
});
it('集約のメソッドが、ドメインモデルのクラス図のクラスにある', () => {
for (const operation of operations) {
if (operation.aggregateMethod === undefined) continue;
const [className, methodName] = operation.aggregateMethod.split('.');
expect(classMembers(className), operation.aggregateMethod).toContainEqual(expect.stringMatching(new RegExp(`^${methodName}\\(`)));
}
});
it('パスの変数の名前が、用語集の code にある', () => {
const terms = isRecord(glossary) && Array.isArray(glossary.terms) ? glossary.terms : [];
const codes = terms.flatMap((term: unknown) => (isRecord(term) && isText(term.code) ? [term.code] : []));
for (const operation of operations) {
for (const variable of captures(operation.path, /\{([^}]+)\}/g)) expect(codes, operation.path).toContain(variable);
}
});
it('操作の名前も、メソッドとパスの組も、対応表の中で重ならない', () => {
const ids = operations.map((operation) => operation.operationId);
const routes = operations.map((operation) => `${operation.method} ${operation.path}`);
expect(new Set(ids).size).toBe(ids.length);
expect(new Set(routes).size).toBe(routes.length);
});
it('エンドポイントの一覧と対応表が、同じ操作を同じメソッドとパスで持つ', () => {
const listed = [...endpoints.matchAll(/^\| `([A-Z]+ \/[^`]*)` \| `([^`]+)` \|/gm)].map((match) => `${match[1]} ${match[2]}`);
expect(listed.length).toBeGreaterThan(0);
const table = operations.map((operation) => `${operation.method} ${operation.path} ${operation.operationId}`);
expect(table.sort()).toEqual(listed.sort());
});