プログラミング

【初心者向け】プログラミングの「クリーンアーキテクチャ」入門

プログラミング初心者向けにクリーンアーキテクチャの基本概念、メリット、実装方法を分かりやすく解説。実例とともに学べる実践的なガイドです。

Learning Next 運営
約 72 分で読めます
クリーンアーキテクチャソフトウェア設計プログラミング初心者設計パターン保守性テスタビリティ

「コードが複雑になって、どこを修正すればいいかわからない」 「新機能を追加するたびに既存のコードが壊れる」 「テストが書きにくく、品質に不安がある」

これらの問題に悩んでいるプログラミング初心者の方は多いのではないでしょうか。

そんな課題を解決する強力な手法が「クリーンアーキテクチャ」です。

クリーンアーキテクチャは、ソフトウェアを保守しやすく、テストしやすく、変更に強い構造で設計するための原則とパターンです。本記事では、初心者の方でも理解できるよう、基本概念から実践的な実装まで、わかりやすく解説します。

クリーンアーキテクチャとは？

基本概念の理解

クリーンアーキテクチャは、Robert C. Martin（Uncle Bob）によって提唱されたソフトウェア設計の原則です。

その核心は「関心の分離」と「依存性の方向制御」にあります：

// クリーンアーキテクチャの基本原則
const cleanArchitecturePrinciples = {
    separation: {
        title: "関心の分離（Separation of Concerns）",
        description: "異なる責任を持つコードを別々の場所に配置",
        benefits: [
            "理解しやすいコード",
            "変更の影響範囲を限定",
            "再利用可能なコンポーネント",
            "テストの容易性"
        ],
        example: {
            bad: "UIとビジネスロジックとデータベースアクセスが混在",
            good: "それぞれを独立したレイヤーに分離"
        }
    },
    
    dependencyDirection: {
        title: "依存性の方向制御（Dependency Rule）",
        description: "外側のレイヤーから内側のレイヤーへの一方向依存",
        rule: "内側のレイヤーは外側のレイヤーを知らない",
        benefits: [
            "ビジネスロジックの独立性",
            "フレームワークからの独立",
            "データベースからの独立",
            "外部サービスからの独立"
        ]
    },
    
    testability: {
        title: "テスタビリティ",
        description: "各レイヤーを独立してテスト可能",
        features: [
            "ユニットテストの容易性",
            "モックオブジェクトの活用",
            "テスト実行速度の向上",
            "テストの信頼性向上"
        ]
    }
};

なぜクリーンアーキテクチャが必要なのか？

従来の問題とクリーンアーキテクチャの解決策：

// 従来アプローチ vs クリーンアーキテクチャ
const architectureComparison = {
    traditionalApproach: {
        structure: "レイヤー化アーキテクチャ（3層構造）",
        layers: ["UI層", "ビジネスロジック層", "データアクセス層"],
        problems: [
            {
                issue: "データベース中心設計",
                description: "データベーススキーマが設計の中心となる",
                consequences: [
                    "ビジネスロジックがSQLに依存",
                    "データベース変更でアプリ全体に影響",
                    "テストにデータベースが必要"
                ]
            },
            {
                issue: "フレームワーク依存",
                description: "特定のフレームワークに強く依存",
                consequences: [
                    "フレームワーク変更で大幅な修正",
                    "ビジネスルールがフレームワークに混在",
                    "技術的負債の蓄積"
                ]
            },
            {
                issue: "低いテスタビリティ",
                description: "各レイヤーが密結合",
                consequences: [
                    "ユニットテストが困難",
                    "テスト実行に時間がかかる",
                    "テストの信頼性が低い"
                ]
            }
        ]
    },
    
    cleanArchitecture: {
        structure: "同心円状のレイヤー構造",
        layers: ["エンティティ", "ユースケース", "インターフェース適合器", "フレームワーク&ドライバー"],
        solutions: [
            {
                solution: "ビジネスロジック中心設計",
                description: "ビジネスルールを中心に据える",
                benefits: [
                    "ドメイン知識の明確化",
                    "ビジネス要件変更への対応力",
                    "技術詳細からの独立"
                ]
            },
            {
                solution: "依存性逆転の原則",
                description: "抽象に依存し、具象に依存しない",
                benefits: [
                    "フレームワーク交換可能性",
                    "データベース交換可能性",
                    "外部サービス交換可能性"
                ]
            },
            {
                solution: "高いテスタビリティ",
                description: "各レイヤーを独立してテスト",
                benefits: [
                    "高速なユニットテスト",
                    "信頼性の高いテスト",
                    "テスト駆動開発の促進"
                ]
            }
        ]
    }
};

クリーンアーキテクチャの構造

4つのレイヤー構造

クリーンアーキテクチャは同心円状の4つのレイヤーで構成されます：

// クリーンアーキテクチャのレイヤー構造
class CleanArchitectureLayers {
    constructor() {
        this.layers = {
            entities: {
                name: "エンティティ（Entities）",
                position: "最内側",
                responsibility: "ビジネスの核となるルールとデータ",
                characteristics: [
                    "ビジネスルールの実装",
                    "最も変更されにくい部分",
                    "外部への依存なし",
                    "純粋なビジネスロジック"
                ],
                examples: ["User", "Product", "Order", "Account"]
            },
            
            useCases: {
                name: "ユースケース（Use Cases）",
                position: "内側から2番目",
                responsibility: "アプリケーション固有のビジネスルール",
                characteristics: [
                    "アプリケーションの機能定義",
                    "エンティティの操作",
                    "データフローの制御",
                    "ビジネスルールの適用"
                ],
                examples: ["RegisterUser", "PlaceOrder", "ProcessPayment", "SendNotification"]
            },
            
            interfaceAdapters: {
                name: "インターフェース適合器（Interface Adapters）",
                position: "外側から2番目",
                responsibility: "データフォーマットの変換",
                characteristics: [
                    "内側と外側のデータ変換",
                    "プレゼンテーション形式への変換",
                    "永続化形式への変換",
                    "外部サービス形式への変換"
                ],
                examples: ["Controllers", "Presenters", "Gateways", "Repositories"]
            },
            
            frameworksDrivers: {
                name: "フレームワーク&ドライバー（Frameworks & Drivers）",
                position: "最外側",
                responsibility: "具体的な技術詳細",
                characteristics: [
                    "Webフレームワーク",
                    "データベース",
                    "外部ライブラリ",
                    "デバイスドライバー"
                ],
                examples: ["Express.js", "React", "MySQL", "AWS SDK"]
            }
        };
    }
    
