クリーンアーキテクチャの​理論編:原典で​確かめる​依存性の​ルール

クリーンアーキテクチャは、​Robert C. Martin (通称 Uncle Bob) が 2012 年 8 月の​ブログ記事​「The Clean Architecture」​で示した、​ソフトウェアの​構造の​考え方です。​2017 年には​同じ​題名の​本も​出ています。​同心円の​図は​よく​知られていますが、​図だけが​広まって​「4 つの​フォルダを​作る​こと」と​受け取られる​こともあります。

この記事は 2 本組みの​「理論編」です。

  • 理論編 (この記事):何のために​分けるのか、​どこから​来た​考えか、​依存性の​ルール、​境界の​越え方、​設計の​原則、​誤解と批判
  • 実践編:経費精算の​「申請を​承認する」を TypeScript で作り、​テストまで​動かす。​ディレクトリ構成、​テスト戦略、​DDD・​CQRS・​フロントエンドとの​関係、​既存の​システムへの​入れ方、​チェックリスト

どちらから​読んでも​分かるように​書いています。​手を​動かしながら​覚えたい​人は、​実践編から​読んでもかまいません。

この記事の​読み方

  • 引用するのは、​本文を​確かめられた​資料だけです。 Martin の​ブログ (blog.cleancoder.com) と、Martin が​以前に​公開した​記事・論文、​ほかの​著者の​公開記事です。​英語の​原文と​訳 (訳は​この​サイト) を​並べ、​どの​資料かを​書き添えます
  • 2017 年の本は、​出版社 (InformIT) のページに​ある​目次で、​章と​節の​題名を​確かめた​範囲だけを​書きます。 本の文章の​引用や​中身の​要約は​していません。​「本には​第 N 章『題名』が​あります」のように、​章や​節が​ある​ことだけを​書きます。​その前後の​説明は、​この​記事の​言葉に​よる​説明です
  • 原典と​解釈を​分けます。 原典に​書いてある​ことは​灰色の​線の​枠、​後の​解釈や​実務の​工夫は​黄色の​線の​枠に​入れます。​枠の​外でも、​資料に​書いてある​ことには​資料名を​添えます。​資料名の​ない​説明や​意見は、​この​記事の​考えです
  • 図はすべて​この​記事の​ために​描いたもので、原典の​図の​転載ではありません

1. 要点は​「依存の向き」

クリーンアーキテクチャの​中心は、​1 つの​規則です。

source code dependencies can only point inwards.

(ソースコードの​依存は、​内側へだけ向けてよい)

— Robert C. Martin​「The Clean Architecture」​(2012 年の​ブログ)

内側には​業務の​規則を、​外側には Web・​データベース・​フレームワークのような​仕組みを​置きます。​外側は​内側を​知っていてかまいませんが、​内側は​外側を​一切​知りません。​こうしておくと、​外側の​仕組みを​替えても​内側は​書き換えずに​済み、​内側は​外側なしで​テストできます。

有名な​同心円の 4 つの​層は、​この​規則を​説明する​ための​例です。​同じ​ブログが​「円は​模式図で、​4 つでなければならないと​いう​規則は​ない」と​書いています (4 章で​引用します)。​クリーンアーキテクチャは、​フォルダの​切り方の​型でも、​特定の​フレームワークの​使い方でもなく、​依存の​向きの​規則と、​それを​守る​ための​境界の​越え方​だ、というのが​この​記事の​読み方です。

2. 何の​ために​分けるのか、​いつ分けなくて​よいのか

変わる​理由が​違う​ものを​分ける

Martin は 2014 年の​ブログ​「The Single Responsibility Principle」​で、従業員の​クラスに​給与の計算 (calculatePay)、データベースへの保存 (save)、監査向けの​勤務時間の報告 (reportHours) の 3 つの​メソッドが​ある​例を​挙げています。​給与の​計算の​仕様に​責任を​持つのは​財務の​責任者 (CFO)、​勤務時間の​報告は​業務の​責任者 (COO)、​保存は​技術の​責任者 (CTO) で、​変更の​依頼は​それぞれの​組織から​来ます。​そして、​こう​書いています。

This principle is about people.

(この原則は、​人に​ついての​ものだ)

— Robert C. Martin​「The Single Responsibility Principle」​(2014 年の​ブログ)

経費精算システムに​当てはめると、​次のようになります (この記事の​例です)。

変更の例 求める人 (例) 変わるべき場所
10 万円以上は​経理の​承認も​要るようにする 経理部 (承認権限規程の改定) 業務の規則
承認ボタンを​スマホでも​押しやすくする 承認する社員 画面
社内の​データベースを​クラウドに移す 情報システム部 データの保存
会計システムを​入れ替える 経理部と​情報システム部 外部との連携

変える​理由も、​求める​人も、​時期もばらばらです。​これらが 1 つの​クラスに​混ざっていると、​画面の​変更で​承認の​規則が​壊れる、と​いった​ことが​起きます。​同じ​ブログは、​SQL を JSP に​書かない​こと、​業務の​規則が​データベースの​スキーマを​知らない​ことも、​この​原則から​説明しています。​変わる​理由ごとに​置き場所を​分け、​置き場所どうしの​依存の​向きを​決めて​おく。​クリーンアーキテクチャは、​これを​構造全体で​行う​ものだと​読めます。

外の仕組みなしで​テストできる

2012 年の​ブログは、​クリーンアーキテクチャが​まとめた​先行の​考え方 (3 章) で​作った​システムの​性質と​して、​フレームワークからの​独立、​テストの​しやすさ、​UI からの​独立、​データベースからの​独立、​外部の​どんな​ものからの​独立、の 5 つを​挙げています。​テストに​ついては​こうです。

The business rules can be tested without the UI, Database, Web Server, or any other external element.

(業務の​規則は、​UI・​データベース・​Web サーバー、​その​ほかの​外部の​要素なしで​テストできる)

— 「The Clean Architecture」​(2012)

2011 年の​ブログ​「Screaming Architecture」​にも、テストを​動かすのに Web サーバーや​データベースの​接続が​要るべきではない、と​いう​趣旨の​文が​あります (You shouldn’t need the web server running in order to run your tests.)。​実践編のコードでは、​承認の​規則の​テストは​データベースも HTTP も​使わず、​1 件あたり 1 ミリ秒かからずに​終わりました (手元の​実行結果)。

