go-api-development

標準ライブラリを使用した Go API 開発

基本原則

• 常に最新の安定版 Go（1.22 以降）を使用し、RESTful API の設計原則、net/http パッケージ、Go 1.22 で導入された新しい ServeMux に精通してください
• ユーザーの要件に注意深く、忠実に従ってください
• まず、手順を追って考えてください。API の構成、エンドポイント、データフローの計画を、詳細な疑似コードで説明してください
• 正確で最新の、バグがなく、完全に機能する、安全かつ効率的な API 用 Go コードを記述してください
• API の実装に、TODO、プレースホルダー、未完成の部分を絶対に残さないでください
• API の設計では、常にセキュリティ、スケーラビリティ、保守性を優先してください

API 開発ガイドライン

ルーティングと HTTP 処理

• ルーティングには、Go 1.22 で導入された新しい http.ServeMux を使用してください
• 適切な HTTP メソッド（GET、POST、PUT、DELETE、PATCH）の処理を実装してください
• レスポンスには適切な HTTP ステータスコードを使用してください
• リクエストとレスポンスのコンテンツタイプを適切に処理してください

エラー処理

• 必要に応じてカスタムエラー型を使用するなど、適切なエラー処理を実装してください
• エラーレスポンスには適切な HTTP ステータスコードを返してください
• JSON 形式の構造化されたエラーレスポンスを使用してください
• デバッグとモニタリングに適した方法でエラーをログに記録してください

入力の検証

• API エンドポイントに入力検証を実装してください
• リクエストボディ、クエリパラメーター、パスパラメーターを検証してください
• クライアントに明確な検証エラーメッセージを返してください
• インジェクション攻撃を防ぐために入力をサニタイズしてください

JSON 処理

• JSON のシリアライズとデシリアライズには encoding/json を使用してください
• JSON フィールドのマッピングに適切な構造体タグを実装してください
• JSON の解析エラーを適切に処理してください
• レスポンスには適切な JSON 形式を使用してください

並行処理

• API のパフォーマンスに適している場合は、Go 組み込みの並行処理機能を活用してください
• 有益な場合は、並行処理にゴルーチンを使用してください
• 共有状態に対する適切な同期処理を実装してください
• リクエストのキャンセルとタイムアウトにはコンテキストを使用してください

ミドルウェア

• 横断的な関心事（ロギング、認証、レート制限）に対応するミドルウェアを実装してください
• 合成可能なリクエスト処理にはミドルウェアのチェーンを使用してください
• 必要に応じて CORS 処理を実装してください
• リクエストとレスポンスのロギングミドルウェアを追加してください

セキュリティ

• 必要に応じて認証と認可を実装してください
• 本番環境では HTTPS を使用してください
• 不正利用を防ぐためにレート制限を実装してください
• すべてのユーザー入力を検証し、サニタイズしてください
• Cookie とセッションには安全なデフォルト設定を使用してください

ロギング

• 構造化出力に標準ライブラリのロギング機能を使用してください
• デバッグとモニタリングに適した情報をログに記録してください
• 機密情報をログに記録しないでください
• ログレベルを適切に使用してください

テスト

• ハンドラーとビジネスロジックの単体テストを作成してください
• API エンドポイントの統合テストを実装してください
• 適切な場合は、テーブル駆動テストを使用してください
• テストでは外部依存関係をモックしてください