    // レイヤー間の依存関係ルール
    getDependencyRules() {
        return {
            rule: "依存の方向は内側向きのみ",
            forbidden: [
                "エンティティがユースケースを知ること",
                "ユースケースがコントローラーを知ること",
                "内側のレイヤーが外側のレイヤーを知ること"
            ],
            allowed: [
                "コントローラーがユースケースを知ること",
                "ユースケースがエンティティを知ること",
                "外側のレイヤーが内側のレイヤーを知ること"
            ],
            mechanism: "依存性逆転の原則（Dependency Inversion Principle）"
        };
    }
    
    // 実際の例での説明
    showPracticalExample() {
        const userManagement = {
            entity: {
                name: "User Entity",
                code: `
                class User {
                    constructor(id, name, email) {
                        this.id = id;
                        this.name = name;
                        this.email = email;
                    }
                    
                    // ビジネスルール: 有効なメールアドレスかチェック
                    isValidEmail() {
                        return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(this.email);
                    }
                    
                    // ビジネスルール: ユーザー情報の更新
                    updateProfile(name, email) {
                        if (!name || name.trim() === '') {
                            throw new Error('Name cannot be empty');
                        }
                        if (!this.isValidEmail(email)) {
                            throw new Error('Invalid email format');
                        }
                        this.name = name;
                        this.email = email;
                    }
                }`,
                description: "純粋なビジネスロジックのみ"
            },
            
            useCase: {
                name: "Register User Use Case",
                code: `
                class RegisterUserUseCase {
                    constructor(userRepository, emailService) {
                        this.userRepository = userRepository;
                        this.emailService = emailService;
                    }
                    
                    async execute(userData) {
                        // ビジネスルールの適用
                        const user = new User(null, userData.name, userData.email);
                        
                        // 重複チェック
                        const existingUser = await this.userRepository.findByEmail(userData.email);
                        if (existingUser) {
                            throw new Error('User already exists');
                        }
                        
                        // ユーザー保存
                        const savedUser = await this.userRepository.save(user);
                        
                        // ウェルカムメール送信
                        await this.emailService.sendWelcomeEmail(savedUser.email);
                        
                        return savedUser;
                    }
                }`,
                description: "アプリケーション固有のビジネスロジック"
            },
            
            controller: {
                name: "User Controller",
                code: `
                class UserController {
                    constructor(registerUserUseCase) {
                        this.registerUserUseCase = registerUserUseCase;
                    }
                    
                    async register(request, response) {
                        try {
                            // リクエストデータの取得
                            const userData = {
                                name: request.body.name,
                                email: request.body.email
                            };
                            
                            // ユースケースの実行
                            const user = await this.registerUserUseCase.execute(userData);
                            
                            // レスポンスの構築
                            response.status(201).json({
                                success: true,
                                data: {
                                    id: user.id,
                                    name: user.name,
                                    email: user.email
                                }
                            });
                        } catch (error) {
                            response.status(400).json({
                                success: false,
                                error: error.message
                            });
                        }
                    }
                }`,
                description: "Web APIとアプリケーションの橋渡し"
            }
        };
        
        console.log("=== クリーンアーキテクチャ実装例 ===");
        Object.entries(userManagement).forEach(([layer, details]) => {
            console.log(`
【${details.name}】`);
            console.log(details.description);
            console.log(details.code);
        });
        
        return userManagement;
    }
}

依存性逆転の原則

クリーンアーキテクチャの核心技術：

// 依存性逆転の実装例
class DependencyInversionExample {
    constructor() {
        this.concept = {
            problem: "高レベルモジュールが低レベルモジュールに依存",
            solution: "両方が抽象化に依存",
            technique: "インターフェース（抽象化）の活用"
        };
    }
    
    // 悪い例：直接依存
    showBadExample() {
        const badCode = `
        // 悪い例：ユースケースがMySQLに直接依存
        class RegisterUserUseCase {
            constructor() {
                this.mysql = new MySQL(); // 具体的な実装に依存
            }
            
            async execute(userData) {
                const user = new User(userData.name, userData.email);
                
                // MySQL固有のコードが混入
                const query = "INSERT INTO users (name, email) VALUES (?, ?)";
                await this.mysql.execute(query, [user.name, user.email]);
                
                return user;
            }
        }
        
        // 問題点：
        // 1. MySQLを変更すると、ユースケースも変更が必要
        // 2. テストにMySQLが必要
        // 3. ビジネスロジックに技術詳細が混入
        `;
        
        console.log("=== 悪い例：直接依存 ===");
        console.log(badCode);
        
        return badCode;
    }
    