フレームワークを​道具と​して使う

Frameworks are tools, not ways of life.

(フレームワークは​道具であって、​生き方ではない)

— 「Screaming Architecture」​(2011)

2011 年 11 月の​ブログ​「Clean Architecture」​では、Rails を​例に​こう​書いています。

Keeping the business rules separate and decoupled from the ActiveRecord derivatives does not violate any Rails conventions.

(業務の​規則を ActiveRecord の派生クラスから​切り離しておく​ことは、​Rails の​どの​規約にも​反しない)

本には​第 32 章​『Frameworks Are Details』が​あり、​目次には​「Asymmetric Marriage」​という​節が​あります。​この​記事の​言葉で​まとめると、​フレームワークは​外側で​使い、​内側の​コードが​フレームワークの​型や​基底クラスを​知らないように​する、と​いう​ことです。

決定を​遅らせられる

A good software architecture allows decisions about frameworks, databases, web-servers, and other environmental issues and tools, to be deferred and delayed.

(良いソフトウェア​アーキテクチャは、​フレームワーク・​データベース・​Web サーバー、​その​ほかの​環境や​道具に​ついての​決定を、​先に​延ばせるようにする)

— 「Screaming Architecture」​(2011)

一方で、​2011 年 11 月の​ブログは​こうも​書いています。

A good architecture allows you to defer critical decisions, it doesn’t force you to defer them.

(良いアーキテクチャは、​重要な​決定を​遅らせる​ことを​可能に​する。​遅らせる​ことを​強いるのではない)

最初から PostgreSQL と決まっていても​問題は​ありません。​決めた​ことを​内側が​知らずに​済むように​しておけば​よい、と​いう​ことです。​本では​第 15 章​『What Is Architecture?』​に「Keeping Options Open」と​いう​節が​あります。

分けなくてよい場面

オニオンアーキテクチャを​提唱した Jeffrey Palermo は、2008 年の​最初の​記事で​こう​断っています。

This architecture is not appropriate for small websites. It is appropriate for long-lived business applications as well as applications with complex behavior.

(このアーキテクチャは​小さな Web サイトには​向かない。​長く​使う​業務アプリや、​振る舞いの​複雑な​アプリに​向いている)

— Jeffrey Palermo​「The Onion Architecture : part 1」(2008)

Martin 自身も、​2011 年 11 月の​ブログで​「大がかりな​事前設計 (Big Up Front Design) ではないか」と​いう​声に​答えて、​何か​月も​図を​描けと​言っているのではなく、​コードを​書いて​テストを​通しながら切り離していけばよい、​という​趣旨の​ことを​書いています (You can do that decoupling while you are writing your code and making your tests pass.)。

3. 歴史:2012 年の図は​何を​まとめたのか

2012 年の​ブログは、​冒頭で​先行する 5 つの​考え方を​挙げ、​こう​続けます。

Though these architectures all vary somewhat in their details, they are very similar. They all have the same objective, which is the separation of concerns.

(これらの​アーキテクチャは​細部こそ​違うが、​よく​似ている。​どれも​同じ​目的、​関心の​分離を​目指している)

— 「The Clean Architecture」​(2012)

そして、​どれも​業務の​規則の​ための​層を​少なくとも 1 つ、​外との​やりとりの​ための​層を 1 つ​持っている、と​指摘します。​クリーンアーキテクチャの​図は、​これらを​「1 つの​実行できる​考え」に​まとめようとした​もの (an attempt at integrating all these architectures into a single actionable idea) です。

年 名前 提唱 中心の​考え (出典は各節)
1992 BCE Ivar Jacobson 境界・​制御・実体の 3 種類の​クラスで、​ユースケースを​実現する
2005 ヘキサゴナル (Ports and Adapters) Alistair Cockburn アプリを、​本番の​装置や​データベースから​切り離して​開発・​テストできるようにする
2008 オニオン Jeffrey Palermo ドメインモデルを​中心に​置き、​結合は​すべて​中心へ​向ける
2009 DCI Trygve Reenskaug と James O. Coplien データと、​ユースケースごとの​役割の​相互作用を​分けて書く
2011 Screaming Architecture Robert C. Martin 最上位の​構造が、​フレームワークではなく​ユースケースを​語るようにする
2012 The Clean Architecture Robert C. Martin 上をまとめた 1 つの​図と、​依存性の​ルール
2017 本『Clean Architecture』 Robert C. Martin 設計の​原則・​コンポーネント・​境界・​詳細を 1 冊に​まとめる (目次による)

BCE (1992)

2012 年の​ブログは、​BCE を Ivar Jacobson の本『Object Oriented Software Engineering: A Use-Case Driven Approach』​の考え方と​して​挙げています。​英語版 Wikipedia の「Entity–control–boundary」​の項に​よると、​Entity は​関係者に​とって​長く​残る​情報、​Boundary は​外部の​利用者や​外部の​システムとの​やりとり、​Control は​ユースケースの​実行に​要る​処理と​業務の​論理を​受け持つ​クラスです (Jacobson の本は、​この​記事では​読んで​確かめていません)。

Martin は​「Screaming Architecture」​で、この​本の​副題 (ユースケース駆動) に触れ、​ソフトウェアの​アーキテクチャは​システムの​ユースケースを​支える​構造だ、と​いう Jacobson の​指摘を​紹介しています。

対応づけると、​Boundary が Interface Adapters の Controller や Presenter、​Control が Use Cases の Interactor、​Entity が Entities に​近い​役割です (この対応は​この​記事の​解釈です)。

ヘキサゴナルアーキテクチャ (2005)

Alistair Cockburn が 2005 年 9 月 4 日の​日付 (版 0.9) で​公開した​記事です。​目的 (Intent) は​こう​書かれています。

Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases.

(アプリを、​利用者からも​プログラムからも​自動テストからも​バッチからも​同じように​動かせるようにし、​本番で​使う​装置や​データベースから​切り離して​開発・​テストできるようにする)

— Alistair Cockburn​「Hexagonal architecture」​(2005)

