マイクロサービス向け Go バックエンド開発

コア原則

• Clean Architecture を適用し、ハンドラー、サービス、リポジトリ、ドメインモデルを明確に分離する
• インターフェース駆動開発を優先し、明示的な依存性の注入を行う
• 短く焦点を絞った単一責任の関数を作成する
• goroutine の安全な使用を確保し、チャネルまたは sync プリミティブで共有状態を保護する

プロジェクト構造

モジュラーなプロジェクト構造をディレクトリを明確に分けて維持する:

project/
├── cmd/           # Application entry points
├── internal/      # Private application code
├── pkg/           # Public library code
├── api/           # API definitions (OpenAPI, protobuf)
├── configs/       # Configuration files
└── test/          # Additional test utilities

エラーハンドリング

• エラーは常に明示的にチェックして処理する
• エラーをラップしてトレーサビリティを確保する: fmt.Errorf("context: %w", err)
• ドメイン固有のエラーにはカスタムエラータイプを作成する
• 適切なコンテキストを付けてエラーをコールスタック上に返す
• 十分なコンテキストを含めて適切なレベルでエラーをログする

コンテキスト伝播

• リクエストスコープの値、デッドライン、キャンセルのためにコンテキスト伝播を使用する
• コンテキストを関数の最初のパラメーターとして渡す
• 長時間実行される操作ではコンテキストキャンセルを尊重する
• 外部呼び出しに対して適切なタイムアウトを設定する

可観測性

包括的な可観測性のために OpenTelemetry を実装する:

分散トレーシング

• 重要な操作にスパンを追加する
• サービス境界を越えてトレースコンテキストを伝播させる
• スパンに関連属性を含める

メトリクス

• ビジネス操作向けのカスタムメトリクスを実装する
• 標準的なメトリクスタイプ（カウンター、ゲージ、ヒストグラム）を使用する
• メトリクスを Prometheus 形式でエクスポートする

構造化ログ

• 一貫性のあるフィールド名で構造化ログを使用する
• ログエントリにトレース ID を含める
• 適切なレベル（debug、info、warn、error）でログを記録する

セキュリティ

• すべての外部入力に対して厳密に入力検証を適用する
• JWT トークンとクッキーにはセキュアなデフォルトを使用する
• 適切な認証と認可を実装する
• 機密情報の漏洩を避けるためにログ前にデータをサニタイズする
• データベースクエリに対してはプリペアドステートメントを使用する

テスト

ユニットテスト

• テーブル駆動ユニットテストを適切なカバレッジで作成する
• 安全な場所では並行テスト実行を使用する
• インターフェースを使用して外部依存をモックする
• ビジネスロジックのテストに焦点を当てる

統合テスト

• 統合テストをユニットテストから分離する
• データベースとサービス依存にはテストコンテナを使用する
• 実際の API エンドポイントとレスポンスをテストする

並行処理

• 並行処理に適切に goroutine を使用する
• チャネルまたは sync プリミティブで共有状態を保護する
• 適切なグレースフルシャットダウンを実装する
• 制約のある並行処理にはワーカープールを使用する

ドキュメント

• GoDoc スタイルのコメントでドキュメントを作成する
• コメントをコード変更に合わせて最新に保つ
• パブリック API を十分にドキュメント化する
• 適切な場合はドキュメントに例を含める

CI/CD 統合

• リント処理とテストのための CI 統合を維持する
• 包括的なリント処理に golangci-lint を使用する
• すべてのプルリクエストでテストを実行する
• コードカバレッジレポートを含める