クリーンアーキテクチャの理論編:原典で確かめる依存性のルール
クリーンアーキテクチャは、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)
「知る」とは何かも具体的に書かれています。外側で宣言されたものの名前 (関数・クラス・変数など) を内側のコードに書かないこと。外側で使うデータの形式、特に外側のフレームワークが作る形式を、内側で使わないこと。
元のブログの図では、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 を直接呼ぶと、内側が外側の名前を書くことになり、依存性のルールに反します。
- ソースコードの依存 (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「AnemicDomainModel」)。
層を分けると、これが起きやすくなる、とこの記事では考えます。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 年の記事「PresentationDomainDataLayering」で、データアクセスを差し替えられることが層を分ける理由に挙げられるのをよく聞くが、実際に差し替えた話はめったに聞かない、と書いています (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 のブログ・記事 (本文を確かめて引用したもの)
- The Clean Architecture (2012-08-13)
- Screaming Architecture (2011-09-30)
- Clean Architecture (2011-11-22)
- Test Induced Design Damage? (2014-05-01)
- The Single Responsibility Principle (2014-05-08)
- The Open Closed Principle (2014-05-12)
- Clean Micro-service Architecture (2014-10-01)
- A Little Architecture (2016-01-04)
- Too Clean? (2018-08-13)
- Solid Relevance (2020-10-18)
- The Principles of OOD (butunclebob.com)
- Design Principles and Design Patterns (2000。Object Mentor の公開版を Internet Archive で閲覧)
- Stability (C++ Report の連載「Engineering Notebook」の 1 本。Object Mentor の公開版を Internet Archive で閲覧)
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大学出版会) を確認
先行する考え方
- Alistair Cockburn, Hexagonal architecture (2005)
- Jeffrey Palermo, The Onion Architecture : part 1 (2008-07-29)
- Trygve Reenskaug, James O. Coplien, The DCI Architecture: A New Vision of Object-Oriented Programming (Artima, 2009-03-20)
- Entity–control–boundary (英語版 Wikipedia。BCE の説明に使用)
関連する考え方と批判
- Martin Fowler, Repository (Patterns of Enterprise Application Architecture のカタログ)
- Martin Fowler, Evans Classification
- Martin Fowler, Anemic Domain Model (2003-11-25)
- Martin Fowler, Presentation Domain Data Layering (2015-08-26)
- Gerard Meszaros, Humble Object (xUnitPatterns.com)
- Simon Brown, Modular monolith and “package by component”
- David Heinemeier Hansson, Test-induced design damage (2014-04-29)
- Mark Seemann, Functional architecture is Ports and Adapters (2016-03-18)
- Jimmy Bogard, Vertical Slice Architecture (2018-04-19)