外の世界との​「目的の​ある​会話」​(a purposeful conversation) の口を​ポートと​呼び、​1 つの​ポートには​技術ごとに​複数の​アダプターが​つながりえます。​アプリを​動かす側 (利用者・​テスト) と、アプリが​動かす側 (データベースなど) を左右に​分けて​描きます。​六角形なのは 6 と​いう​数に​意味が​あるからではなく、​描く​人が​ポートと​アダプターを​描き込む​余白を​取る​ためだ、と​本人が​書いています。

この記事が​示すのは​アプリの​「内と​外」の​分け方で、​内側を​さらに​どう​分けるかは​書かれていません。​2012 年の​ブログに​よれば、​Steve Freeman と Nat Pryce も​本『Growing Object Oriented Software』​でこの​考えを​取り入れています。​Cockburn の​公式サイトでは、​本『Hexagonal Architecture Explained』​も販売されています (刊行年・​共著者などは、​この​記事では​確かめていません)。

オニオンアーキテクチャ (2008)

Jeffrey Palermo が 2008 年 7 月 29 日から​連載した​記事です。

The fundamental rule is that all code can depend on layers more central, but code cannot depend on layers further out from the core.

(基本の​規則は、​どの​コードもより​中心の​層には​依存して​よいが、​中心から​遠い層には​依存できない、と​いう​ことだ)

— 「The Onion Architecture : part 1」(2008)

クリーンアーキテクチャの​依存性の​ルールと​ほぼ​同じです。​記事の​図では、​中心に Domain Model、​その​外に Domain Services、​Application Services があり、​一番外に User Interface・​Infrastructure・​Tests が並びます。​記事の​本文に​よると、​データの​保存と​取り出しの​インターフェース (Repository のインターフェース) は​アプリの​中心側に​置き、​その​実装は​外側に​置きます。​「The database is not the center. It is external.」​(データベースは​中心ではない。​外部の​ものだ) と​いう​一文も​あります。

DCI (2009)

Trygve Reenskaug と James O. Coplien が 2009 年 3 月に Artima で​発表した​記事です。​記事に​よると、​オブジェクトが​「何であるか」を​表す​データの​モデルと、​システムが​「何を​するか」を​表すアルゴリズムの​モデルを​分け、​ユースケースの​シナリオの​中で​オブジェクトが​演じる​役割の​対応づけを Context と​して​扱います。​ユースケースを​コードの​中で 1 つの​まとまりと​して​見えるように​する​点が、​クリーンアーキテクチャの Use Cases の​層に​通じます (この​対応は​この​記事の​解釈です)。

Screaming Architecture (2011)

Martin の 2011 年 9 月の​ブログです。​建物の​設計図を​見れば​住宅か​図書館か​分かるように、​ソフトウェアも​最上位の​ディレクトリを​見れば​何の​システムか​分かるべきだ、と​書いています。

do they scream: Health Care System, or Accounting System, or Inventory Management System? Or do they scream: Rails, or Spring/Hibernate, or ASP?

(それは​「医療システム」​「会計システム」​「在庫管理システム」​と叫んでいるか。​それとも​「Rails」​「Spring/Hibernate」​「ASP」と​叫んでいるか)

— 「Screaming Architecture」​(2011)

実践編のコードの​最上位の​ディレクトリが controllers/ や models/ ではなく expense/ (経費) なのは、​この​考えによります。

原典の​ブログと本

2012 年 8 月 13 日の​ブログ​「The Clean Architecture」は、図と​依存性の​ルール、​4 つの​層、​境界の​越え方、​境界を​越える​データを​短く​まとめた​記事です。​その​前年の 2011 年 11 月 22 日には​「Clean Architecture」​という​題の​ブログが​あり、​フレームワークや UI を​アプリから​隠すと​いう​考えへの​反論 (Rails では無理だ、​コードの​重複が​増える、​大がかりな​事前設計だ、​など) に​答えています。

2017 年の​本『Clean Architecture: A Craftsman’s Guide to Software Structure and Design』​(Pearson) は、出版社の​目次に​よると、​第 I⁠〜​VI 部の 34 章と、​第 VII 部の付録からなります。​目次の​順では、​第 I 部の​導入、​第 II 部の​プログラミングの​パラダイム、​第 III 部の設計の​原則、​第 IV 部の​コンポーネントの​原則の​あとで、​第 V 部​「Architecture」​に入ります。​2012 年の​ブログと​同じ​題名の​第 22 章​『The Clean Architecture』は 201 ページから​始まり、​次の​章は 211 ページからです。​第 VI 部​「Details」​には、データベース・​Web・​フレームワークを​それぞれ​「詳細」と​する 3 つの​章 (第 30⁠〜​32 章) が​あります。

邦訳は​『Clean Architecture 達人に​学ぶソフトウェアの​構造と​設計』(角征典・​高木正弘 訳) です。​書誌の​データベース (openBD・​版元ドットコム) では、2018 年 7 月の​版 (ISBN 978-⁠4-⁠04-⁠893065-⁠9) と、ZEN大学出版会の​版 (ISBN 978-⁠4-⁠04-⁠901203-⁠3) が確かめられます。

「Entity」は 3 つの​意味で​使われる

同じ「Entity」と​いう​言葉が、​文脈に​よって​違う​ものを​指します。​混ざると​議論が​かみ合わなくなるので、​先に​整理しておきます。

文脈 Entity が​指すもの 出典
クリーンアーキテクチャ 会社全体の​業務規則を​カプセル化する​もの。​メソッドを​持つオブジェクトでも、​データ構造と​関数の​組でもよい 2012 年の​ブログ
ドメイン駆動設計 (DDD) 時間や​表現が​変わっても​続く、​区別できる​同一性を​持つオブジェクト Fowler の​解説 (Evans の分類)
ORM (JPA の @Entity など) データベースの​表の​行に​対応づける​クラス (各 ORM の仕様)

ORM の Entity を​そのまま​内側に​置くと、​内側が ORM を​知ることになり、​依存性の​ルールに​反します。​どこまで​許すかの​折り合いは 7 章で​書きます。

4. 依存性の​ルールと層

ルールの本文