    // 良い例：抽象化への依存
    showGoodExample() {
        const goodCode = `
        // 1. 抽象化（インターフェース）の定義
        class UserRepository {
            async save(user) {
                throw new Error('Must implement save method');
            }
            
            async findByEmail(email) {
                throw new Error('Must implement findByEmail method');
            }
        }
        
        // 2. ユースケース：抽象化に依存
        class RegisterUserUseCase {
            constructor(userRepository) {
                this.userRepository = userRepository; // 抽象化に依存
            }
            
            async execute(userData) {
                const user = new User(userData.name, userData.email);
                
                // 重複チェック
                const existingUser = await this.userRepository.findByEmail(user.email);
                if (existingUser) {
                    throw new Error('User already exists');
                }
                
                // ユーザー保存（具体的な実装は知らない）
                return await this.userRepository.save(user);
            }
        }
        
        // 3. 具体的な実装：抽象化を実装
        class MySQLUserRepository extends UserRepository {
            constructor(mysql) {
                super();
                this.mysql = mysql;
            }
            
            async save(user) {
                const query = "INSERT INTO users (name, email) VALUES (?, ?)";
                const result = await this.mysql.execute(query, [user.name, user.email]);
                user.id = result.insertId;
                return user;
            }
            
            async findByEmail(email) {
                const query = "SELECT * FROM users WHERE email = ?";
                const rows = await this.mysql.execute(query, [email]);
                return rows.length > 0 ? new User(rows[0].id, rows[0].name, rows[0].email) : null;
            }
        }
        
        // 4. 利用方法
        const mysql = new MySQL();
        const userRepository = new MySQLUserRepository(mysql);
        const registerUserUseCase = new RegisterUserUseCase(userRepository);
        
        // メリット：
        // 1. データベースを変更してもユースケースは不変
        // 2. テスト用のモックRepository作成が容易
        // 3. ビジネスロジックが純粋に保たれる
        `;
        
        console.log("=== 良い例：抽象化への依存 ===");
        console.log(goodCode);
        
        return goodCode;
    }
}

実践的な実装ガイド

1. 簡単なTodoアプリで学ぶ

段階的にクリーンアーキテクチャを実装：

Step 1: エンティティの定義

// Step 1: エンティティ（最内側レイヤー）
class Todo {
    constructor(id, title, description, completed = false, createdAt = new Date()) {
        this.id = id;
        this.title = title;
        this.description = description;
        this.completed = completed;
        this.createdAt = createdAt;
    }
    
    // ビジネスルール：タイトルの検証
    validateTitle() {
        if (!this.title || this.title.trim().length === 0) {
            throw new Error('Title cannot be empty');
        }
        if (this.title.length > 100) {
            throw new Error('Title cannot exceed 100 characters');
        }
    }
    
    // ビジネスルール：Todoの完了
    complete() {
        if (this.completed) {
            throw new Error('Todo is already completed');
        }
        this.completed = true;
        this.completedAt = new Date();
    }
    
    // ビジネスルール：Todoの未完了への変更
    uncomplete() {
        if (!this.completed) {
            throw new Error('Todo is not completed yet');
        }
        this.completed = false;
        this.completedAt = null;
    }
    
    // ビジネスルール：内容の更新
    update(title, description) {
        const updatedTodo = new Todo(this.id, title, description, this.completed, this.createdAt);
        updatedTodo.validateTitle();
        
        this.title = updatedTodo.title;
        this.description = updatedTodo.description;
        this.updatedAt = new Date();
    }
    
    // ビジネスルール：期限切れかどうか
    isOverdue(dueDate) {
        if (!dueDate) return false;
        return !this.completed && new Date() > dueDate;
    }
}


// エンティティのテスト例
class TodoEntityTest {
    static runTests() {
        console.log("=== Todo Entity Tests ===");
        
        // テスト1: 正常な作成
        try {
            const todo = new Todo(1, "Buy groceries", "Milk, Bread, Eggs");
            console.log("✓ Normal creation test passed");
        } catch (error) {
            console.log("✗ Normal creation test failed:", error.message);
        }
        
        // テスト2: 空のタイトルでエラー
        try {
            const todo = new Todo(2, "", "Empty title");
            todo.validateTitle();
            console.log("✗ Empty title test failed: Should throw error");
        } catch (error) {
            console.log("✓ Empty title test passed:", error.message);
        }
        
        // テスト3: 完了処理
        try {
            const todo = new Todo(3, "Test task", "For testing");
            todo.complete();
            console.log("✓ Complete test passed:", todo.completed);
        } catch (error) {
            console.log("✗ Complete test failed:", error.message);
        }
    }
}

Step 2: ユースケースの実装

// Step 2: ユースケース（アプリケーション層）
class CreateTodoUseCase {
    constructor(todoRepository, notificationService) {
        this.todoRepository = todoRepository;
        this.notificationService = notificationService;
    }
    
    async execute(todoData) {
        // 1. エンティティの作成とビジネスルールの適用
        const todo = new Todo(null, todoData.title, todoData.description);
        todo.validateTitle();
        
        // 2. 重複チェック（アプリケーション固有のルール）
        const existingTodos = await this.todoRepository.findByTitle(todoData.title);
        if (existingTodos.length > 0) {
            throw new Error('Todo with the same title already exists');
        }
        
        // 3. 永続化
        const savedTodo = await this.todoRepository.save(todo);
        
        // 4. 通知送信（アプリケーション固有の処理）
        if (todoData.sendNotification) {
            await this.notificationService.sendTodoCreated(savedTodo);
        }
        
        return savedTodo;
    }
}


class GetTodosUseCase {
    constructor(todoRepository) {
        this.todoRepository = todoRepository;
    }
    
    async execute(filters = {}) {
        let todos = await this.todoRepository.findAll();
        
        // フィルタリング（アプリケーション固有のロジック）
        if (filters.completed !== undefined) {
            todos = todos.filter(todo => todo.completed === filters.completed);
        }
        
        if (filters.overdue) {
            const now = new Date();
            todos = todos.filter(todo => todo.isOverdue(todo.dueDate));
        }
        
        // ソート（アプリケーション固有のロジック）
        if (filters.sortBy === 'createdAt') {
            todos.sort((a, b) => b.createdAt - a.createdAt);
        } else if (filters.sortBy === 'title') {
            todos.sort((a, b) => a.title.localeCompare(b.title));
        }
        
        return todos;
    }
}


