Goマイクロサービスの基本構成・ベストプラクティスとテンプレート比較

Goマイクロサービスの基本構成

Go でマイクロサービスを開発する際に、プロジェクト全体の可読性と保守性を確保するための「最低限必要な」ディレクトリ構造と設定手順を示します。ここで紹介する構成は、Clean Architecture の考え方を取り入れつつ、シンプルに保てることを目的としています。

ディレクトリ構成（推奨）

以下の階層は cmd/ をエントリポイント、internal/ と pkg/ に機能別コードを分離した形です。各ディレクトリの役割は簡潔にコメントで示しています。

• cmd/ は実行可能バイナリを生成するだけに留め、設定やロギングは外部から注入します。
• internal/service/ にインターフェイスと実装を分離し、テスト時はモックで差し替えられるように設計します。
• pkg/models.go は構造体定義のみを保持し、バリデーションロジックや DB アクセスは含めません。

go.mod の管理

Clean Architecture と依存性注入（DI）の指針

1. 層分割
2. Domain：pkg/models.go に純粋な構造体だけを置く。
3. UseCase：internal/service/ 配下にビジネスロジックのインターフェイスと実装を配置。外部依存はインターフェイスで抽象化。

4. Interface Adapter：リポジトリや外部 API クライアントは internal/adapter/ に実装し、UseCase からはインターフェイス経由で呼び出す。

5. DI ライブラリの選択肢（プロジェクト規模に合わせて）

6. Uber fx – 起動・停止管理が自動化され、大規模サービス向き。

7. Google wire – コンパイル時に依存解決コードを生成し、ランタイムオーバーヘッドがゼロ。小〜中規模での採用が一般的。

8. 簡易 DI 実装例（wire）

テスト・CI の概要

テンプレート選定基準と比較表

テンプレートを採用する際に評価すべき項目を整理し、代表的な 2 つのリポジトリを客観的に比較します。数値情報（スター数・最終更新日など）は「参考情報」として掲載していますが、実務での導入判断は機能要件との合致度で行うことを推奨します。

※上記の数値は GitHub の公開情報を元にした目安です。実際の採用判断では最新のリポジトリ状況をご確認ください。

主要テンプレートの概要

以下では、上表で取り上げた 2 つのテンプレートについて、構成要素と特徴だけを簡潔にまとめます。実装コードは省略し、導入時に注目すべきポイントのみ列挙します。

neo7337/go-microservice-template の概要

このテンプレートは「最小限の雛形」を提供することを目的としています。シンプルさが求められる PoC や学習用途に適しています。

• ディレクトリ構成（抜粋）
  cmd/
server/main.go
internal/
service/ # UseCase 実装
adapter/ # リポジトリ実装
pkg/
models.go # ドメインモデルのみ
api/
openapi.yaml (任意)
configs/
config.yaml
Dockerfile
docker-compose.yml
• DI：wire の利用はオプション。手動で依存関係を組み立てる形のため、コードが増えると管理コストが上がります。
• テスト支援：モック生成ツール（例：mockgen）を使用すれば簡易的にユニットテストが可能です。
• デプロイ：Dockerfile と docker‑compose が提供されるだけで、K8s 用マニフェストは同梱されていません。

bruc3mackenzi3/go-microservice-template の概要

本テンプレートは「本番レベルのコンテナ化」と「自動生成ドキュメント」を前提に設計されています。大規模プロジェクトや継続的デリバリーが必須の場合に有用です。

• ディレクトリ構成（抜粋）
  cmd/
server/main.go
internal/
service/
adapter/
logger/
tracing/
pkg/
models.go
api/
openapi.yaml # swaggo により自動生成
configs/
config.yaml
k8s/
deployment.yaml
service.yaml
configmap.yaml
Dockerfile (multi‑stage)
docker-compose.yml
.github/workflows/ci.yml
• DI：標準で Uber fx が組み込まれ、起動コードがテンプレート化されています。
• OpenAPI：swaggo/swag による自動生成スクリプトが make generate 等のコマンドで走ります。Swagger UI が /swagger/index.html で閲覧可能です。
• CI/CD：GitHub Actions のワークフローにテスト、Lint、Docker ビルド・レジストリへのプッシュが含まれます。
• Observability：prometheus/client_golang と OpenTelemetry が組み込まれ、/metrics と Jaeger 用トレーシングエンドポイントを自動で公開します。

導入手順と実務での留意点

ここでは 共通化できるセットアップフロー と、環境ごとの設定・デプロイ時に注意すべきポイントをまとめます。冗長な記述は排除し、最小限のコマンドだけを示します。

共通セットアップフロー

1. リポジトリ取得
   bash
git clone https://github.com/<owner>/<template-repo>.git
cd <template-repo>
2. 依存解決（ローカル環境）
   bash
go mod tidy
3. Docker ビルド（マルチステージ Dockerfile が前提）
   bash
docker build -t myservice:dev .
4. ローカル起動（docker‑compose）
   bash
docker compose up -d # DB・Redis 等の依存サービスが自動起動
docker run --rm -p 8080:8080 myservice:dev
5. ヘルスチェック
   bash
curl -s http://localhost:8080/health | jq .
# {"status":"OK"} が返れば正常起動

環境変数とシークレット管理

Kubernetes デプロイのポイント

• Deployment はレプリカ数やリソース制限を明示し、readinessProbe/livenessProbe を設定することで自動回復性を向上させます。
• Observability：Prometheus の ServiceMonitor と Jaeger のサイドカーはテンプレートに含まれているので、そのまま適用可能です。

ライセンスと貢献ガイドライン

まとめ

• 基本構成：cmd/, internal/, pkg/, api/, configs/ の5層でシンプルかつ拡張性を確保。
• DI と Clean Architecture：プロジェクト規模に合わせて wire か fx を選択し、インターフェイス中心の設計を徹底する。
• テンプレート比較：neo7337 は学習・PoC 向けの軽量版、bruc3mackenzi3 は本番環境に即したコンテナ化・CI/CD が充実した版。導入時は「DI の自動化」や「K8s マニフェスト」の有無で選択するとよい。
• 導入手順：リポジトリ取得 → go mod tidy → Docker ビルド → docker‑compose 起動の流れを共通化し、環境変数・シークレットは K8s の仕組みで管理する。

この構成と選定基準をベースにすれば、Go マイクロサービスの開発・運用がスムーズに進むはずです。ご不明点やプロジェクト固有の要件がある場合は、上記テンプレートをカスタマイズしながら適宜調整してください。