2012 年の​ブログは、​円の​内側と​外側の​関係を​こう​書いています。

In general, the further in you go, the higher level the software becomes. The outer circles are mechanisms. The inner circles are policies.

(一般に、​内側へ​行く​ほど​ソフトウェアは​高い​レベルに​なる。​外側の​円は​仕組みであり、​内側の​円は​方針である)

そして、​依存性の​ルール (The Dependency Rule) の説明が​続きます。

Nothing in an inner circle can know anything at all about something in an outer circle.

(内側の​円の​中の​ものは、​外側の​円の​中の​ものに​ついて​何ひとつ​知っては​ならない)

— 「The Clean Architecture」​(2012)

「知る」とは​何かも具体的に​書かれています。​外側で​宣言された​ものの​名前 (関数・​クラス・​変数など) を内側の​コードに​書かない​こと。​外側で​使う​データの​形式、​特に​外側の​フレームワークが​作る​形式を、​内側で​使わないこと。

4 つの層の入れ子の図。外側から Frameworks and Drivers、Interface Adapters、Use Cases、Entities。矢印は、外側から内側へ向かうソースコードの依存を表す Frameworks & DriversWeb・DB・外部のサービス・mainInterface AdaptersController・Presenter・Gateway の実装Use Casesこのアプリだけの業務ルールEntities会社全体の業務ルールExpenseReport・Money承認権限規程・職務の分離
4 つの​層と​依存の​向き。​中央下の​矢印は、​ソースコードの​依存 (import) が​外から​内へだけ向く​ことを​表します。​中の​例は、​実践編で​作る​経費精算の​コードの​名前です。

元のブログの​図では、​Interface Adapters の円に Controllers・​Presenters・​Gateways、​一番外の​円に Web・​UI・​DB・​Devices・​External Interfaces と書かれています。

「知っている」とは何か

Entities

Entities encapsulate Enterprise wide business rules.

(Entities は、​会社全体の​業務規則を​カプセル化する)

— 「The Clean Architecture」​(2012)

同じブログに​よると、​Entity は​メソッドを​持つオブジェクトでも、​データ構造と​関数の​組でもかまいません。​大事なのは、​その​会社の​多くの​アプリから​使えるような​規則である​ことです。​会社が​なく 1 つの​アプリを​作っているだけなら、​その​アプリの​業務オブジェクトが Entities です。外の​何かが​変わった​ときに、​いちばん​変わりにくい​ものが​入ります。

経費精算なら、​「10 万円以上は​部長の​承認が​要る」​「自分の​申請は​自分で​承認しない」​のような​規則が​これに​当たる、とこの​記事では​考えます。​紙と​判子で​精算していた​ころから​業務と​して​存在した​規則です。​本には​第 20 章​『Business Rules』が​あります。

Use Cases

The software in this layer contains application specific business rules.

(この層の​ソフトウェアは、​アプリ固有の​業務規則を持つ)

— 「The Clean Architecture」​(2012)

同じブログに​よると、​ユースケースは Entities とのデータの​やりとりを​取りまとめ、​Entities の​規則を​使って​ユースケースの​目的を​果たします。​データベースや UI が​変わっても​この​層は​変わりませんが、​アプリの​操作が​変われば​変わります。​経費精算なら​「承認したら​次の​承認者の​名前を​返す」​「最後の​承認で​経理に​支払いを​依頼する」が​ユースケースの​手順です (この記事の例)。

Interface Adapters

同じブログに​よると、​ユースケースや Entities に​都合の​よい形と、​データベースや Web のような​外部に​都合の​よい形の​間で​データを​変換する​層です。​GUI の MVC は​まるごと​この​層に​入り、​Presenter・​View・​Controller がここに​入ります。​SQL も​この​層の、​データベースを​受け持つ部分だけに​閉じ込めます。

Frameworks & Drivers

同じブログに​よると、​一番外は​データベースや Web フレームワークのような​道具で、​ここに​書く​コードは 1 つ​内側に​つなぐ​ための​接着剤のような​コードが​中心です。

The Web is a detail. The database is a detail.

(Web は​詳細だ。​データベースは​詳細だ)

— 「The Clean Architecture」​(2012)

「詳細」は​「重要でない」と​いう​意味ではない、とこの​記事では​読みます。​業務の​規則の​側から​見て、​知らずに​済ませるべきもの、と​いう​意味です (データベースの​扱いは 7 章)。

層は 4 つと​決まっていない

この規則は​どの​層か、の​決め方

規則・​処理 (この​記事の例) 層
合計が 10 万円以上なら 3 段の​承認が要る Entities
申請者本人は​承認できない Entities
最後の​承認で​経理に​支払いを​依頼する Use Cases
承認の​記録と​支払依頼を、​両方残すか​両方残さないか Use Cases (手段は外側)
金額を​「45,800円」、​日時を​日本時間で​表示する Interface Adapters (Presenter)
承認の​記録を SQL で書く Interface Adapters (Gateway の実装)
HTTP サーバーを​起動する Frameworks & Drivers

「最後の​承認で​支払いを​依頼する」は、​紙の​運用でも​あった​規則と​見て Entities に​置く​考え方も​あります。​迷う​ものは、​まず Use Cases に​置き、​ほかの​ユースケースからも​同じ​規則が​必要に​なったら Entities へ​移す、と​いう​進め方が​無理が​ないと​考えます。

5. 境界の​越え方

内から​外へ​呼ぶときの問題

2012 年の​ブログは、​図の​右下の​例を​使って​こう​説明しています。

It begins in the controller, moves through the use case, and then winds up executing in the presenter.

(制御は Controller から始まり、​ユースケースを​通って、​最後は Presenter で​実行される)

— 「The Clean Architecture」​(2012)

Controller → ユースケースは​外から​内への​呼び出しなので、​依存の​向きと​一致します。​ところが​ユースケース → Presenter は内から​外への​呼び出しです。​ユースケースが Presenter を​直接呼ぶと、​内側が​外側の​名前を​書く​ことになり、​依存性の​ルールに​反します。

