はじめに

ソフトウェア開発において、クリーンアーキテクチャは保守性、拡張性、テスト容易性を高めるための設計手法として広く認識されています。

本記事では、クリーンアーキテクチャの基本概念を深掘りし、Go言語とEchoフレームワークを使用して実装する方法を詳しく解説します。
コード例には豊富なコメントを付けて、各部分の役割を明確にします。

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

クリーンアーキテクチャは、ロバート・C・マーチン（通称：アンクルボブ）によって提唱されたソフトウェア設計のパターンです。
主な目的は、依存関係の方向性を明確にし、システムの各層が独立して開発・テスト・保守できるようにすることです。
これにより、システム全体の柔軟性と拡張性が向上します。

クリーンアーキテクチャの原則

クリーンアーキテクチャは、以下の5つの主要な原則に基づいています。

依存関係の逆転（Dependency Rule）
外側の層が内側の層に依存し、内側の層は外側の層について知りません。
具体的には、エンティティやユースケースはインフラストラクチャやフレームワークに依存しません。
エンティティ（Entities）
ビジネスルールやオブジェクトを表現します。
アプリケーション全体で共有され、他の層からも利用されます。
ユースケース（Use Cases）
アプリケーション固有のビジネスロジックを実装します。
エンティティを操作し、外部からの要求を処理します。
インターフェースアダプター（Interface Adapters）
データの変換やフレームワークとの橋渡しを行います。
例として、Webハンドラーやリポジトリの実装が含まれます。
フレームワークとドライバ（Frameworks and Drivers）
データベース、Webフレームワーク、外部サービスなど、具体的な技術スタックが含まれます。
これらは外側の層として扱われ、内側の層に依存しません。

これらの原則に従うことで、システムの各層が疎結合となり、変更に強い構造を実現できます。

GoとEchoでの実装

では、Go言語とEchoフレームワークを使用して、クリーンアーキテクチャを実装する具体的な手順を見ていきましょう。
ここでは、ユーザー管理を例にシンプルなAPIを構築します。

プロジェクト構成

まず、プロジェクトのディレクトリ構成を以下のように整理します。

/myapp
├── cmd
│   └── server
│       └── main.go
├── internal
│   ├── delivery
│   │   └── http
│   │       └── handler.go
│   ├── repository
│   │   └── user_repository.go
│   ├── usecase
│   │   └── user_usecase.go
│   └── entity
│       └── user.go
├── pkg
│   └── db
│       └── db.go
├── go.mod
└── go.sum

cmd/server/main.go: アプリケーションのエントリーポイント。
internal/entity: ビジネスエンティティの定義。
internal/repository: データアクセスのインターフェースと実装。
internal/usecase: ビジネスロジックの実装。
internal/delivery/http: HTTPハンドラーの実装。
pkg/db: データベース接続や設定。

エンティティ（Entity）

エンティティはビジネスルールの中心であり、システム全体で共有されます。
ここでは、Userエンティティを定義します。

// internal/entity/user.go
package entity

// User はユーザー情報を表すエンティティです。
type User struct {
    ID    int    `json:"id"`    // ユーザーID
    Name  string `json:"name"`  // ユーザー名
    Email string `json:"email"` // ユーザーのメールアドレス
}

ポイント:

構造体にJSONタグを付与することで、JSONとの相互変換を容易にします。
エンティティはビジネスロジックに必要な属性のみを持ち、外部の詳細には依存しません。

リポジトリ（Repository）

リポジトリはデータアクセスのインターフェースを定義し、具体的な実装はインフラストラクチャ層で行います。
ここでは、ユーザーに関する操作を定義します。

// internal/repository/user_repository.go
package repository

import "myapp/internal/entity"

// UserRepository はユーザーに関するデータアクセス操作を定義するインターフェースです。
type UserRepository interface {
    // GetByID は指定されたIDのユーザーを取得します。
    GetByID(id int) (*entity.User, error)
    
    // Create は新しいユーザーを作成します。
    Create(user *entity.User) error
}

次に、メモリ上にユーザーを管理する簡易的な実装を追加します。

// internal/repository/user_repository.go
package repository

import (
    "errors"
    "myapp/internal/entity"
    "sync"
)

// InMemoryUserRepository はメモリ上でユーザーを管理するリポジトリの実装です。
type InMemoryUserRepository struct {
    users map[int]*entity.User // ユーザーをIDで管理するマップ
    mu    sync.RWMutex        // 並行アクセスを制御するためのミューテックス
}

// NewInMemoryUserRepository は InMemoryUserRepository の新しいインスタンスを返します。
func NewInMemoryUserRepository() *InMemoryUserRepository {
    return &InMemoryUserRepository{
        users: make(map[int]*entity.User),
    }
}

