Go API Development with Standard Library

コア原則

• 常に最新の安定版 Go (1.22 以上) を使用し、RESTful API 設計原則、net/http パッケージ、および Go 1.22 で導入された新しい ServeMux に精通していること
• ユーザーの要件に注意深く正確に従う
• 最初にステップバイステップで考える - API 構造、エンドポイント、およびデータフローの計画を疑似コードで非常に詳細に記述する
• 正確で最新の、バグのない、完全に機能し、安全で効率的な Go API コードを作成する
• API 実装に TODO、プレースホルダー、または欠落している部分を一切残さない
• API 設計では、常にセキュリティ、スケーラビリティ、保守性を優先する

API 開発ガイドライン

ルーティングと HTTP ハンドリング

• Go 1.22 で導入された新しい http.ServeMux をルーティングに使用する
• 適切な HTTP メソッド処理 (GET、POST、PUT、DELETE、PATCH) を実装する
• レスポンスに適切な HTTP ステータスコードを使用する
• リクエストとレスポンスの content-type を適切に処理する

エラーハンドリング

• カスタムエラータイプが有益な場合を含め、適切なエラーハンドリングを実装する
• エラーレスポンスに適切な HTTP ステータスコードを返す
• JSON 形式の構造化エラーレスポンスを使用する
• デバッグおよび監視のためにエラーを適切にログする

入力検証

• API エンドポイントの入力検証を実装する
• リクエストボディ、クエリパラメータ、およびパスパラメータを検証する
• クライアントに明確な検証エラーメッセージを返す
• インジェクション攻撃を防止するため入力をサニタイズする

JSON ハンドリング

• JSON のシリアライズ/デシリアライズに encoding/json を使用する
• JSON フィールドマッピングのための適切な struct タグを実装する
• JSON 解析エラーを適切に処理する
• レスポンスに適切な JSON フォーマットを使用する

並行性

• API パフォーマンスのために、必要に応じて Go の組み込み並行性機能を活用する
• 有益な場合は goroutine を並行操作に使用する
• 共有状態に対して適切な同期を実装する
• リクエストのキャンセルとタイムアウトに context を使用する

ミドルウェア

• ロギング、認証、レート制限などのクロスカッティングコンサーンのためにミドルウェアを実装する
• 組み合わせ可能なリクエスト処理のためミドルウェアチェーンを使用する
• 必要に応じて CORS ハンドリングを実装する
• リクエスト/レスポンスロギングミドルウェアを追加する

セキュリティ

• 必要に応じて認証と認可を実装する
• 本番環境では HTTPS を使用する
• 悪用を防ぐためレート制限を実装する
• すべてのユーザー入力を検証およびサニタイズする
• クッキーとセッションに対してセキュアなデフォルト値を使用する

ロギング

• 構造化出力を備えた標準ライブラリロギングを使用する
• デバッグおよび監視に適切な情報をログする
• 機密情報のログは避ける
• ログレベルを適切に使用する

テスト

• ハンドラーとビジネスロジックのユニットテストを作成する
• API エンドポイントの統合テストを実装する
• 適切な場合はテーブル駆動テストを使用する
• テストで外部の依存関係をモックする