【Clean Architecture】Entities（エンティティ）

はじめに

Clean Architecture における Entities（エンティティ） は、システムの中心に位置する存在です。
エンティティは ビジネスルールの最も基本的な表現 であり、システムが解決すべき問題の「本質」を形にします。

---

1. エンティティとは何か

• ビジネスルールの中核を表すオブジェクト
• 長期的に変わらないルールを保持
• フレームワークや技術詳細に依存しない
• システム外（紙の業務や人間の手作業）でも成立するルール

例:

• 銀行システムの「口座（Account）」
• ECサイトの「注文（Order）」
• SNSの「ユーザー（User）」

---

2. エンティティの役割

1. 不変のビジネスロジックを保持
   • 「口座残高はマイナスになってはならない」
   • 「在庫がゼロなら購入できない」
2. ユースケースやフレームワークから独立
   • APIやDB、UIに依存しない
   • 技術の変化からビジネスルールを守る
3. テスト容易性
   • 外部リソース不要で単体テスト可能

---

3. エンティティの例（Kotlin）

// 銀行口座を表すエンティティ
data class Account(
    val id: String,
    private var balance: Int
) {
    fun deposit(amount: Int) {
        require(amount > 0) { "入金額は正の値でなければならない" }
        balance += amount
    }

    fun withdraw(amount: Int) {
        require(amount > 0) { "出金額は正の値でなければならない" }
        if (balance - amount < 0) {
            throw IllegalStateException("残高不足")
        }
        balance -= amount
    }

    fun getBalance(): Int = balance
}

この Account エンティティは DBやUIに依存せず、純粋にビジネスルールを表現しています。

---

4. エンティティとユースケースの違い

• エンティティ
  • 普遍的なビジネスルール
  • システム外でも成立するルール
• ユースケース
  • システム固有のルール
  • ユーザーとシステムのやりとりに特化

例：

• エンティティ: 「残高がマイナスの時は出金できない」
• ユースケース: 「ATMからの出金処理を行い、トランザクション履歴を保存する」

---

5. 図解：エンティティの位置づけ

Entities は最も内側 にあり、外部技術の変化から守られる。

---

まとめ

• Entities = ビジネスルールの核
• 技術詳細やユースケースから独立して存在する
• 長期的に変わらないため、アーキテクチャの中心に置くべき

エンティティは「Screaming Architecture」で言うところの システムの意図を叫ぶ存在 であり、
その設計こそがソフトウェアの生命力を決めます。