go-backend-microservices

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

基本原則

• ハンドラー、サービス、リポジトリ、ドメインモデルを明確に分離し、クリーンアーキテクチャを適用します
• 明示的な依存性注入を取り入れ、インターフェース主導の開発を優先します
• 単一の責務を持つ、短く焦点の定まった関数を記述します
• ゴルーチンを安全に使用し、共有状態をチャネルまたは 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 トークンと Cookie には、安全なデフォルト値を使用します
• 適切な認証と認可を実装します
• 機密情報の漏えいを防ぐため、ログに記録する前にデータをサニタイズします
• データベースクエリにはプリペアドステートメントを使用します

テスト

単体テスト

• 十分なカバレッジを確保できるテーブル駆動の単体テストを記述します
• 安全な場合は、テストを並列実行します
• インターフェースを使用して外部依存関係をモックします
• ビジネスロジックのテストに重点を置きます

統合テスト

• 統合テストを単体テストと分離します
• データベースやサービスの依存関係にはテストコンテナーを使用します
• 実際の API エンドポイントとレスポンスをテストします

並行処理

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

ドキュメント

• GoDoc 形式のコメントでドキュメントを記述します
• コードの変更に合わせてコメントを最新の状態に保ちます
• 公開 API を詳しく文書化します
• 有用な場合は、ドキュメントに例を含めます

CI/CD 統合

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