class CompleteTodoUseCase {
    constructor(todoRepository, notificationService) {
        this.todoRepository = todoRepository;
        this.notificationService = notificationService;
    }
    
    async execute(todoId) {
        // 1. Todoの取得
        const todo = await this.todoRepository.findById(todoId);
        if (!todo) {
            throw new Error('Todo not found');
        }
        
        // 2. ビジネスルールの適用
        todo.complete();
        
        // 3. 更新の永続化
        const updatedTodo = await this.todoRepository.update(todo);
        
        // 4. 完了通知の送信
        await this.notificationService.sendTodoCompleted(updatedTodo);
        
        return updatedTodo;
    }
}

Step 3: インターフェース適合器の実装

// Step 3: インターフェース適合器
// 3-1: Repository Interface（抽象化）
class TodoRepository {
    async save(todo) {
        throw new Error('Must implement save method');
    }
    
    async findById(id) {
        throw new Error('Must implement findById method');
    }
    
    async findAll() {
        throw new Error('Must implement findAll method');
    }
    
    async findByTitle(title) {
        throw new Error('Must implement findByTitle method');
    }
    
    async update(todo) {
        throw new Error('Must implement update method');
    }
    
    async delete(id) {
        throw new Error('Must implement delete method');
    }
}


// 3-2: Notification Service Interface（抽象化）
class NotificationService {
    async sendTodoCreated(todo) {
        throw new Error('Must implement sendTodoCreated method');
    }
    
    async sendTodoCompleted(todo) {
        throw new Error('Must implement sendTodoCompleted method');
    }
}


// 3-3: Controller（Web API との適合器）
class TodoController {
    constructor(createTodoUseCase, getTodosUseCase, completeTodoUseCase) {
        this.createTodoUseCase = createTodoUseCase;
        this.getTodosUseCase = getTodosUseCase;
        this.completeTodoUseCase = completeTodoUseCase;
    }
    
    async createTodo(request, response) {
        try {
            // リクエストからデータを抽出
            const todoData = {
                title: request.body.title,
                description: request.body.description,
                sendNotification: request.body.sendNotification || false
            };
            
            // ユースケースの実行
            const todo = await this.createTodoUseCase.execute(todoData);
            
            // レスポンスの構築
            response.status(201).json({
                success: true,
                data: this.toResponseFormat(todo)
            });
        } catch (error) {
            this.handleError(error, response);
        }
    }
    
    async getTodos(request, response) {
        try {
            // クエリパラメータからフィルターを抽出
            const filters = {
                completed: request.query.completed ? 
                    request.query.completed === 'true' : undefined,
                overdue: request.query.overdue === 'true',
                sortBy: request.query.sortBy || 'createdAt'
            };
            
            // ユースケースの実行
            const todos = await this.getTodosUseCase.execute(filters);
            
            // レスポンスの構築
            response.json({
                success: true,
                data: todos.map(todo => this.toResponseFormat(todo)),
                count: todos.length
            });
        } catch (error) {
            this.handleError(error, response);
        }
    }
    
    async completeTodo(request, response) {
        try {
            const todoId = parseInt(request.params.id);
            
            // ユースケースの実行
            const todo = await this.completeTodoUseCase.execute(todoId);
            
            // レスポンスの構築
            response.json({
                success: true,
                data: this.toResponseFormat(todo)
            });
        } catch (error) {
            this.handleError(error, response);
        }
    }
    
    // エンティティをAPI レスポンス形式に変換
    toResponseFormat(todo) {
        return {
            id: todo.id,
            title: todo.title,
            description: todo.description,
            completed: todo.completed,
            createdAt: todo.createdAt.toISOString(),
            completedAt: todo.completedAt ? todo.completedAt.toISOString() : null
        };
    }
    
    // エラーハンドリング
    handleError(error, response) {
        console.error('Controller Error:', error);
        
        if (error.message.includes('not found')) {
            response.status(404).json({
                success: false,
                error: error.message
            });
        } else if (error.message.includes('already exists')) {
            response.status(409).json({
                success: false,
                error: error.message
            });
        } else {
            response.status(400).json({
                success: false,
                error: error.message
            });
        }
    }
}

Step 4: 具体的な実装（最外側レイヤー）

// Step 4: 具体的な実装（Infrastructure Layer）
// 4-1: MySQL Repository 実装
class MySQLTodoRepository extends TodoRepository {
    constructor(mysqlConnection) {
        super();
        this.mysql = mysqlConnection;
    }
    
    async save(todo) {
        const query = `
            INSERT INTO todos (title, description, completed, created_at)
            VALUES (?, ?, ?, ?)
        `;
        const values = [todo.title, todo.description, todo.completed, todo.createdAt];
        
        const result = await this.mysql.execute(query, values);
        todo.id = result.insertId;
        return todo;
    }
    
    async findById(id) {
        const query = 'SELECT * FROM todos WHERE id = ?';
        const rows = await this.mysql.execute(query, [id]);
        
        if (rows.length === 0) {
            return null;
        }
        
        return this.rowToTodo(rows[0]);
    }
    
    async findAll() {
        const query = 'SELECT * FROM todos ORDER BY created_at DESC';
        const rows = await this.mysql.execute(query);
        
        return rows.map(row => this.rowToTodo(row));
    }
    
    async findByTitle(title) {
        const query = 'SELECT * FROM todos WHERE title = ?';
        const rows = await this.mysql.execute(query, [title]);
        
        return rows.map(row => this.rowToTodo(row));
    }
    
    async update(todo) {
        const query = `
            UPDATE todos 
            SET title = ?, description = ?, completed = ?, completed_at = ?
            WHERE id = ?
        `;
        const values = [
            todo.title, 
            todo.description, 
            todo.completed, 
            todo.completedAt,
            todo.id
        ];
        
        await this.mysql.execute(query, values);
        return todo;
    }
    
    async delete(id) {
        const query = 'DELETE FROM todos WHERE id = ?';
        await this.mysql.execute(query, [id]);
    }
    