// GetByID は指定されたIDのユーザーを取得します。
func (r *InMemoryUserRepository) GetByID(id int) (*entity.User, error) {
    r.mu.RLock()         // 読み取り時にロック
    defer r.mu.RUnlock() // 関数終了時にロック解除

    user, exists := r.users[id]
    if !exists {
        return nil, errors.New("user not found")
    }
    return user, nil
}

// Create は新しいユーザーを作成します。
func (r *InMemoryUserRepository) Create(user *entity.User) error {
    r.mu.Lock()         // 書き込み時にロック
    defer r.mu.Unlock() // 関数終了時にロック解除

    // 新しいIDを生成（単純に現在のマップサイズ + 1）
    user.ID = len(r.users) + 1
    r.users[user.ID] = user
    return nil
}

ポイント:

UserRepository インターフェースにより、データアクセスの具体的な実装を抽象化します。
InMemoryUserRepository はテストや開発時に便利なメモリ上の実装です。実際のアプリケーションでは、データベース接続を用いた実装に置き換えます。
sync.RWMutex を使用して、並行アクセス時のデータ整合性を確保します。

ユースケース（Usecase）

ユースケース層は、アプリケーション固有のビジネスロジックを実装します。
リポジトリを利用してデータ操作を行います。

// internal/usecase/user_usecase.go
package usecase

import (
    "myapp/internal/entity"
    "myapp/internal/repository"
)

// UserUsecase はユーザーに関するビジネスロジックを実装します。
type UserUsecase struct {
    Repo repository.UserRepository // ユーザーリポジトリへの依存
}

// NewUserUsecase は UserUsecase の新しいインスタンスを返します。
func NewUserUsecase(repo repository.UserRepository) *UserUsecase {
    return &UserUsecase{Repo: repo}
}

// GetUser は指定されたIDのユーザーを取得します。
func (u *UserUsecase) GetUser(id int) (*entity.User, error) {
    return u.Repo.GetByID(id)
}

// CreateUser は新しいユーザーを作成します。
func (u *UserUsecase) CreateUser(user *entity.User) error {
    // ここで追加のビジネスロジックを実装できます（例：バリデーション）
    if user.Name == "" || user.Email == "" {
        return errors.New("name and email are required")
    }
    return u.Repo.Create(user)
}

ポイント:

ユースケース層はリポジトリに依存していますが、リポジトリの具体的な実装には依存しません（依存性逆転の原則）。
ビジネスロジックの中心として、必要に応じてデータのバリデーションや加工を行います。

ハンドラー（Handler）

ハンドラー層は、HTTPリクエストを受け取り、ユースケースを呼び出してレスポンスを返します。
Echoフレームワークを使用して実装します。

// internal/delivery/http/handler.go
package http

import (
    "net/http"
    "strconv"

    "github.com/labstack/echo/v4"
    "myapp/internal/entity"
    "myapp/internal/usecase"
)

// UserHandler はユーザー関連のHTTPハンドラーを提供します。
type UserHandler struct {
    Usecase *usecase.UserUsecase // ユースケースへの依存
}

// NewUserHandler は UserHandler を初期化し、Echoにルートを登録します。
func NewUserHandler(e *echo.Echo, usecase *usecase.UserUsecase) {
    handler := &UserHandler{Usecase: usecase}
    e.GET("/users/:id", handler.GetUser)      // GET /users/:id エンドポイント
    e.POST("/users", handler.CreateUser)      // POST /users エンドポイント
}

// GetUser は指定されたIDのユーザー情報を取得し、JSONで返します。
func (h *UserHandler) GetUser(c echo.Context) error {
    // URLパラメータからIDを取得
    idStr := c.Param("id")
    id, err := strconv.Atoi(idStr)
    if err != nil {
        // IDが整数でない場合は400 Bad Requestを返す
        return c.JSON(http.StatusBadRequest, map[string]string{"error": "Invalid ID"})
    }

    // ユースケースを呼び出してユーザーを取得
    user, err := h.Usecase.GetUser(id)
    if err != nil {
        // ユーザーが見つからない場合は404 Not Foundを返す
        return c.JSON(http.StatusNotFound, map[string]string{"error": "User not found"})
    }

    // ユーザー情報を200 OKで返す
    return c.JSON(http.StatusOK, user)
}

