このページの目次

このページの目次

Go ツールチェーン

適用義務

AI 支援開発のデフォルト言語は TypeScript と Python である。Go はデフォルトではなく、次の要件が実際に必要な場合に限って選ぶ。

  • 性能が重視されるネットワークサービス
  • 単一バイナリとして配布するコマンドラインツール
  • 静的な単一バイナリでデプロイする対象
  • 並行性の高いワークロード

Go の採用には明確な根拠とユーザーの承認が必要であり、その内容をプロジェクトの ADR に記録する。

Go に慣れていること自体は、採用の根拠にならない。

適用範囲

本文書は Go プロジェクトのベースライン標準であり、プロジェクト単位の評価に代わるものではない。Go を採用する前に、要件が上記のいずれかに当てはまり、かつ TypeScript や Python では妥当なコストで満たせないことを確認する。

バージョン方針

最新の安定版 Go リリースを mise で管理する。

go.mod の toolchain ディレクティブは、mise で管理する Go のバージョンと一致させる。

記録された理由がない限り、旧バージョンの Go に固定しない。

利用ルール

リント

リンターとして golangci-lint を使う。

mise タスクとして利用できるようにし、ローカル開発と CI で同じ設定を使う。

設定は .golangci.yml としてコミットし、プロジェクトで重視する項目に合わせて調整する。enable-all は使わない。すべてを有効にすると、実行が遅く、特定のスタイルを要求するチェックまで有効になり、重要な指摘を見つけにくくなる。

常に有効にするベースライン:

  • govet — 疑わしい構造を検出し、go vet のチェックをおおむね含む
  • staticcheck — 正確性、簡略化、スタイルのチェック。エラー文字列の形式も含む(ST1005)。エラーメッセージは小文字で始め、末尾に句読点を付けない
  • unused — 未使用の定数、変数、関数、型
  • ineffassign — 効果のない代入
  • misspell — よくある英単語のスペルミス

ベースラインに加えて、プロジェクトの性質に応じたグループを追加する:

  • context を多用するサービス:contextcheck、containedctx、fatcontext、noctx
  • エラー処理を重視するプロジェクト:errcheck に加えて errorlint と wrapcheck

フォーマット

フォーマッターには gofumpt を使う。

フォーマットのチェックをプリコミット設定と CI に含める。

エラー処理

エラーにコンテキストを付加するときは、%w でラップする:

return fmt.Errorf("loading config: %w", err)

ラップされたエラーは errors.Is と errors.As で検査する。

エラーメッセージ文字列を比較してエラーを判定してはならない。

コンテキスト

ブロックする関数やリクエスト単位の関数では、最初のパラメーターに context.Context を渡す。

呼び出し元のコンテキストを伝播させ、ライブラリコード内で新たな context.Background を生成してはならない。

並行処理

各 goroutine には所有者を一つだけ割り当て、その所有者がライフサイクルに責任を持つことを明示する。

キャンセルはコンテキストの伝播によって明示する。

goroutine をリークさせない。

テスト

複数の入力に対する振る舞いを、テーブル駆動テストでカバーする。

CI では go test -race を実行する。

_test.go ファイルには、.golangci.yml のパス単位の除外を使って、緩和したリントルールを適用する。テストでは本番コードほどリントを厳格にせず、可読性と意図の明確さを優先する。エラーラップと重複コードのスタイルチェックは、テストでは無効にする:

version: "2"
linters:
  exclusions:
    rules:
      - path: _test\.go
        linters:
          - wrapcheck
          - errorlint
          - dupl

panic

ライブラリコードでは panic を使わず、エラーを返す。

panic は cmd/ のエントリーポイントにおける回復不能な起動時エラーに限って使う。

プロジェクト構成

Go には公式に定められた標準プロジェクト構成がない。golang-standards/project-layout リポジトリはコミュニティによる参考資料であり、公式標準ではない。公式ガイド Organizing a Go module も、モジュールのルートに基本パッケージを置く構成から説明を始めている。

  • 小さなライブラリはルートをフラットに保ってよい。go.mod とパッケージのファイルで足りる。
  • 複雑なサービスは、ビジネスのレイヤー構造に合う構成を設計し、テンプレートをそのままコピーしない。

cmd/(バイナリごとにエントリーポイントを置く)と internal/(インポート制限をコンパイラーが強制する)は、今も有用な慣習である。設計に役立つ場合に採用し、テンプレートに従う義務として扱わない。

連携

  • mise — バージョン管理:Go と golangci-lint を mise で管理し、mise タスクとして利用できるようにする。
  • Go API スタック — HTTP サービス向けの Web フレームワークと検証スタック。
  • 品質ゲート — 同じチェック:prek と CI で同じリント・フォーマット設定を使う。
  • Git ワークフロー — コミット規律:Go の変更も標準のコミットとプルリクエストのルールに従う。
  • テスト戦略 — テストの焦点:何をどのレベルで検証するか。

採用しない代替案

単独の gofmt や goimports をプロジェクトのフォーマッターとして使わない。

gofumpt は gofmt の厳密な上位集合であり、import の並べ替えは gofumpt と golangci-lint の gci または goimports ルールで処理する。