    // データベース行からTodoエンティティへの変換
    rowToTodo(row) {
        const todo = new Todo(
            row.id,
            row.title,
            row.description,
            row.completed === 1,
            row.created_at
        );
        
        if (row.completed_at) {
            todo.completedAt = row.completed_at;
        }
        
        return todo;
    }
}


// 4-2: Email Notification Service 実装
class EmailNotificationService extends NotificationService {
    constructor(emailService) {
        super();
        this.emailService = emailService;
    }
    
    async sendTodoCreated(todo) {
        const emailContent = {
            to: 'user@example.com',
            subject: 'New Todo Created',
            body: `A new todo "${todo.title}" has been created.`
        };
        
        await this.emailService.send(emailContent);
    }
    
    async sendTodoCompleted(todo) {
        const emailContent = {
            to: 'user@example.com',
            subject: 'Todo Completed',
            body: `Todo "${todo.title}" has been completed!`
        };
        
        await this.emailService.send(emailContent);
    }
}


// 4-3: 依存性注入とアプリケーション起動
class TodoApplication {
    constructor() {
        this.setupDependencies();
        this.setupRoutes();
    }
    
    setupDependencies() {
        // 外側から内側への依存関係を構築
        
        // Infrastructure Layer
        this.mysql = new MySQLConnection();
        this.emailService = new EmailService();
        
        // Interface Adapters Layer
        this.todoRepository = new MySQLTodoRepository(this.mysql);
        this.notificationService = new EmailNotificationService(this.emailService);
        
        // Use Cases Layer
        this.createTodoUseCase = new CreateTodoUseCase(
            this.todoRepository, 
            this.notificationService
        );
        this.getTodosUseCase = new GetTodosUseCase(this.todoRepository);
        this.completeTodoUseCase = new CompleteTodoUseCase(
            this.todoRepository, 
            this.notificationService
        );
        
        // Controllers Layer
        this.todoController = new TodoController(
            this.createTodoUseCase,
            this.getTodosUseCase,
            this.completeTodoUseCase
        );
    }
    
    setupRoutes() {
        const express = require('express');
        this.app = express();
        this.app.use(express.json());
        
        // REST API エンドポイント
        this.app.post('/todos', (req, res) => 
            this.todoController.createTodo(req, res));
        this.app.get('/todos', (req, res) => 
            this.todoController.getTodos(req, res));
        this.app.put('/todos/:id/complete', (req, res) => 
            this.todoController.completeTodo(req, res));
    }
    
    start(port = 3000) {
        this.app.listen(port, () => {
            console.log(`Todo API server running on port ${port}`);
        });
    }
}


// アプリケーション起動
const app = new TodoApplication();
app.start();

2. テストの実装

クリーンアーキテクチャのテスタビリティ：

// テスト実装例
class TodoUseCaseTest {
    constructor() {
        this.mockRepository = new MockTodoRepository();
        this.mockNotificationService = new MockNotificationService();
    }
    
    // モックオブジェクトの実装
    createMocks() {
        // Mock Repository
        class MockTodoRepository extends TodoRepository {
            constructor() {
                super();
                this.todos = [];
                this.nextId = 1;
            }
            
            async save(todo) {
                todo.id = this.nextId++;
                this.todos.push(todo);
                return todo;
            }
            
            async findById(id) {
                return this.todos.find(todo => todo.id === id) || null;
            }
            
            async findAll() {
                return [...this.todos];
            }
            
            async findByTitle(title) {
                return this.todos.filter(todo => todo.title === title);
            }
            
            async update(todo) {
                const index = this.todos.findIndex(t => t.id === todo.id);
                if (index !== -1) {
                    this.todos[index] = todo;
                }
                return todo;
            }
        }
        
        // Mock Notification Service
        class MockNotificationService extends NotificationService {
            constructor() {
                super();
                this.sentNotifications = [];
            }
            
            async sendTodoCreated(todo) {
                this.sentNotifications.push({
                    type: 'created',
                    todo: todo,
                    timestamp: new Date()
                });
            }
            
            async sendTodoCompleted(todo) {
                this.sentNotifications.push({
                    type: 'completed',
                    todo: todo,
                    timestamp: new Date()
                });
            }
        }
        
        return {
            mockRepository: new MockTodoRepository(),
            mockNotificationService: new MockNotificationService()
        };
    }
    
    // ユースケースのテスト
    async runTests() {
        console.log("=== Todo Use Case Tests ===");
        
        const { mockRepository, mockNotificationService } = this.createMocks();
        
        // テスト1: Todo作成の成功ケース
        await this.testCreateTodoSuccess(mockRepository, mockNotificationService);
        
        // テスト2: 重複Todoの作成エラー
        await this.testCreateTodoDuplicate(mockRepository, mockNotificationService);
        
        // テスト3: Todo完了の成功ケース
        await this.testCompleteTodoSuccess(mockRepository, mockNotificationService);
        
        // テスト4: 存在しないTodoの完了エラー
        await this.testCompleteTodoNotFound(mockRepository, mockNotificationService);
    }
    
    async testCreateTodoSuccess(mockRepository, mockNotificationService) {
        try {
            const useCase = new CreateTodoUseCase(mockRepository, mockNotificationService);
            const todoData = {
                title: "Test Todo",
                description: "Test Description",
                sendNotification: true
            };
            
            const result = await useCase.execute(todoData);
            
            // 検証
            if (result.id && result.title === "Test Todo") {
                console.log("✓ Create Todo Success Test Passed");
            } else {
                console.log("✗ Create Todo Success Test Failed");
            }
            
            // 通知が送信されたかチェック
            if (mockNotificationService.sentNotifications.length === 1) {
                console.log("✓ Notification Sent Test Passed");
            } else {
                console.log("✗ Notification Sent Test Failed");
            }
            
        } catch (error) {
            console.log("✗ Create Todo Success Test Failed:", error.message);
        }
    }
    
