문서가격블로그
문의하기
로그인무료로 가입하기
Back to Tech Articles

GoモノリシックWebアプリケーションの構造化：凝集度と疎結合なコードのために

Aug. 24, 2025
# Misc

Takashi Yamamoto

Infrastructure Engineer · Leapcell

이 게시물은 English, 한국어 및 Deutsch에서도 볼 수 있습니다.
Cover of "GoモノリシックWebアプリケーションの構造化：凝集度と疎結合なコードのために"

はじめに

Web開発の活気ある世界において、Goはそのパフォーマンス、並行処理のストーリー、そして直接的な構文で称賛され、重要なニッチを切り開いてきました。アプリケーションが単純なスクリプトから複雑なシステムへと進化するにつれて、クリーンで理解しやすく、スケーラブルなコードベースを維持することが最重要になります。これは、すべてのコンポーネントが単一のコードベース内に存在するモノリシックアプリケーションでは特にそうです。マイクロサービスが人気のある代替手段を提供していますが、モノリスは多くのプロジェクト、特に初期段階や、よりシンプルなデプロイメントと統一された開発を優先するチームにとって、依然として実用的でしばしば好まれる選択肢です。しかし、慎重なアーキテクチャ上の配慮なしには、そのようなモノリスはすぐに絡み合った混乱に陥り、新しい機能開発を悪夢にし、バグ修正を危険な試みに変える可能性があります。中核となる課題は、関連部分を一緒に保つ「高い凝集度」と、コンポーネントが独立していて交換可能である「低い結合度」を保証するようにコードを整理することにあります。この記事では、これらの重要な特性を達成するために、GoモノリシックWebアプリケーションを構造化するための効果的な戦略とパターンを検討し、潜在的な混沌を保守可能な順序に変換します。

コア原則の理解

特定のGo実装に飛び込む前に、議論を導く中心的な概念を簡単に定義しましょう。

  • 凝集度（Cohesion）: これは、モジュール内の要素がどれだけまとまっているかの度合いを指します。高い凝集度は、モジュール内のすべての部分が単一の、明確に定義された目的のために機能することを意味します。たとえば、UserServiceモジュールには、注文処理や支払い処理ではなく、ユーザー管理に直接関連するロジックのみが含まれるべきです。高い凝集度は、理解、テスト、保守が容易なモジュールにつながります。
  • 結合度（Coupling）: これは、ソフトウェアモジュール間の相互依存の度合いを指します。低い結合度は、モジュールが互いに比較的独立しており、あるモジュールでの変更が他のモジュールでの変更を必要とする可能性が低いことを意味します。たとえば、UserServiceは、理想的にはデータベースクライアントの具体的な実装に直接依存するのではなく、それが定義するインターフェースに依存すべきです。低い結合度は、柔軟性、再利用性、およびデバッグの容易さを促進します。

高い凝集度と低い結合度を達成することは、優れたソフトウェア設計の礎であり、より堅牢でスケーラブルで保守性の高いアプリケーションにつながります。

Goモノリスにおける戦略的なコード編成

Goのパッケージシステムとインターフェース駆動設計は、これらの原則を強制するための優れたツールを提供します。ここでは、GoモノリシックWebアプリケーションで一般的に効果的なアーキテクチャパターン、しばしば「レイヤードアーキテクチャ」または「クリーンアーキテクチャ」のバリアントと呼ばれるものを概説します。

1. プロジェクト構造 - レイヤードアプローチ

明確に定義されたディレクトリ構造は、明瞭さへの最初のステップです。典型的なGoモノリシックWebアプリケーションは次のようになります。

my-web-app/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── app/
│   │   ├── user/
│   │   │   ├── service.go
│   │   │   └── repository.go
│   │   ├── product/
│   │   │   ├── service.go
│   │   │   └── repository.go
│   │   └── common/
│   │       └── errors.go
│   ├── domain/
│   │   ├── user.go
│   │   └── product.go
│   ├── port/
│   │   ├── http/
│   │   │   ├── handler.go
│   │   │   ├── routes.go
│   │   │   └── dto.go
│   │   └── cli/
│   │       └── commands.go
│   ├── adapter/
│   │   ├── database/
│   │   │   ├── postgres/
│   │   │   │   └── user_repo.go
│   │   │   │   └── product_repo.go
│   │   │   └── redis/
│   │   │       └── cache.go
│   │   └── external/
│   │       └── payment_gateway/
│   │           └── client.go
│   └── config/
│       └── config.go
├── pkg/
│   └── utils/
│       └── validator.go
├── web/
│   └── static/
│   └── templates/
└── go.mod
└── go.sum