境界をはさんで、左の外側に Controller と Presenter、右の内側に Input Port、Interactor、Output Port。 実線の依存の矢印はどれも右の内側へ向く。破線の制御の流れは、Controller から Interactor へ入り、Interactor から Presenter へ外へ出る 外側Interface Adapters内側Use CasesControllerPresenter«interface»Input PortInteractor«interface»Output Port① 入力を渡す② 結果を渡す
  • ソースコードの​依存 (import)。​どれも​内側へ​向いています。​白抜きの​三角は​「その interface を​実装する」
  • 実行時の​制御の​流れ。​② は​内側から​外側へ​出ます
制御の​流れ (破線) と​依存の​向き (実線) が、​② の​ところで​逆に​なります。

元のブログの​図では、​この​部分が Controller、​Use Case Input Port、​Use Case Interactor、​Use Case Output Port、​Presenter の 5 つの​箱と​「Flow of control」​の線で​描かれています。​上の​図は​それを​もとに、​この​記事で​描き直した​ものです。

依存性逆転の​原則 (DIP)

we have the use case call an interface (Shown here as Use Case Output Port) in the inner circle, and have the presenter in the outer circle implement it.

(ユースケースには​内側の​円に​ある​インターフェース (図では Use Case Output Port) を呼ばせ、​外側の​円の Presenter に​それを​実装させる)

— 「The Clean Architecture」​(2012)

ユースケースが​知っているのは、​自分と​同じ​内側に​ある Output Port という​インターフェースだけです。​Presenter は​その​インターフェースを​実装するので、​Presenter → Output Port という​依存に​なり、​向きは​内側へ​そろいます。​実行時には Presenter の​メソッドが​呼ばれますが、​ソースコードの​上では​内側は​外側を​知りません。

Martin は 2016 年の​ブログ​「A Little Architecture」​の対話で、​この​点を​こう​言い表しています。

At runtime this is true. But at compile time we want the dependencies inverted.

(実行時には​その​通りだ。​だが​コンパイル時には、​依存を​逆に​したいのだ)

— 「A Little Architecture」​(2016)

TypeScript は構造的型付けなので、implements を書かなくても​形が​合えば​代入できます。​それでも Presenter に implements を書いて​おくと、​インターフェースが​変わった​ときに Presenter の​側で​型エラーに​なり、​依存が​あることも​コードから​読み取れます。

Controller から Presenter まで

2011 年 11 月の​ブログに、​流れが​短く​まとめられています。

the controllers unpack the HttpRequest object into a simple vanilla data structure, and then pass that data structure to an interactor object that implements the use case by invoking business objects. The interactor then gathers the response data into another vanilla data structure and passes it back to the UI.

(Controller は HttpRequest を単純な​データ構造に​詰め替え、​それを​インタラクターに​渡す。​インタラクターは​業務の​オブジェクトを​呼んで​ユースケースを​実行し、​応答の​データを​別の​単純な​データ構造に​まとめて UI に返す)

— 「Clean Architecture」​(2011 年 11 月の​ブログ)

本では、​第 22 章​『The Clean Architecture』​に「A Typical Scenario」​という​節が​あります。

2012 年の​ブログの​図と​本文の​名前と、​実践編の​コードの​名前の​対応は​次の​通りです。

2012 年の​ブログの​図・本文 実践編の​コード
Controller ApproveExpenseReportController
Use Case Input Port ApproveExpenseReportInputPort
Use Case Interactor ApproveExpenseReport
Use Case Output Port ApproveExpenseReportOutputPort
Presenter ApproveExpenseReportPresenter
Gateways ExpenseReportRepository とその実装
Entities ExpenseReport・​Money
(境界を​越える​単純な​データ) ApproveExpenseReportInput・​ApproveExpenseReportOutput
View json() (JSON に​書き出すだけ)

2012 年の​ブログの​本文には​「Repository」​という​言葉は​出て​こず、​図では​データベース側の​部品を Gateways と​書いています。​Repository は、Martin Fowler のパターンの​カタログ (『Patterns of Enterprise Application Architecture』) で「ドメインと​データの​対応づけの​層の​間を、​コレクションのような​インターフェースで​仲介する」​ものとして​説明されている​名前です。​この​記事の​実践編でも、​この​名前を​使っています。

Presenter と View

2012 年の​ブログは、​Presenter・​View・​Controller がどれも Interface Adapters に入る、とだけ​書いています。​2 つを​分ける​ことは、​Martin の 2018 年の​ブログ​「Too Clean?」に​次のように​書かれています。

The code that puts the data into presentable form should not reside with the code that puts that data on the screen.

(データを​表示できる​形に​する​コードは、​その​データを​画面に​出すコードと​一緒に​置くべきではない)

— 「Too Clean?」​(2018)

同じ記事で Martin は、​画面の​見た目を​調整している間は 2 つの​ファイルを​行き来するのが​面倒なので、​いったん 1 つに​戻して​作業し、​整ったらまた​分ける​ことが​ある、​とも​書いています。​原則を​書いた​本人も、​作業中の​一時的な​崩れは​認めています。

テストしにくい部分を​薄く​する​考え方は、​Gerard Meszaros が Humble Object という​パターンと​して​まとめています。

We extract the logic into a separate easy-to-test component that is decoupled from its environment.

(ロジックを、​環境から​切り離された​テストしやすい別の​部品に​取り出す)

— Gerard Meszaros​「Humble Object」​(xUnitPatterns.com)

本には​第 23 章​『Presenters and Humble Objects』が​あり、​目次には​「The Humble Object Pattern」​「Presenters and Views」などの​節が​あります。

境界を​越える​データ

実践編の​コードの​出力の​データは、​合計額を Money ではなく​円の​数値で、​次の​承認者を Employee ではなく​名前の​文字列で​持っています。​Presenter は Entities の​メソッドを​呼べないので、​Entities の​形が​変わっても Presenter は​影響を​受けません。

Output Port か、戻り値か

境界の​強さは​選べる

2014 年の​ブログ​「Clean Micro-service Architecture」は、部品の​配置の​仕方を、​たくさんの​サーバーに​置いた​マイクロサービスから、​同じ​仮想マシンの​スレッド、​jar や DLL の​中の​関数​呼び出しまで、​5 段階に​並べています。​そして、​クリーンアーキテクチャの​部品の​コードは、​自分が​どの​配置で​動いているかを​知らない、と​書いています。​本では、​第 18 章​『Boundary Anatomy』に​「The Dreaded Monolith」​「Deployment Components」​「Threads」​「Local Processes」​「Services」​という​節が​あります。