// CreateUser は新しいユーザーを作成し、作成されたユーザー情報を返します。
func (h *UserHandler) CreateUser(c echo.Context) error {
    var user entity.User

    // リクエストボディをUser構造体にバインド
    if err := c.Bind(&user); err != nil {
        // バインドエラーの場合は400 Bad Requestを返す
        return c.JSON(http.StatusBadRequest, map[string]string{"error": "Invalid input"})
    }

    // ユースケースを呼び出してユーザーを作成
    if err := h.Usecase.CreateUser(&user); err != nil {
        // 作成エラーの場合は500 Internal Server Errorを返す
        return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
    }

    // 作成されたユーザー情報を201 Createdで返す
    return c.JSON(http.StatusCreated, user)
}

ポイント:

ハンドラーはHTTPリクエストとレスポンスの処理に専念し、ビジネスロジックには関与しません。
エラーハンドリングを適切に行い、クライアントに分かりやすいエラーメッセージを返します。
c.Bind を使用してリクエストボディを構造体にバインドします。

インフラストラクチャ（Infrastructure）

インフラストラクチャ層は、データベース接続や外部サービスとの連携など、具体的な技術スタックに関する実装を行います。
ここでは、簡単なデータベース接続の例を示します。

// pkg/db/db.go
package db

import (
    "database/sql"
    "log"

    _ "github.com/lib/pq" // PostgreSQLドライバー
)

// NewPostgresDB はPostgreSQLデータベースへの接続を初期化します。
func NewPostgresDB(connStr string) *sql.DB {
    db, err := sql.Open("postgres", connStr)
    if err != nil {
        log.Fatalf("Failed to connect to PostgreSQL: %v", err)
    }

    // データベース接続が有効か確認
    if err := db.Ping(); err != nil {
        log.Fatalf("Failed to ping PostgreSQL: %v", err)
    }

    log.Println("Connected to PostgreSQL successfully")
    return db
}

ポイント:

実際のアプリケーションでは、データベース接続やマイグレーションの管理をここで行います。
必要に応じてリポジトリの具体的な実装をインフラストラクチャ層に追加します。

メイン（Main）

アプリケーションのエントリーポイントであり、各層の依存関係を組み立てます。

// cmd/server/main.go
package main

import (
    "log"
    "myapp/internal/delivery/http"
    "myapp/internal/repository"
    "myapp/internal/usecase"
    "myapp/pkg/db"

    "github.com/labstack/echo/v4"
)

func main() {
    // Echoインスタンスの作成
    e := echo.New()

    // データベース接続の初期化（実際の接続文字列を使用）
    // ここではメモリリポジトリを使用するため、データベース接続は省略
    // dbConn := db.NewPostgresDB("user=postgres password=secret dbname=mydb sslmode=disable")

    // リポジトリの初期化
    // ここではメモリリポジトリを使用
    repo := repository.NewInMemoryUserRepository()

    // ユースケースの初期化
    uc := usecase.NewUserUsecase(repo)

    // ハンドラーの設定
    http.NewUserHandler(e, uc)

    // サーバーの起動
    log.Println("Starting server on :8080")
    if err := e.Start(":8080"); err != nil {
        log.Fatalf("Shutting down the server: %v", err)
    }
}

ポイント:

各層の依存関係をここで組み立てます。
実際のデータベースを使用する場合は、リポジトリの実装を切り替えます。
Echoフレームワークの設定やミドルウェアの追加もここで行います。

まとめ

クリーンアーキテクチャを採用することで、システムの各層が明確に分離され、依存関係が内向きになります。
これにより、以下のような利点が得られます。

保守性の向上: 各層が独立しているため、変更が他の部分に波及しにくくなります。
テスト容易性: モックやスタブを使用して各層を個別にテストできます。
拡張性の確保: 新しい機能や技術スタックの導入が容易です。

本記事では、Go言語とEchoフレームワークを使用してクリーンアーキテクチャを実装する基本的な方法を紹介しました。
実際のプロジェクトでは、リポジトリの具体的なデータベース実装や、ユースケースの複雑なビジネスロジックなど、さらに多くの要素が加わります。
しかし、基本的な構造と原則を理解することで、堅牢で拡張性の高いシステムを構築する基盤を築くことができます。

クリーンアーキテクチャの採用を検討している方は、ぜひこのガイドを参考にプロジェクトを進めてみてください。
継続的な学習と実践を通じて、より良いソフトウェア設計を目指しましょう。

参考資料

会社紹介

株式会社 Mosaica
最先端テクノロジーで社会課題を解決し、持続可能な未来を創造する IT カンパニー。
AI ソリューション、クラウド統合、DX 推進、経営コンサルティングなど包括的なサービスでビジネス変革を支援しています。

詳しくは公式サイトまでお気軽にご相談ください。
公式サイト： https://mosaica.co.jp/