これらのディレクトリの内訳を見てみましょう。

  • cmd/: 実行可能なコマンドのエントリポイントを含みます。Webサーバーの場合、cmd/server/main.goは通常、HTTPサーバーを初期化して開始します。これにより、アプリケーションのブートストラップロジックが分離され、最小限に抑えられます。
  • internal/: 他のプロジェクトからインポートされるべきではない、アプリケーション固有のコードを含みます。これは、強力な内部境界を維持するために重要です。
    • internal/app/: ビジネスロジックの中核を含み、しばしば機能（例：user、product）ごとに構造化されます。
      • service.go: ビジネスルールを実装し、リポジトリや外部サービスとのやり取りを調整します。これは、アプリケーションの「何」と「なぜ」のほとんどが存在する場所です。
      • repository.go: データ操作のためのインターフェースを定義します。これらのインターフェースは、具体的なアダプターによって実装されます。
    • internal/domain/: コアアプリケーションエンティティ、値オブジェクト、およびドメイン固有の型を定義します。これらは、特定の永続化またはトランスポートメカニズムに関連付けられたビジネスロジックを持たない、純粋なGo構造体であるべきです。
    • internal/port/: アプリケーションが外部世界と対話するための「ポート」またはインターフェースを定義します。
      • http/: HTTPハンドラー、ルーティング設定、およびリクエストとレスポンスのDTO（データ転送オブジェクト）を含みます。このレイヤーは、アプリケーションがHTTP経由でどのように入力を受け取り、出力を送信するかを定義します。
      • cli/: アプリケーションにCLIコマンドがある場合、それらの定義はここに配置されます。
    • internal/adapter/: internal/appおよびinternal/portで定義されたインターフェースを実装する「アダプター」を含みます。これらは、データベース、外部API、メッセージキューなどと対話するための具体的な実装です。これらは、外部テクノロジーをアプリケーションのドメインに「適応」させます。
    • internal/config/: アプリケーション設定のロードと解析を処理します。
  • pkg/: 他のプロジェクトから安全にインポートできる再利用可能なライブラリまたはユーティリティを格納します（ただし、真のモノリスでは、internalよりも一般的ではないかもしれません）。例としては、汎用ユーティリティ関数、カスタムエラータイプ、またはヘルパーがあります。
  • web/: Goアプリケーションが直接配信する場合の静的アセットまたはHTMLテンプレート用です。

2. 機能ベースのサービス構造による高い凝集度の達成

internal/app内では、機能（例：user、product）ごとに整理することで、凝集度が大幅に向上します。各機能パッケージには、その特定のドメインに関連するすべてのもの（ビジネスロジック（service）、データアクセスインターフェース（repository））が含まれます。

例：internal/app/user/service.go

package user

import (
	"context"
	"my-web-app/internal/domain"
	"my-web-app/internal/app/common"
)

// Service defines the business logic for user management.
type Service struct {
	repo Repository
}

// NewService creates a new user service.
func NewService(repo Repository) *Service {
	return &Service{repo: repo}
}

// RegisterUser handles the registration of a new user.
func (s *Service) RegisterUser(ctx context.Context, email, password string) (*domain.User, error) {
	// Business rule: check if user already exists
	existingUser, err := s.repo.GetUserByEmail(ctx, email)
	if err != nil && err != common.ErrNotFound {
		return nil, err
	}
	if existingUser != nil {
		return nil, common.ErrUserAlreadyExists
	}

	// Hash password (simplified for example)
	hashedPassword := "hashed_" + password

	user := &domain.User{
		Email:    email,
		Password: hashedPassword,
		// ... other fields
	}

	if err := s.repo.CreateUser(ctx, user); err != nil {
		return nil, err
	}
	return user, nil
}

// GetUserByID retrieves a user by their ID.
func (s *Service) GetUserByID(ctx context.Context, id string) (*domain.User, error) {
	return s.repo.GetUserByID(ctx, id)
}

例：internal/app/user/repository.go

package user

import (
	"context"
	"my-web-app/internal/domain"
)

// Repository defines the interface for user data storage operations.
type Repository interface {
	CreateUser(ctx context.Context, user *domain.User) error
	GetUserByID(ctx context.Context, id string) (*domain.User, error)
	GetUserByEmail(ctx context.Context, email string) (*domain.User, error)
	UpdateUser(ctx context.Context, user *domain.User) error
	DeleteUser(ctx context.Context, id string) error
}

ここでは、userサービスがすべてのユーザー関連のビジネスルールをカプセル化しています。これは、同じuserパッケージ内で定義されたRepositoryインターフェースを使用しており、凝集度を高めています。

3. インターフェースと依存性逆転による低い結合度の達成

Goで低い結合度を実現する鍵は、インターフェースの広範な使用です。サービスはデータベースや外部サービスの具体的な実装に依存せず、インターフェースに依存します。具体的な実装は、より高いレベル（例：main.go）で「注入」されます。これは、依存性逆転の原則の直接的な適用です。

例：internal/adapter/database/postgres/user_repo.go

package postgres

import (
	"context"
	"database/sql"
	"fmt"

	"my-web-app/internal/app/user" // インターフェースをインポート！
	"my-web-app/internal/domain"
)

// UserRepository implements user.Repository for PostgreSQL.
type UserRepository struct {
	db *sql.DB
}

