ADRの親が贈るAction Domain Responder(ADR)を実装する際の注意点の和訳

# はじめに

Paul M. JonesさんはADRの親です

> Action-domain-responder（ADR）は、Webアプリケーションにより適したModel-view-controller（MVC）の改良版としてPaul M. Jonesによって提案されたソフトウェアアーキテクチャパターンです.

ソース: https://en.wikipedia.org/wiki/Action%E2%80%93domain%E2%80%93responder

この記事は[Paul M. Jonesさんが掲載しているADRを実装する際の注意書き](https://github.com/pmjones/adr/blob/master/IMPLEMENTATION.md)を[DeepL](https://www.deepl.com/ja/translator)をベースに和訳したものです. (意訳と補足を含みます


## 実装上の注意点

_Action Domain Responder_ は、ユーザーインターフェースのパターンです。それ自体がアプリケーション・アーキテクチャ全体ではありません。このセクションでは、アプリケーション・アーキテクチャの中でADRと一緒に使われる可能性のある他のコンポーネント、コラボレーション、パターンについて説明し、ADRの実装者からの注意事項や提案を示します。

## Action

_Action_ の役割は意図的に非常に限定されています。_Action_は、HTTP リクエストからの入力を収集し、その入力をドメインに渡した後、コントロールを_Responder_に渡すだけです。ビジネスロジックは_Domain_でのみ扱い、プレゼンテーションロジックは_Responder_でのみ扱う必要があります。

_Action_ にif/thenブロック、try/catchブロック、ループなどが含まれている場合は、_Action_の処理が多すぎると言えます。唯一の例外は、HTTPリクエストにデフォルト値がない場合に、アクションがユーザーの入力に対してデフォルト値を提供することです。これはif/thenブロックではなく、三項演算子で簡単に処理できます。

### 補足

> if/thenブロックではなく、三項演算子で簡単に処理できます。

三項演算子はあくまでも手段の1つです。
例えばjsだと三項演算子以外だと、`a || b`や`a && b`や[論理和代入](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Operators/Logical_OR_assignment)等他にもこの目的を達成する為の沢山の手段があります.

### _Action_はどのようにしてHTTPリクエストを受け取るべきか?

HTTP リクエストは、_Action_のコンストラクタに注入することもできますし、_Action_ロジックを呼び出すメソッドの引数として渡すこともできます。それぞれの方法で HTTP リクエストを渡すことができますが、それぞれにトレードオフがあります。

### _Action_が入力を検証すべきか？

**ユーザー・インターフェース**コンポーネントは、**ドメイン・ロジック**の入力検証を行うべきではありません。

ユーザーの入力を _Domain_ に渡し、ドメインロジックで検証を行うようにするのがよいでしょう。_Domain_は、入力が無効な場合、ドメイン固有のメッセージを表示して報告します。

### _Action_ がDomainの入力値であるDTOを構築するのは可能ですか？

はい. ただし、_Data Transfer Object_の構築は、条件なしで完了しなければならないことに注意してください。DTOの構築で例外やエラーが発生する可能性がある場合は、必要な入力を_Domain_に渡し、_Domain_にDTOを構築させ、そのDTOを必要なドメイン・ロジックに渡す方が良いでしょう。

### _Action_はCommand Busを使えますか？

Command Busは、ユーザーインターフェースのパターンではなく、ドメインロジックのパターンであり、_Action_ではなく、_Domain_で使用する必要があります。この点についての詳しい説明は、[Command Bus and Action-Domain-Responder](http://paul-m-jones.com/post/2016/03/08/command-bus-and-action-domain-responder/)を参照してください。

### ドメインの例外を _Action_ で処理するべきか？

**ユーザーインターフェース**要素は、**ドメインロジック**の例外処理を担当すべきではありません。_Domain_は独自の例外処理を行い、その処理結果を _Action_ に報告します。

### _Action_は_Responder_を起動する前に操作できるか？

レスポンダの実装によっては、_Action_セットのデータ要素を個別に入力する必要があったり、呼び出しの前に他のメソッドの呼び出しを必要とする場合があります。

たとえば、これの代わりに:

```php
return $this->responder->createResponse($request, $payload);
```

次のようにするのも合理的です。

```php
$this->responder->setRequest($request);
$this->responder->setPayload($payload);
return $this->responder->createResponse();
```

ただし、条件付きのロジックが必要ないように注意しましょう。 すべてのプレゼンテーションロジックは _Responder_ に置くべきで、 _Action_ は値を渡してそれを呼び出すだけにしましょう。

### _Action_は、レスポンダを呼び出す代わりに、_Responder_を返すことができますか？

このパターンの初期のドラフトでは、"_Action_は_Responder_を返すことがあり、_Responder_はレスポンスを返すために呼び出され、レスポンスは自分自身を送信するために呼び出されます。 "と記載されていました。

しかし、よく考えてみると、_Action_を呼び出すコードは、なぜレスポンス以外のものを返す必要があるのでしょうか。もし、_Responder_がHTTP Responseを構築する方法を変更するロジックがあるとすれば、それは_Responder_の中に組み込まれるか、構成されるのがベストでしょう。

このように、レスポンスを直接返すのではなく、他の何かから呼び出されてレスポンスを作成するように_Responder_を返すことは、懸念事項を適切に分離することにはなりますが、このパターンの劣った形と考えるべきです。

### インターフェイス全体で1つの_Action_だけを使う事は可能か？

_Action_の責任範囲は意図的に非常に限定されているため、すべてのユーザー・インターフェース・インタラクションを処理する単一のジェネリックな_Action_クラスを作成することは可能です。しかし、そうすると、依存性を注入するシステムが使えなくなる可能性があります。また、実装者は _Action_ に必要な _Domain_ と _Responder_ のロジックへのアクセスを与える方法や、さまざまなケースでの入力の収集方法を考えなければならないでしょう。

そのような実装の一つが[Arbiter](https://github.com/arbiterphp/Arbiter.Arbiter)です。
要するに、ルーターや他のウェブ・ハンドラー・コンポーネントは、インプット・コレクション・コーラブル、ドメイン・ロジック・コーラブル、レスポンス・ビルディング・コーラブルで構成される_Action_[記述](https://github.com/arbiterphp/Arbiter.Arbiter/blob/1.x/src/Action.php)を構築します。そして、_Action_[ハンドラ](https://github.com/arbiterphp/Arbiter.Arbiter/blob/1.x/src/ActionHandler.php)は、適切な順序でコーラブルを呼び出し、その過程で必要に応じてオブジェクトインスタンスを解決します。

##_Domain_

ADRの_Domain_は、ドメインロジックへの**エントリーポイント**であることを覚えておいてください。ドメインロジック自体は、単一のインフラストラクチャの相互作用のような単純なものかもしれませんし、相互に接続されたサービスやオブジェクトの複雑な層で、最終的なステータスを返す前にお互いに通知したり観察したりするものかもしれません。

_Action_も_Responder_も、_Domain_の内部動作には関心がありません。ADRの関心事は、_Action_が_Domain_を呼び出し、_Responder_が_Domain_の結果を提示することだけです。

### _Domain_には何を書く?

ADRは**ユーザーインターフェース**のパターンであることを思い出してください。HTTPリクエストの読み取りに関係するものはすべて_Action_に入り、HTTPレスポンスの構築に関係するものはすべて_Responder_に入ります。 それ以外のすべてのものは、_Domain_に入れなければなりません。

簡単に覚えられるヒューリスティックな方法があります。"ストレージに触れるものは _Domain_ に置く" ということです。ストレージとは、データベース、キャッシュ、ファイルシステム、ネットワークなど、あらゆるインフラや外部リソースを含みます。

では、ストレージとのやりとりが、ビジネスロジックを全く必要としないテンプレートテキストの翻訳など、プレゼンテーションの値のみを取得する場合はどうでしょうか？レスポンダがそのような値を自ら取得することは合理的かもしれません。

そうであっても、一貫したヒューリスティックな考え方のために、私は、_Action_が（_Domain_の入力の一部として）_Domain_に、返されるペイロードの一部としてそれらの値を返す命令を渡すのが良いと考えています。

### ユーザーインターフェースとの適切な分離

Domain_は、HTTP固有の依存関係から完全に分離する必要があります。_Action_ と _Responder_ のユーザーインターフェースのコードが _Domain_ に依存するのは妥当ですが、 _Domain_ のコードが特定のユーザーインターフェースに依存するのは **妥当ではありません** 。

そのためのテストとして、_Domain_のエントリーポイントが、HTTPインターフェースではなく、コマンドラインインターフェースでどの程度動作するかを調べてみてください。答えが「簡単ではない」ということであれば、_Domain_はHTTPに依存しすぎていると考えられます。

### _Domain_はどのように入力を受け取るべきでしょうか？

ドメイン層へのエントリーポイントである_Domain_のシグネチャは、そのロジックがユーザの入力から必要とするものであれば何でも構いません。1つ以上の個別の引数（タイプヒントがあってもなくても）、_Data Transfer Object_、さらにはHTTPリクエストに含まれる全ての入力値が含まれた配列等です。受け取るべきではないものは、HTTPリクエストそのものです。

### _Domain_は何を返すべきですか？

これは、ドメイン・ロジックの詳細と、アプリケーションがユーザーへの出力に何を要求するかによります。これは必然的にアプリケーションのコア部分に関わることであり、 ユーザーインターフェースに左右されるべきではありません。

_Domain_は、場合によっては何も返さないこともあります。また、単純な値や単一のオブジェクトを返す場合もあります。また、オブジェクトや値の複雑なコレクションを返す場合もあります。このような場合には、_Domain Payload_を使用して、ユーザーインターフェースの境界を越えてドメインの結果や状態を伝達し、解釈することができます。

その後、_Domain_の結果をHTTPレスポンスとしてどのように表示するかは、_Responder_に任されています。

## _Responder_

### _Responder_はどのようにしてHTTPレスポンスを生成するのですか？

_Responder_は、`new`やDIされたFactoryによって、自分自身のHTTPレスポンスオブジェクトを生成して返すことができます。

また、_Responder_は、コンストラクタのパラメータとして注入されたHTTPレスポンスオブジェクトを受け取ることもできます。_Responder_は、注入されたレスポンスオブジェクトを修正してから、それを_Action_に返すことができます。実際には、HTTPレスポンスオブジェクトが既存のシステム全体で共有されている場合、ウェブハンドラーが共有オブジェクトに既にアクセスしている可能性があるため、_Responder_はHTTPレスポンスオブジェクトを返す必要がないかもしれません[1]。

これらのアプローチにはそれぞれトレードオフがありますが、_Responder_の実装としては有効です。

#### 補足

[1]のnodejsの例: [@koa/router](https://www.npmjs.com/package/koa-router)はコンテキスト上でHTTPレスポンスを構築するのに必要なパラメーターを設定するので"返す必要がない"パターンに該当します

### Generic or Parent _Responders_

レスポンス構築のロジックが非常に単純であるため、1つの_Responder_がユーザーインターフェース全体のレスポンス構築作業をすべて行うことができる場合があります。同様に、基本機能を持つ親_Responder_を、機能を追加・変更した子_Responder_で拡張することもできます。

これらはどちらもADRの実装として受け入れられます。重要な点は、応答構築作業の単純さや複雑さではなく、そのような作業が_Action_や_Domain_から完全に分離されていることです。

### Templates and Transformations

_Responder_の中で、_Template View_、_Two Step View_、_Transform View_の各実装を使用することは、HTTPレスポンスのコンテンツを構築する上で、全く問題ありません。

### Widgets and Panels

プレゼンテーションの中には、異なるデータソースを持つ複数のパネル、コンテンツエリア、サブセクションがある場合があります。これらは、テンプレートシステムやその他のプレゼンテーションサブシステムで処理することができますが、_Domain_から独自のデータを取得してはいけません。代わりに、_Action_がウィジェットを起動したときに、_Domain_がこれらのウィジェットに必要なデータをすべて提供する必要があります。

その方法の初歩的な例については、[Solving The "Widget Problem" In ADR](http://paul-m-jones.com/post/2017/12/28/solving-the-widget-problem-in-adr/)を参照してください。

#### 補足

例えばHypertext Application Language (HAL)を正確に・効率的に構築する為のパッケージは_Responder_の中で利用されます

## その他のTopics

### Content Negotiation

コンテンツネゴシエーションは、HTTPレスポンスのボディコンテンツをどのように表示するかを扱うため、最も適切には_Responder_に属します。例えば、_Responder_は、HTTP Requestの`Accept`ヘッダーに基づいて、HTTP Responseのボディのコンテンツタイプをネゴシエートすることができます。

しかし、HTTPリクエストが、ウェブハンドラー、_Action_、_Domain_（高価なリソースの使用を伴う可能性がある）を経て、最終的に_Responder_に到達し、唯一、_Responder_が許容されるコンテンツタイプのいずれも満たすことができないと判断するのは、非効率的である。

このように、リクエストをルーティングした後、ウェブハンドラーは、ルーティングされた_Action_の_Responder_を先読みして、_Responder_がリクエストで許容されるコンテンツタイプのいずれかを提供できるかどうかを判断することが合理的であるかもしれません。

これはそれ自体がネゴシエーションではなく、単に`Accepts`ヘッダーに_Responder_が扱えると表明しているタイプが含まれているかどうかを確認するものです。Webハンドラーと_Responder_はすべてユーザーインターフェイス層に存在するので、これは不適切な依存関係を示すものではありません。

例としては、Radarフレームワークを参照してください。

- デフォルトの_Responder_クラスでは、応答可能なコンテンツタイプを報告します ([code](https://github.com/radarphp/Radar.Adr/blob/1.x/src/Route.php#L121-L147)).

- The route class, _Responder_ をルートに関連付ける ([code](https://github.com/radarphp/Radar.Adr/blob/1.x/src/Route.php#L121-L147)).

- 受け入れ可能かどうかをテストするrouter rule ([code](https://github.com/auraphp/Aura.Router/blob/3.x/src/Rule/Accepts.php)).


### Sessions

上記の _Domain_ のヒューリスティックな考え方を思い出してください。「ストレージに触れているものは _Domain_ に属する」ということです。 セッションはストレージ（ファイルシステム、データベース、キャッシュなど）から読み書きを行います。したがって、セッションの作業はすべて _Domain_ で行う必要があります。例えば、以下のようになります。

- _Action_は、入力された Session ID(もしあれば)を読み取って、それを_Domain_への入力として渡すことができます。

- その後、_Domain_はそのIDを使ってSession Storeの読み書きを行い（もしくは新規作成を行い）、後で結果の一部としてSession IDや関連データを_Domain Payload_で返すことができます。

- その後、_Responder_は、_Domain_の結果からSession IDとデータを読み取り、それに基づいてCookieを設定することができます。

しかし、Sessionの実装の中には、言語やフレームワークと密接に絡み合っていて、 純粋な_Domain_の作業には適さないものもあります。たとえば、PHP のセッション拡張機能は複数の問題を組み合わせています。

- `session_start()` は、入力されたリクエストデータからSession ID を直接読み込み、次に `$_SESSION` というスーパーグローバルデータをストレージ自体から読み込みます。これにより、入力の収集とインフラとの相互作用に関する懸念が解消されます。

- `session_commit()` は、`$_SESSION` のスーパーグローバルデータをストレージに書き戻し、クッキーヘッダを発信するレスポンスバッファに直接書き込みます。これにより，インフラとのインタラクションとプレゼンテーションの問題が解決されます．

このような状況では、HTTPリクエスト・オブジェクトによる自動入力収集プロセス、HTTPレスポンス・オブジェクトによる自動出力プロセス、インフラとドメイン・ロジックの懸念をインターセプトすることは困難です。

これはADR自体の問題ではなく、PHPのセッション関数がリクエストの読み込み、ストレージとの連動、レスポンスの送信をどのように組み合わせているかという問題です。 これが問題になるのは、PHP の自動化された動作にフックされていない HTTP リクエスト/レスポンスオブジェクトを使用する場合だけです。

これを回避する方法があるならば、そうすべきです。一つの方法は、[自動セッション処理の一部の要素を無効にし、他の要素はそのままにする](http://paul-m-jones.com/post/2016/04/12/psr-7-and-session-cookies/)ことです。また、自動セッション処理を完全に回避し、[ここで紹介するような](https://www.futureproofphp.com/2017/05/02/best-way-handle-sessions-adr/)のようなドメインロジックに適したソリューションを採用するという方法もあります。

残念ながら、入力の収集、ストレージからの読み書き、出力の提示をきれいに分離することが**必要ですが、言語やフレームワークの制約の中では、そうすることが現実的でない場合もあります。そのような場合には、HTTPリクエストとレスポンスオブジェクトを使ったセッション作業は、私たちが望むほどクリーンではない方法で行われなければならないかもしれません。

### 認証

セッションと同様に、認証作業は、どこかの時点でストレージに触れる可能性があるため、_Domain_で行うべきです。例えば、以下のようになります。

- _Action_ は、HTTP リクエストから認証情報 (トークンやセッション ID など) を収集し、それを入力として _Domain_ に渡すことができます。

- _Domain_ はストレージシステムと連携して、認証情報の有効性や有効期限などを確認し、その認証情報に関連付けられているユーザー固有のデータを読み込むことができます。

- 認証状態に基づいて、_Domain_ は、匿名または無効なユーザに対しては早期に返答するか、または他のドメインロジックに進み、後で認証状態（またはその欠如）を結果の一部として、おそらく _Domain Payload_ の一部として返すことができます。

- _Responder_は、_Domain_の結果に含まれるユーザ情報を検査し、適切に表示することができます。

#### Routing

多くの場合、開発者はいくつかのエンドポイントを認証されたユーザーのみに制限したいと思うでしょう。それは、ユーザーインターフェースコンポーネントであるルーターが、認証ロジックが存在するドメイン層と対話しなければならないということでしょうか？

答えは、"そうではないかも"。 ルートの条件が「誰であるかに関わらず、ユーザーは全く認証されていないか」というようなものに基づいている場合、答えは**認証**ではなく**匿名**をチェックすることです。

つまり、受信したHTTPリクエストにクレデンシャルやトークンが関連付けられていなければ、そのリクエストは匿名であり、適切にルーティングすることができます。クレデンシャルの保存と検証を含む認証作業は、Routerから削除して _Domain_ に置くことができます。

#### Applicability

認証はユーザーとのやりとりを識別して管理するものなので、ユーザーインターフェースのコードに含まれるべきだという主張があります。私は直感的にそうすることに反対ですが、それは支持できる視点です。

そこで問題となるのは、ドメイン・ロジックに対してユーザーをどのように表現するかということです。ドメイン・ロジックがユーザー・インターフェース・コードに依存することは避けたいので、ユーザー・コンポーネントはユーザー・インターフェース・レイヤーによって提供されてはなりません。

ここでの一つの解決策は、ユーザーインターフェースコードがドメイン層によって提供されるUserコンポーネントを作成することです。このUserコンポーネントは、コンストラクタのパラメータとして、あるいはHTTPリクエストの追加パラメータとして、あるいはその他の方法で_Action_に渡すことができます。そして、_Action_は、Userコンポーネントを_Domain_への入力として扱うことができ、そこからすべてが始まります。

このアプローチには問題があることは想像できますが、_Domain_の作業結果を提示するユーザーインターフェイスフレームワークの制約を考えると、それ以外の方法はあり得ないのかもしれません。

### Authorization

認証はユーザーを特定するものですが、認可はそのユーザーが何をすることができるかを制御するものです。権限付与の作業は、間違いなく _Domain_ に属します。

認証の場合と同様に、ユーザーが特定のルートに沿って派遣されることを許可されているかどうかをルータが知ることができない場合、ルーティング（ユーザーインターフェイスの問題）をどのように行うことができるでしょうか？その答えは、認証とは特定のルートに対するものではなく、 そのルートがつながる特定の _Domain_ の機能に対するものだということです。また、ドメイン内の特定のリソースに関する機能も対象となる場合があります。その場合は、認可チェックの一環として、ドメイン内のリソースを（一部または全部）読み込む必要があります。

このように、ユーザーが特定の機能を実行することを許可されているかどうかをチェックするのは _Domain_ です。許可されていれば、_Domain_のロジックは続行しますが、許可されていなければ、_Domain_は適切な報告を行います。これにより、ユーザーインターフェースコンポーネントではなく、 _Domain_ がドメインレイヤーの機能に対する適切な権限を持つことになります。

これについての詳しい説明は、[Auth Gates and User Roles](https://www.reddit.com/r/PHP/comments/64910c/laravel_auth_gates_and_user_roles/?sort=old)の項を参照してください。

### Client-Side Use

ADRパターンは、クライアントサイドでの使用を想定していません。クライアント側には、オリジナルの_Model View Controller_や_Model View Presenter_など、既存の優れたユーザーインターフェースパターンがたくさんあります。

### Command Line Use

ADRは、サーバーサイドアプリケーションのユーザーインターフェースパターンとして想定されていますが、非対話型のコマンドラインアプリケーションのユーザーインターフェースパターンとしても機能します。つまり、コマンドが起動された瞬間に提供された値だけで完結するのであれば、次のようになります。

- _Action_は、コマンドラインから渡された引数、フラグ、オプションなどの入力を収集し、_Domain_を起動して結果を返し、_Responder_を起動して（もしあれば）出力を生成します。

- _Domain_はそのままです。

- _Responder_は、HTTPレスポンスを生成するのではなく、_ドメインの結果を使ってSTDOUTとSTDERRに書き込みます。

この場合、_Domain_は、STDOUTとSTDERRに書き込むロギングシステムやnotifier/observerシステムを使用して、ユーザーに継続的な出力を提供することができます。ロギングや通知は_Domain_の運用に付随するものなので、これは必ずしもADRに違反するものではありませんが、このパターンが必ずしも環境に適しているとは言えないことを示しています。

この種の非対話的な使用の一例として、[Cadre CliAdr](https://github.com/cadrephp/Cadre.CliAdr)を参照してください。

ADRパターンは、コマンド起動後にユーザーの追加入力を必要とするインタラクティブなコマンドライン・アプリケーションではうまく機能しません。

#### 補足

> ADRパターンは、コマンド起動後にユーザーの追加入力を必要とするインタラクティブなコマンドライン・アプリケーションではうまく機能しません。

Client-Side Useでも書かれていますが、ADRは対話型のアプリケーションには適しません.