本には​第 24 章​『Partial Boundaries』があり、​節の​題名は​「Skip the Last Step」​「One-Dimensional Boundaries」​「Facades」​です。ここからは​この​記事の​言葉です。​境界を​完全には​分けず、​緩めて​おく​実務の​やり方を​挙げると​次のようになります。

  • インターフェースと​入出力の​データは​用意するが、​別の​パッケージや​モジュールには​分けない
  • 片側にだけ​インターフェースを置く
  • インターフェースを​置かず、​窓口の​クラスを 1 つ​置くだけにする

本には​第 26 章​『The Main Component』があり、​目次には​「The Ultimate Detail」と​いう​節が​あります。​この​記事では、​すべての​具体的な​部品を​作って​組み立てる​場所を Main と​呼びます。​実践編の composition-root.ts がこれに​当たります。

6. 設計の原則

本の目次では、​第 III 部​「Design Principles」​(SOLID の 5 つの​章) と​第 IV 部​「Component Principles」が、第 V 部​「Architecture」​の前に​置かれています。​同心円の​図だけを​取り出すと​根拠が​見えなくなるので、​Martin が​公開している​定義で​要点を​まとめます。

SOLID の 5 つ

Martin は 2020 年の​ブログ​「Solid Relevance」​で、5 つの​原則を 1 つずつ​短く​言い直しています。​下の​表の 2 列目は​その​記事からの​引用です。

原則 「Solid Relevance」​(2020) での言い方 クリーンアーキテクチャとの​関係 (この​記事の説明)
SRP 単一責任 Gather together the things that change for the same reasons. Separate things that change for different reasons. 層や部品を、​変わる​理由 (変更を​求める​人) で​分ける
OCP 開放閉鎖 A Module should be open for extension but closed for modification. 上位の​規則を、​下位の​詳細の​変更から​守る​向きに​依存を​並べる
LSP リスコフの置換 A program that uses an interface must not be confused by an implementation of that interface. Port の​どの​実装に​替えても​約束が​守られる
ISP インターフェース分離 Keep interfaces small so that users don’t end up depending on things they don’t need. Port を、​ユースケースが​要る​分だけにする
DIP 依存性逆転 Depend in the direction of abstraction. High level modules should not depend upon low level details. 境界の​越え方​そのもの

訳すと、​SRP は​「同じ​理由で​変わる​ものを​集め、​違う​理由で​変わる​ものを​分ける」、​OCP は​「モジュールは​拡張に​対して​開き、​修正に​対して​閉じる」、​LSP は​「インターフェースを​使う​プログラムが、​その​実装に​よって​混乱させられては​ならない」、​ISP は​「使わない​ものに​依存しないよう、​インターフェースを​小さく​保つ」、​DIP は​「抽象の​方向へ​依存する。​高い​レベルの​モジュールは​低い​レベルの​詳細に​依存しない」です。

補足です。

  • SRP:名前だけを​見ると​「1 つの​クラスは 1 つの​ことだけを​する」と​読めますが、​2014 年の​ブログの​説明は 2 章で​見た​とおり​「変更を​求める​人」の​話です。​同じ​ブログには​「each software module should have one and only one reason to change」​(どの​モジュールも、​変わる​理由は​ただ 1 つであるべきだ) と​いう​言い方も​あります
  • OCP:2014 年の​ブログ​「The Open Closed Principle」​によると、​1988 年に Bertrand Meyer が本『Object Oriented Software Construction』​で定義した​ものです
  • LSP:「Solid Relevance」は、これは​継承ではなく​部分型 (インターフェースと​その​実装) の​話で、​実装が​利用者を​混乱させると if 文や switch 文が増えていく、と​書いています。​実践編の​コードでは、​Repository のメモリ版と SQLite 版が同じ​約束を​守る​ことを、​同じ​テストで​確かめています (契約テスト)

本では、​第 7⁠〜​11 章が​それぞれ 1 つの​原則に​当てられています。

コンポーネントの​凝集:REP・​CCP・​CRP

Martin の​サイト butunclebob.com のページ​「The Principles of OOD」は、​SOLID の 5 つに​続けて、​パッケージに​ついての 6 つの​原則を 1 行ずつ​挙げています。​ここでの​パッケージは、​Java の​パッケージのような​名前空間ではなく、​.jar や DLL のような​配布の​単位を​指す、と​同じ​ページに​書かれています。​npm の​パッケージも、​この​意味に​近い​ものです。

最初の 3 つは、​何を 1 つの​パッケージに​まとめるかの​原則です (「The Principles of OOD」からの引用)。

  • REP (再利用・​リリース等価の原則):「The granule of reuse is the granule of release.」​再利用の​単位は、​リリースの​単位と同じ
  • CCP (閉鎖性共通の原則):「Classes that change together are packaged together.」​一緒に​変わる​クラスは、​同じ​パッケージに​まとめる
  • CRP (全再利用の原則):「Classes that are used together are packaged together.」​一緒に​使われる​クラスは、​同じ​パッケージに​まとめる

3 つの​関係は、​Martin の 2000 年の論文​「Design Principles and Design Patterns」​(Object Mentor の公開版。​Internet Archive に保存された​もので​確かめました) に​書かれています。​3 つは​同時には​満たせず、​REP と CRP は​再利用する​人を、​CCP は​保守する​人を​楽に​する。​CCP は​パッケージを​大きく​する​方向に、​CRP は​小さく​する​方向に​働く。​そのうえで、​こう​続けます。

Early in a project, architects may set up the package structure such that CCP dominates and develoipment and maintenance is aided. Later, as the architecture stabilizes, the architects may refactor the package structure to maximize REP and CRP for the external reusers.

(プロジェクトの​初めには、​CCP が​優位に​なるように​パッケージを​組み、​開発と​保守を​助ける​ことがある。​後で​アーキテクチャが​安定してきたら、​外部の​再利用者の​ために REP と CRP を​最大に​するよう組み直すことがある)