    async testCreateTodoDuplicate(mockRepository, mockNotificationService) {
        try {
            const useCase = new CreateTodoUseCase(mockRepository, mockNotificationService);
            
            // 同じタイトルのTodoを2回作成
            await useCase.execute({ title: "Duplicate Todo", description: "First" });
            await useCase.execute({ title: "Duplicate Todo", description: "Second" });
            
            console.log("✗ Create Todo Duplicate Test Failed: Should throw error");
        } catch (error) {
            if (error.message.includes('already exists')) {
                console.log("✓ Create Todo Duplicate Test Passed");
            } else {
                console.log("✗ Create Todo Duplicate Test Failed:", error.message);
            }
        }
    }
    
    async testCompleteTodoSuccess(mockRepository, mockNotificationService) {
        try {
            // 前準備：Todoを作成
            const createUseCase = new CreateTodoUseCase(mockRepository, mockNotificationService);
            const todo = await createUseCase.execute({ 
                title: "Complete Me", 
                description: "Test completion" 
            });
            
            // 完了テスト
            const completeUseCase = new CompleteTodoUseCase(mockRepository, mockNotificationService);
            const result = await completeUseCase.execute(todo.id);
            
            if (result.completed) {
                console.log("✓ Complete Todo Success Test Passed");
            } else {
                console.log("✗ Complete Todo Success Test Failed");
            }
            
        } catch (error) {
            console.log("✗ Complete Todo Success Test Failed:", error.message);
        }
    }
    
    async testCompleteTodoNotFound(mockRepository, mockNotificationService) {
        try {
            const useCase = new CompleteTodoUseCase(mockRepository, mockNotificationService);
            await useCase.execute(999); // 存在しないID
            
            console.log("✗ Complete Todo Not Found Test Failed: Should throw error");
        } catch (error) {
            if (error.message.includes('not found')) {
                console.log("✓ Complete Todo Not Found Test Passed");
            } else {
                console.log("✗ Complete Todo Not Found Test Failed:", error.message);
            }
        }
    }
}


// テストの実行
const test = new TodoUseCaseTest();
test.runTests();

クリーンアーキテクチャのメリット

1. 保守性の向上

変更に強いコード構造：

// 保守性向上の具体例
const maintainabilityBenefits = {
    changeIsolation: {
        example: "データベースをMySQLからPostgreSQLに変更",
        traditionalApproach: {
            impact: "アプリケーション全体に影響",
            changes: [
                "SQLクエリの書き換え",
                "データ型の調整", 
                "ビジネスロジックの修正",
                "テストの大幅な変更"
            ],
            effort: "数週間〜数ヶ月"
        },
        cleanArchitecture: {
            impact: "Repositoryの実装のみ",
            changes: [
                "PostgreSQLRepositoryの新規作成",
                "DIコンテナの設定変更のみ"
            ],
            effort: "数日",
            unaffectedLayers: [
                "エンティティ（ビジネスロジック）",
                "ユースケース（アプリケーションロジック）",
                "コントローラー（APIレイヤー）"
            ]
        }
    },
    
    businessLogicClarity: {
        benefit: "ビジネスロジックの明確化",
        examples: [
            {
                scenario: "割引計算ロジックの変更",
                location: "Entityクラスのメソッド",
                impact: "他のレイヤーに影響なし",
                testability: "ユニットテストで確実に検証"
            },
            {
                scenario: "新しい承認フローの追加",
                location: "UseCase クラス",
                impact: "UIやデータベースに影響なし",
                testability: "モックを使った高速テスト"
            }
        ]
    },
    
    teamCollaboration: {
        benefit: "チーム開発の効率化",
        advantages: [
            "レイヤーごとの並行開発",
            "専門分野での分業",
            "影響範囲の明確化",
            "コードレビューの焦点化"
        ]
    }
};

2. テスタビリティの向上

効率的で信頼性の高いテスト：

// テスタビリティの向上例
class TestabilityDemonstration {
    showTestingStrategy() {
        return {
            unitTesting: {
                target: "個別のエンティティとユースケース",
                characteristics: [
                    "高速実行（データベース不要）",
                    "独立性（他のコンポーネントに依存しない）",
                    "確実性（外部要因の影響なし）",
                    "網羅性（全てのケースをカバー可能）"
                ],
                example: `
                // エンティティのテスト
                test('Todo should not allow empty title', () => {
                    expect(() => {
                        new Todo(1, '', 'description');
                    }).toThrow('Title cannot be empty');
                });
                
                // ユースケースのテスト（モック使用）
                test('Should create todo successfully', async () => {
                    const mockRepo = new MockTodoRepository();
                    const mockNotification = new MockNotificationService();
                    const useCase = new CreateTodoUseCase(mockRepo, mockNotification);
                    
                    const result = await useCase.execute({
                        title: 'Test Todo',
                        description: 'Test Description'
                    });
                    
                    expect(result.title).toBe('Test Todo');
                    expect(mockRepo.savedTodos).toHaveLength(1);
                });`
            },
            
            integrationTesting: {
                target: "レイヤー間の連携",
                characteristics: [
                    "実際のデータベース使用",
                    "APIエンドポイントのテスト",
                    "実際のフローの確認",
                    "パフォーマンステスト"
                ],
                example: `
                // 統合テスト
                test('POST /todos should create and return todo', async () => {
                    const response = await request(app)
                        .post('/todos')
                        .send({
                            title: 'Integration Test Todo',
                            description: 'Testing full flow'
                        });
                    
                    expect(response.status).toBe(201);
                    expect(response.body.success).toBe(true);
                    expect(response.body.data.title).toBe('Integration Test Todo');
                });`
            },
            
            testPyramid: {
                structure: [
                    {
                        layer: "Unit Tests",
                        quantity: "多数（70%）",
                        scope: "エンティティ、ユースケース",
                        execution: "高速"
                    },
                    {
                        layer: "Integration Tests", 
                        quantity: "中程度（20%）",
                        scope: "レイヤー間連携",
                        execution: "中速"
                    },
                    {
                        layer: "E2E Tests",
                        quantity: "少数（10%）",
                        scope: "全体フロー",
                        execution: "低速"
                    }
                ]
            }
        };
    }
}