// NewUserRepository creates a new PostgreSQL user repository.
func NewUserRepository(db *sql.DB) *UserRepository {
	return &UserRepository{db: db}
}

// CreateUser implements user.Repository.CreateUser.
func (r *UserRepository) CreateUser(ctx context.Context, u *domain.User) error {
	query := `INSERT INTO users (email, password) VALUES ($1, $2) RETURNING id`
	err := r.db.QueryRowContext(ctx, query, u.Email, u.Password).Scan(&u.ID)
	if err != nil {
		return fmt.Errorf("failed to create user: %w", err)
	}
	return nil
}

// GetUserByEmail implements user.Repository.GetUserByEmail.
func (r *UserRepository) GetUserByEmail(ctx context.Context, email string) (*domain.User, error) {
	u := &domain.User{}
	query := `SELECT id, email, password FROM users WHERE email = $1`
	err := r.db.QueryRowContext(ctx, query, email).Scan(&u.ID, &u.Email, &u.Password)
	if err != nil {
		if err == sql.ErrNoRows {
			return nil, user.ErrNotFound // app/userレイヤーからの特定エラーを使用
		}
		return nil, fmt.Errorf("failed to get user by email: %w", err)
	}
	return u, nil
}

// ... other repository methods

UserRepositoryが明示的にuser.Repositoryを実装していることに注意してください。user.ServiceはPostgreSQLについては何も知りませんが、user.Repositoryインターフェースのみと対話します。テストのためにNoSQLデータベースやインメモリリポジトリに切り替えることを決定した場合、internal/app/userのコアビジネスロジックではなく、internal/adapter/databaseのみを変更する必要があります。これにより、結合度が劇的に減少します。

4. cmd/server/main.goでの配線

最上位のmain.goは、すべてのコンポーネントを組み立て、依存関係を注入する責任があります。

例：cmd/server/main.go

package main

import (
	"context"
	"database/sql"
	"log"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	_ "github.com/lib/pq" // PostgreSQL driver

	"my-web-app/internal/adapter/database/postgres"
	"my-web-app/internal/app/user"
	"my-web-app/internal/config"
	"my-web-app/internal/port/http"
)

func main() {
	cfg := config.LoadConfig() // 設定のロード

	// データベース接続の初期化
	db, err := sql.Open("postgres", cfg.DatabaseURL)
	if err != nil {
		log.Fatalf("Failed to connect to database: %v", err)
	}
	defer db.Close()

	if err = db.Ping(); err != nil {
		log.Fatalf("Failed to ping database: %v", err)
	}
	log.Println("Database connection established.")

    // --- Dependency Injection ---
	// 具体的なリポジトリ実装の作成
	userRepo := postgres.NewUserRepository(db)

	// リポジトリを注入したサービスレイヤーの作成
	userService := user.NewService(userRepo) // user.Repositoryの実装であるuserRepoを注入

	// サービスを注入したHTTPハンドラーの作成
	userHandler := httpport.NewUserHandler(userService) 
	// --- End Dependency Injection ---

	// ルートの設定
	router := httpport.NewRouter(userHandler) // userHandlerをルーターに渡す

	server := &http.Server{
		Addr:         cfg.ListenAddr,
		Handler:      router,
		ReadTimeout:  5 * time.Second,
		WriteTimeout: 10 * time.Second,
		IdleTimeout:  15 * time.Second,
	}

	// ゴルーチンでサーバーを起動
	go func() {
		log.Printf("Server listening on %s", cfg.ListenAddr)
		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
			log.Fatalf("Could not listen on %s: %v", cfg.ListenAddr, err)
		}
	}()

	// Graceful shutdown
	quit := make(chan os.Signal, 1)
	signal.Notify(quit, os.Interrupt, syscall.SIGTERM)
	<-quit
	log.Println("Shutting down server...")

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	if err := server.Shutdown(ctx); err != nil {
		log.Fatalf("Server forced to shutdown: %v", err)
	}
	log.Println("Server exited gracefully.")
}

main.goは、すべてのピースをまとめる場所です。これは、具体的な型を作成し、それらをインターフェースに依存するレイヤーに注入する責任を負う、アプリケーションの「コンポジションルート」です。

結論

GoモノリシックWebアプリケーションを高い凝集度と低い結合度で構造化することは、単なる学術的な演習ではなく、保守性、スケーラブル性、テスト性に優れたソフトウェアを構築するための実践的な必要性です。レイヤードアーキテクチャを採用し、依存性逆転のためにGoのインターフェースシステムを活用し、コードを機能ごとに整理することで、開発者は楽しく作業できる堅牢なアプリケーションを作成できます。このアプローチは、変更の波及効果を最小限に抑え、デバッグを簡素化し、アプリケーションのさまざまな部分の独立した開発を可能にし、最終的にはより回復力のある拡張性の高いシステムにつながります。インターフェースを採用し、意図によって整理すれば、あなたのGoモノリスは繁栄するでしょう。

Share this article

HackerNews

More Posts from Leapcell

Popular Posts