— 「Design Principles and Design Patterns」​(2000。​綴りは​原文のまま)

本には​第 13 章​『Component Cohesion』があり、​目次には​「The Tension Diagram for Component Cohesion」​という​節が​あります。

コンポーネントの​結合:​ADP・​SDP・​SAP

残りの 3 つは、​パッケージどうしの​依存に​ついての​原則です (「The Principles of OOD」からの引用)。

  • ADP (非循環依存関係の原則):「The dependency graph of packages must have no cycles.」​パッケージの​依存の​グラフに​循環が​あっては​ならない
  • SDP (安定依存の原則):「Depend in the direction of stability.」​安定している​方へ​依存する
  • SAP (安定度・​抽象度等価の原則):「Abstractness increases with stability.」​安定している​もの​ほど​抽象的にする

ここで​いう​「安定」は​「バグが​ない」ではなく​「変えにくい」と​いう​意味だ、​とこの​記事では​読みます。​多くの​ものから​依存されている​ものは、​変えると​影響が​大きいので​変えにくくなります。

Martin は、​C++ Report 誌の連載の 1 本​「Stability」​(Object Mentor の公開版。​Internet Archive で確かめました) で、​これを​測る​指標を​定義しています。

  • Ca (Afferent Couplings):​パッケージの​外に​あって、​中の​クラスに​依存している​クラスの数
  • Ce (Efferent Couplings):​パッケージの​中に​あって、​外の​クラスに​依存している​クラスの数
  • I (Instability、​不安定さ) = Ce ÷ (Ca + Ce)。0 が​最も​安定、​1 が​最も​不安定
  • A (Abstractness、​抽象度) = 抽象クラスの​数 ÷ クラスの総数

同じ論文は、​横軸に I、​縦軸に A を​とった​グラフで、​(0, 1) と (1, 0) を​結ぶ​線を、​天文学の​グラフに​似ている​ことから Main Sequence (メイン系列) と名付けています。​(0, 0) の​付近と (1, 1) の​付近は​どちらも​「zone of exclusion」​(避けるべき領域) です。線からの​距離 D は |(A + I − 1) ÷ √2⁠| で、範囲を 0⁠〜1 に​そろえた D′ = |A + I − 1⁠| も示されています。

(0, 0) の​付近に​ついて、​論文は 2 つの​例を​挙げています。​データベースの​スキーマは​変わりやすいのに​多くから​依存されているので​問題に​なる。​一方、​文字列の​クラスのような​具体的な​ユーティリティは、​変わりにくいので (0, 0) に​あっても​害はない。

本には​第 14 章​『Component Coupling』があり、​目次には​「The Acyclic Dependencies Principle」​「The Stable Dependencies Principle」​「The Stable Abstractions Principle」​の節が​あります。

7. よく​ある​誤解と​アンチパターン

この章の​「よく​ある」は、​この​記事の​見立てです。

層ごとの​フォルダを​作れば​完成、ではない

entities/・​use-cases/・​adapters/ のフォルダを​作っても、​Controller から Repository の実装を​直接 import できてしまえば、​依存性の​ルールは​守られていません。

Simon Brown は、自分の​サイトの​「Modular monolith and “package by component”」​のページで、​層ごと・​機能ごと・​Ports and Adapters・​コンポーネントごとの 4 つの​コードの​まとめ方を​比べています。​Java で​何でも public にする​習慣に​ついて、​言語の​カプセル化の​仕組みを​生かしていない、と​指摘し、​コンパイラで​アーキテクチャを​強制したい、と​書いています。​同じ​ページに​よると、​この​内容の​一つの​版が​本の​「The missing chapter」と​して​収められています (目次では​第 34 章​『The Missing Chapter』)。

DTO の​変換地獄

層ごとに​同じ​項目を​持つ型を​作り、​Entity → ユースケースの​出力 → View Model → JSON と、毎回​全項目を​写す。​よく​聞く​不満です。

Martin も 2011 年 11 月の​ブログで、​この​心配に​触れています。

nothing I have suggested would inevitably lead to repetition of data structures and an inordinate of field copying.

(私の提案した​ことの​中に、​データ構造の​重複や​過剰な​項目の​コピーに​必ずつながる​ものはない)

— 「Clean Architecture」​(2011 年 11 月の​ブログ)

2012 年の​ブログが​求めているのも​「境界を​越えるのは​内側に​都合の​よい​単純な​データ」と​いう​ことで、​境界を​越える​データは​関数の​引数でも​よい (Or the data can simply be arguments in function calls.) と書いています。​層ごとに​同じ形の​型を​作れ、とは​書いていません。

貧血ドメインモデル

Martin Fowler は 2003 年に、​ドメインの​オブジェクトが getter と setter の​入れ物 (bags of getters and setters) になり、​規則が​すべて​サービスの​側に​ある​状態を​「貧血ドメインモデル」​(Anemic Domain Model) と呼びました。​ドメインモデルの​コストを​払いながら、​その​利点を​何も​得ていない、と​いう​批判です (Fowler​「AnemicDomain​Model」)。

層を分けると、​これが​起きやすくなる、とこの​記事では​考えます。​Entities を​「表の​形を​した​型」と​考え、​規則を​ユースケースに​書いてしまうからです。

// よくない例 (この記事の例): 規則がユースケースに散らばり、Entity はただの入れ物
if (report.status !== 'submitted') return refuse('closed');
if (report.applicantId === approverId) return refuse('own-report');
const step = report.steps.find((s) => s.approvedAt === null);
if (step?.approverId !== approverId) return refuse('not-your-turn');
step.approvedAt = now;
if (report.steps.every((s) => s.approvedAt)) report.status = 'approved';

こう書くと、​差し戻しや​代理承認の​ユースケースを​作る​たびに​同じ if 文が​複製され、​どこか 1 つだけ直し忘れる、と​いう​ことが​起きます。​実践編の​コードでは、​規則は ExpenseReport.approve の中だけに​あり、​ユースケースは​結果を​見て​次の​手順を​決めるだけです。

ただし 2012 年の​ブログは、​Entity が​「データ構造と​関数の​組」でも​よいと​しています。​関数型の​スタイルで、​データと​規則の​関数を​分けて​書くのは​貧血ではありません。​問題は、​規則が Entities の​外 (ユースケースや Controller) に散らばる​ことです。