3. 柔軟性と拡張性

変化する要求への対応力：

// 柔軟性・拡張性の例
const flexibilityExamples = {
    frameworkIndependence: {
        scenario: "WebフレームワークをExpressからFastifyに変更",
        impact: "Controllerレイヤーのみ",
        steps: [
            "FastifyControllerクラスの作成",
            "ルーティング設定の変更",
            "リクエスト/レスポンス処理の調整"
        ],
        unchanged: [
            "ビジネスロジック（エンティティ）",
            "アプリケーションロジック（ユースケース）",
            "データアクセス（リポジトリ）"
        ]
    },
    
    multipleInterfaces: {
        scenario: "REST API に加えて GraphQL API を提供",
        implementation: `
        // 既存のREST Controller
        class TodoRestController {
            constructor(useCases) {
                this.useCases = useCases;
            }
            
            async createTodo(req, res) {
                const result = await this.useCases.createTodo.execute(req.body);
                res.json(result);
            }
        }
        
        // 新規のGraphQL Resolver
        class TodoGraphQLResolver {
            constructor(useCases) {
                this.useCases = useCases; // 同じユースケースを再利用
            }
            
            async createTodo(parent, args, context) {
                return await this.useCases.createTodo.execute(args.input);
            }
        }
        
        // 両方とも同じビジネスロジックを使用
        `,
        benefits: [
            "コードの重複なし",
            "一貫したビジネスロジック",
            "保守コストの削減"
        ]
    },
    
    scalability: {
        microservices: {
            transition: "モノリスからマイクロサービスへの分割",
            strategy: "ユースケース単位での分割",
            example: [
                "UserManagementService（ユーザー関連ユースケース）",
                "TodoManagementService（Todo関連ユースケース）",
                "NotificationService（通知関連ユースケース）"
            ],
            advantages: [
                "独立したデプロイメント",
                "技術スタックの選択自由度",
                "チーム単位でのオーナーシップ"
            ]
        }
    }
};

よくある間違いと注意点

1. 過度な抽象化

適切な抽象化レベルの判断：

// 過度な抽象化の例と対策
const abstraction_pitfalls = {
    overEngineering: {
        problem: "小さなアプリケーションでの過度な抽象化",
        badExample: `
        // 悪い例：シンプルなCRUDアプリでの過度な抽象化
        
        // 不要に複雑な抽象化
        interface IEntityValidator<T> {
            validate(entity: T): ValidationResult;
        }
        
        interface IEntityFactory<T> {
            create(data: any): T;
        }
        
        interface IEntityMapper<T, U> {
            mapToEntity(dto: T): U;
            mapToDto(entity: U): T;
        }
        
        // わずか3つのフィールドを持つシンプルなUserエンティティに
        // 過度な抽象化を適用
        class UserValidator implements IEntityValidator<User> { ... }
        class UserFactory implements IEntityFactory<User> { ... }
        class UserMapper implements IEntityMapper<UserDto, User> { ... }
        `,
        
        betterApproach: `
        // 良い例：適切なレベルの抽象化
        
        class User {
            constructor(id, name, email) {
                this.id = id;
                this.name = name;
                this.email = email;
                this.validate(); // シンプルな検証
            }
            
            validate() {
                if (!this.name || !this.email) {
                    throw new Error('Name and email are required');
                }
            }
        }
        
        class UserRepository {
            async save(user) { /* 実装 */ }
            async findById(id) { /* 実装 */ }
        }
        
        class CreateUserUseCase {
            constructor(userRepository) {
                this.userRepository = userRepository;
            }
            
            async execute(userData) {
                const user = new User(null, userData.name, userData.email);
                return await this.userRepository.save(user);
            }
        }
        `,
        
        guidelines: [
            "YAGNIの原則（You Aren't Gonna Need It）を適用",
            "実際の要件に基づいた設計",
            "段階的な複雑化",
            "チームのスキルレベルに合わせた抽象化"
        ]
    },
    
    wrongLayerDependencies: {
        problem: "依存関係ルールの違反",
        badExample: `
        // 悪い例：内側のレイヤーが外側のレイヤーに依存
        
        class User {
            constructor(id, name, email) {
                this.id = id;
                this.name = name;
                this.email = email;
            }
            
            // 悪い：エンティティがコントローラーを知っている
            sendWelcomeEmail() {
                const emailController = new EmailController();
                emailController.sendEmail(this.email, 'Welcome!');
            }
        }
        
        class CreateUserUseCase {
            async execute(userData) {
                const user = new User(null, userData.name, userData.email);
                
                // 悪い：ユースケースがHTTPレスポンスを知っている
                const response = {
                    status: 201,
                    body: { id: user.id, name: user.name }
                };
                
                return response;
            }
        }
        `,
        
        goodExample: `
        // 良い例：正しい依存関係
        
        class User {
            constructor(id, name, email) {
                this.id = id;
                this.name = name;
                this.email = email;
            }
            
            // エンティティは純粋なビジネスロジックのみ
            isValidEmail() {
                return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(this.email);
            }
        }
        
        class CreateUserUseCase {
            constructor(userRepository, emailService) {
                this.userRepository = userRepository;
                this.emailService = emailService; // 抽象化に依存
            }
            
            async execute(userData) {
                const user = new User(null, userData.name, userData.email);
                const savedUser = await this.userRepository.save(user);
                
                // メール送信（抽象化経由）
                await this.emailService.sendWelcomeEmail(savedUser.email);
                
                return savedUser; // エンティティを返す
            }
        }
        `,
        
        rules: [
            "内側のレイヤーは外側のレイヤーを知らない",
            "エンティティは他のどのレイヤーにも依存しない",
            "ユースケースは抽象化（インターフェース）にのみ依存",
            "具体的な実装は最外側レイヤーに配置"
        ]
    }
};