ユースケースの​肥大化と、​ユースケースどうしの​呼び出し

ExpenseService という 1 つの​クラスに、​申請・​承認・​差し戻し・​一覧・​CSV 出力の​メソッドが 30 個並ぶ。​これも​層の​名前だけを​借りた形です。​本では、​第 16 章​『Independence』​に「Decoupling Use Cases」と​いう​節が​あります。

データベースの扱い

Martin は 2016 年の​ブログ​「A Little Architecture」​で、データベースに​ついて​こう​書いています。

The database is merely an IO device.

(データベースは​入出力の​装置に​すぎない)

The business rules should not know what specific database you are using.

(業務の​規則は、​具体的に​どの​データベースを​使っているかを​知るべきではない)

— 「A Little Architecture」​(2016)

同じ対話の​中で、​業務の​規則が​データベースの​道具を​「使わない」とは​言っていない、​「依存すべきでない」​と言っている、とも​書いています。​本には​第 30 章​『The Database Is a Detail』が​あります。

Fowler は 2015 年の記事​「Presentation​Domain​DataLayering」​で、データアクセスを​差し替えられる​ことが層を​分ける​理由に​挙げられるのを​よく​聞くが、​実際に​差し替えた​話は​めったに​聞かない、と​書いています (I rarely hear of someone actually doing it.)。​データベースを​外側に​置く​利点は、​差し替えよりも、​規則を​データベースなしで​テストでき、​規則を​読む​ときに​データベースの​ことを​考えずに​済む点に​ある、と​考える​方が​実態に​合うと​この​記事では​考えます。

過剰設計

8. 批判と限界

主な批判

  • テストの​ための​設計の​歪み (2014):Ruby on Rails の作者 David Heinemeier Hansson は「Test-induced design damage」で、​テストを​速く、​単体で​書けるように​する​ために、​不要な​間接層と​概念の​負担 (needless indirection and conceptual overhead) を持ち込む​ことを​批判し、​ヘキサゴナルアーキテクチャを Rails に​当てはめた Jim Weirich の発表を​例に​挙げました。​Martin は 2 日後の​ブログ​「Test Induced Design Damage?」で、​これは​関心の​分離であって​歪みではないと​反論し、​David Parnas の 1972 年の​論文に​触れながら​「Things that change together you keep together. Things that change apart you keep apart.」​(一緒に​変わる​ものは​一緒に、​別々に​変わる​ものは​別々に) と​書いています
  • 層より​縦の​切れ端を (2018):Jimmy Bogard は「Vertical Slice Architecture」​で、層の​構成 (オニオンや​クリーンを​含む) は​典型的な​要求の​一部に​しか合わず、​モックが​多くなりがちで、​抽象に​すべきでない​ものまで​抽象にしがちだと​書きました。​代わりに​要求ごとの​縦の​切れ端で​まとめ、​「Minimize coupling between slices, and maximize coupling in a slice.」​(切れ端の​間の​結合は​小さく、​切れ端の​中の​結合は​大きく) する​ことを​勧めています
  • 保つのが​大変 (2016):Mark Seemann は「Functional architecture is Ports and Adapters」​で、オブジェクト指向で Ports and Adapters を実装する​ことを​「Sisyphean task」​(シーシュポスの​岩のような​終わらない​仕事) と​呼び、​少し​目を​離すと​元に​戻ってしまう、と​書いています
  • 差し替えは​めったに​起きない (2015):Fowler の​指摘は 7 章で​引いた​とおりです
  • 原典の​コードの​少なさ:Martin は 2011 年 11 月の​ブログで​「This sounds like a dogmatic rant, I want to see code.」​(独断的な​演説に​聞こえる。​コードを​見せてくれ) と​いう​声を​紹介し、​考え方は​難しくないので、​大量の​コードは​かえって​分かりにくくする、と​答えています。​図だけが​独り歩きして​解釈が​人に​よってばらばらに​なった​一因と​見る​こともできます (この​見方は​この​記事の​考えです)

実践編では、層に​分けた​版 (517 行) と、同じ​振る舞いを 1 つの​処理に​書いた​版 (41 行) を​並べて​比べています。​1 つの​ユースケースだけなら​行数の​差は​大きく、​規則と​変更が​少ないなら​後者の​方が​読みやすい​場面も​あります。

実務での​折り合い

9. まとめ

クリーンアーキテクチャの​中心は、​同心円の​図でも 4 つの​フォルダでもなく、​「ソースコードの​依存は​内側へだけ向ける」​という 1 つの​規則です。​業務の​規則を​内側に​置き、​Web や​データベースを​外側に​置き、​内から​外へ​呼ぶ所では​インターフェースを​内側に​置いて​向きを​逆にします。​その​根拠は、​変わる​理由で​分けると​いう SRP と、​安定した​方・抽象の​方へ​依存すると​いう SDP・​SAP・​DIP に​あります。​どこまで​厳密に​やるかは、​規則と​変更の​量を​見て​決めます。

コードで​確かめたい人は、​実践編へ​どうぞ。​経費精算の​「申請を​承認する」を TypeScript で作り、​24 件の​テストで​動きを​確かめ、​見直し用の​チェックリストも​置いています。

参考文献

URL は 2026 年 10 月 8 日に​開ける​ことを​確かめました。

Robert C. Martin のブログ・​記事 (本文を​確かめて​引用したもの)

Robert C. Martin の本 (目次で​章・節の​題名を​確かめたもの)

  • 『Clean Architecture: A Craftsman’s Guide to Software Structure and Design』​(Pearson, 2017。​ISBN 978-⁠0-⁠13-⁠449416-⁠6)。​出版社の目次
  • 邦訳『Clean Architecture 達人に​学ぶソフトウェアの​構造と​設計』(角征典・​高木正弘 訳)。​書誌の​データベースで ISBN 978-⁠4-⁠04-⁠893065-⁠9 (2018 年 7 月) と ISBN 978-⁠4-⁠04-⁠901203-⁠3 (ZEN大学出版会) を確認

先行する​考え方

関連する​考え方と批判