2. 初心者が陥りやすい間違い

段階的な学習アプローチ：

// 初心者向けのベストプラクティス
const beginnerGuidelines = {
    learningPath: {
        step1: {
            focus: "エンティティの理解",
            practice: [
                "純粋なクラスでビジネスルールを実装",
                "外部依存なしでのロジック作成",
                "ユニットテストの作成"
            ],
            example: `
            // まずはシンプルなエンティティから始める
            class BankAccount {
                constructor(accountNumber, balance) {
                    this.accountNumber = accountNumber;
                    this.balance = balance;
                }
                
                withdraw(amount) {
                    if (amount <= 0) {
                        throw new Error('Amount must be positive');
                    }
                    if (amount > this.balance) {
                        throw new Error('Insufficient funds');
                    }
                    this.balance -= amount;
                }
                
                deposit(amount) {
                    if (amount <= 0) {
                        throw new Error('Amount must be positive');
                    }
                    this.balance += amount;
                }
            }
            `
        },
        
        step2: {
            focus: "ユースケースの実装",
            practice: [
                "エンティティを使った操作の組み合わせ",
                "抽象的なリポジトリの定義",
                "モックを使ったテスト"
            ],
            example: `
            // ユースケース：振込処理
            class TransferMoneyUseCase {
                constructor(accountRepository) {
                    this.accountRepository = accountRepository;
                }
                
                async execute(fromAccountId, toAccountId, amount) {
                    const fromAccount = await this.accountRepository.findById(fromAccountId);
                    const toAccount = await this.accountRepository.findById(toAccountId);
                    
                    fromAccount.withdraw(amount);
                    toAccount.deposit(amount);
                    
                    await this.accountRepository.save(fromAccount);
                    await this.accountRepository.save(toAccount);
                    
                    return { fromAccount, toAccount };
                }
            }
            `
        },
        
        step3: {
            focus: "インターフェース適合器",
            practice: [
                "抽象化の具体的な実装",
                "外部システムとの連携",
                "データ変換の実装"
            ]
        },
        
        step4: {
            focus: "全体統合",
            practice: [
                "依存性注入の実装",
                "設定の外部化",
                "エラーハンドリングの統一"
            ]
        }
    },
    
    commonMistakes: [
        {
            mistake: "すべてを一度に実装しようとする",
            solution: "段階的な実装とテスト"
        },
        {
            mistake: "抽象化を恐れて具象クラスに直接依存",
            solution: "インターフェースの積極的な活用"
        },
        {
            mistake: "テストを後回しにする",
            solution: "TDD（テスト駆動開発）の実践"
        },
        {
            mistake: "完璧を求めすぎる",
            solution: "動くソフトウェアを優先し、徐々に改善"
        }
    ]
};

まとめ

クリーンアーキテクチャについて重要なポイント：

クリーンアーキテクチャの本質

核心原則

  • 関心の分離: 異なる責任を持つコードの分離
  • 依存性の方向制御: 内側向きの一方向依存
  • 抽象化への依存: 具象ではなく抽象に依存
  • テスタビリティ: 各レイヤーの独立したテスト

4つのレイヤー

  • エンティティ: ビジネスの核となるルールとデータ
  • ユースケース: アプリケーション固有のビジネスルール
  • インターフェース適合器: データフォーマットの変換
  • フレームワーク&ドライバー: 具体的な技術詳細

実践的なメリット

保守性の向上

  • 変更の局所化: 影響範囲の限定
  • ビジネスロジックの明確化: 要件変更への対応力
  • 技術的負債の削減: 持続可能な開発
  • チーム開発の効率化: 並行開発の促進

品質の向上

  • 高いテスタビリティ: 信頼性の高いソフトウェア
  • バグの早期発見: ユニットテストによる品質保証
  • リファクタリングの安全性: 構造的な変更の容易さ
  • コードの理解しやすさ: 新メンバーのオンボーディング向上

学習と導入のアプローチ

段階的な習得

  • エンティティから開始: 純粋なビジネスロジックの実装
  • ユースケースの追加: アプリケーション固有の操作
  • 抽象化の導入: インターフェースと実装の分離
  • 全体統合: 依存性注入と設定管理

適用判断

  • プロジェクト規模: 適切な抽象化レベルの選択
  • チームスキル: 段階的な導入と学習
  • 要件の複雑さ: コストと利益のバランス
  • 長期的視点: 保守性とスケーラビリティの重視

クリーンアーキテクチャは、保守しやすく、テストしやすく、変更に強いソフトウェアを作るための強力な指針です。

完璧を目指さず、段階的に学習し、プロジェクトの実情に合わせて適用することで、長期的に価値のあるソフトウェアを構築できます。今日から小さなプロジェクトで実践してみてください。

関連記事

アグリテックエンジニア - 農業×技術の可能性

農業とテクノロジーを融合させるアグリテックエンジニアの仕事内容、必要なスキル、キャリアパスを解説。IoT、AI、ドローンなどの最新技術で農業の課題を解決する新しい職種の魅力をお伝えします。

2025年7月5日
10分

【初心者向け】プログラミングの「GraphQL」vs「REST」

GraphQLとRESTの違いを初心者にもわかりやすく解説。API設計の基本から実際の使い分け方まで、具体例を交えて詳しく説明します

2025年7月5日
18分

【初心者向け】プログラミングの「非同期通信」なぜ難しい？

プログラミング初心者が非同期通信で躓く理由を分析。同期処理との違い、コールバック地獄、Promise、async/awaitまで段階的に解説し、理解しやすい学習方法を紹介します。

2025年7月5日
16分