Goのlinter入門|golangci-lintの仕組みと主要なlinter・設定方法まとめ

ブログ
Goのlinter入門|golangci-lintの仕組みと主要なlinter・設定方法まとめ

Goのlinter入門

Goでコードの品質を保つために欠かせないのがlinter(静的解析ツール)です。
Goのlinterはたくさんあり、それらをまとめて実行するgolangci-lintというツールが広く使われています。

golangci-lintとは

golangci-lintは、Goのlinterをまとめて実行できる linterランナー です。
Go開発ではほぼ標準的に使われています。

主な特徴は次のとおりです。

  • 複数のlinterを一括実行:100種類以上のlinterを1つのコマンドで実行できます。
  • 高速:linterを並列で実行し、パース結果や型情報をlinter間で共有します。結果はキャッシュされます。
  • 設定ファイルで一元管理:.golangci.yml に、どのlinterを使うか、除外ルール、linterごとの設定を書きます。
  • 差分だけをチェック:--new-from-rev などで、変更した箇所だけを検査できます。既存プロジェクトに後から導入するときに便利です。
  • 自動修正:--fix で、一部の指摘を自動修正できます。
  • CI連携:公式のGitHub Action(golangci/golangci-lint-action)があります。
# 実行
golangci-lint run ./...

# 利用可能なlinterの一覧
golangci-lint linters

なお、2025年にv2がリリースされ、設定ファイルの形式がv1から大きく変わっています。

golangci-lintとlinterの関係

golangci-lintは「実行役」です。実際に何をチェックするかは、それぞれのlinterが独立したプロジェクトとして、別々の開発者によって作られています。

全体の階層は次のようになっています。

golangci-lint(ランナー)
├── staticcheck(linter)
│     ├── SA
│     ├── S
│     ├── ST
│     ├── QF
│     └── U
├── errcheck(linter)
├── ineffassign(linter)
├── unused(linter)
├── govet(linter)
└── ...

staticcheckの下にあるSAやSTは「staticcheckという1つのlinterの中の分類」です。errcheckやineffassignは、staticcheckと並ぶ「別のlinter」です。

golangci-lintとlinterの関係について、押さえておきたい点が3つあります。

  1. 外部コマンドを呼び出しているわけではない:golangci-lintは各linterをライブラリとして取り込み、1つのバイナリにまとめています。各linterを個別にインストールする必要はありません。その代わり、各linterのバージョンはgolangci-lintのバージョンに依存します。
  2. 共通の解析基盤がある:多くのlinterはGo公式の解析フレームワーク golang.org/x/tools/go/analysis に沿って作られています。golangci-lintはパース結果や型情報を共有して並列実行するので高速です。
  3. 単体でも使える:staticcheckやerrcheckなどは、golangci-lintを使わずに単体のコマンドとしても実行できます。

標準で有効になる5つのlinter

# 利用可能なlinterの一覧を表示する
golangci-lint linters

golangci-lint v2では、設定なしで実行すると 標準セット(default: standard) の5つのlinterが動きます。

linter内容作者・開発元リポジトリ
staticcheckバグ、誤用、簡略化、スタイルなどを幅広く検出Dominik Honnef氏dominikh/go-tools
unused未使用の関数・型・変数・定数を検出Dominik Honnef氏dominikh/go-tools
errcheckエラーの戻り値の無視を検出Kamil Kisiel氏kisielk/errcheck
ineffassign代入したのに使われない値を検出Gordon Klaus氏gordonklaus/ineffassign
govetGo公式のvetチェックGo公式チームgolang.org/x/tools

staticcheckとunusedは同じプロジェクト

意外なのは、unusedがstaticcheckと同じ作者のツール だという点です。どちらもdominikh/go-toolsリポジトリに含まれていて、unusedはstaticcheckのU1000チェックと同じエンジンです。golangci-lintでは独立したlinterとして扱われていますが、中身は同じプロジェクトです。

govetはGo公式のコード

govetの中身は、golang.org/x/tools/go/analysis/passes 配下の解析パス(shadow、errorsasなど)です。go vet コマンドと同じくGo公式のコードです。

ineffassignとstaticcheckの重なり

ineffassignはstaticcheckの中の分類ではなく、独立したlinterです。ただし、staticcheckの SA4006(代入した値が使われない)と趣旨はほぼ同じです。

func f() error {
    err := doA()   // この値は確認されないまま上書きされる
    err = doB()
    return err
}

この例では doA() のエラーを確認し忘れている可能性が高く、バグの手がかりになります。

ineffassignは型情報を使わずに解析するため、構造体フィールドへの代入などは検出しません。その代わり誤検知は出さない設計になっています。標準セットには両方が含まれています。

errcheckの設定

errcheckには、staticcheckのようなチェックコードの分類はありません。「エラーの戻り値を無視していないか」という1種類のチェックだけを行い、検査範囲をオプションで調整します。

オプション内容
check-type-assertionsv := x.(T) のようにokを受け取らない型アサーションも検出する
check-blank_ = f() のように _ で捨てたエラーも検出する
disable-default-exclusionsデフォルトの除外対象(fmt.Println など)も検出対象にする
exclude-functions指定した関数を検出対象から除外する

staticcheckのチェック種別

staticcheckのチェックは、コードの接頭辞で分類されています。

接頭辞分類内容
SAstaticcheckバグや誤用の検出(中心となるカテゴリ)
Ssimpleより簡潔に書ける箇所の指摘
STstylecheckスタイルや命名規則の指摘
QFquickfixエディタで使うリファクタリング提案
Uunused未使用のコードの検出(U1000)

SAはさらに次のように分かれています。

コード内容
SA1xxx標準ライブラリの誤用
SA2xxx並行処理の問題
SA3xxxテストコードの問題
SA4xxx実質的に何もしていないコード
SA5xxx正しさに関する問題
SA6xxxパフォーマンスの問題
SA9xxx疑わしいコード構造

golangci-lint v2では、以前は別々のlinterだったgosimple(S)とstylecheck(ST)がstaticcheckに統合されています。

主要なlinter一覧(目的別)

標準セットの5つ(★)と、よく使われるlinterを目的別にまとめました。

バグ・品質系

linter内容
★ staticcheckバグ、誤用、簡略化、スタイルなどを幅広く検出
★ govetGo公式のvetチェック(Printfの書式ミス、構造体のコピーなど)
gocriticバグ、スタイル、パフォーマンスの多数のチェックをまとめたlinter
exhaustiveenum的な定数に対するswitchでcaseの漏れを検出

エラー処理系

linter内容
★ errcheckエラーの戻り値の無視を検出
errorlinterrors.Is / errors.As を使うべき箇所の誤用を検出
wrapcheck外部パッケージのエラーをラップせずに返している箇所を検出
nilerrerrがnilでないのにnilを返している箇所を検出

不要コード系

linter内容
★ unused未使用の関数・型・変数・定数を検出
★ ineffassign代入したのに使われない値を検出
unparam使われていない引数や、常に同じ値を返す戻り値を検出

リソース管理系(Webサーバーで特に有用)

linter内容
bodycloseHTTPレスポンスボディのClose漏れを検出
noctxcontextを渡さずにHTTPリクエストを送っている箇所を検出
sqlclosechecksql.Rows などのClose漏れを検出
rowserrcheckrows.Err() の確認漏れを検出

セキュリティ系

linter内容
gosecSQLインジェクション、ハードコードされた認証情報、弱い暗号などを検出

スタイル・可読性系

linter内容
revivegolintの後継。ルールを細かく設定できる
misspellコメントや文字列中の英単語のスペルミスを検出
goconst繰り返し出てくる文字列リテラルを定数化するよう提案
dupl重複したコードを検出
nakedret長い関数でのnaked returnを検出
lll1行が長すぎる箇所を検出

複雑度系

linter内容
gocyclo循環的複雑度が高い関数を検出
gocognit認知的複雑度が高い関数を検出
funlen長すぎる関数を検出

パフォーマンス系

linter内容
prealloc事前に容量を確保できるスライスを検出

フォーマッター(v2ではformattersに分類)

ツール内容
gofmt標準のフォーマッター
goimportsimportの整理とgofmt
gofumptgofmtより厳しいフォーマッター

標準セットに加えるなら、まずは gosec、bodyclose、errorlint、gocritic、revive あたりが定番です。Webサーバーのリポジトリであれば、bodyclose、noctx、sqlclosecheck も効果が出やすいです。

使うlinterの設定方法

設定ファイルの場所

プロジェクトのルート(go.mod があるディレクトリ)に .golangci.yml を置きます。.golangci.yaml、.golangci.toml、.golangci.json でも構いません。golangci-lintは実行したディレクトリから親に向かって設定ファイルを探します。--config で場所を直接指定することもできます。

書き方(v2形式)

version: "2"

linters:
  # 基本セットの選び方
  default: standard   # standard / all / none / fast

  # 基本セットに追加するlinter
  enable:
    - gosec
    - bodyclose
    - errorlint
    - revive

  # 基本セットから外すlinter
  disable:
    - ineffassign

  # linterごとの詳細設定
  settings:
    staticcheck:
      checks:
        - all
        - -ST1000   # パッケージコメントの指摘を無効化
    errcheck:
      check-type-assertions: true

formatters:
  enable:
    - gofmt
    - goimports

default の選択肢は次のとおりです。

値意味
standard標準セット(staticcheck、errcheck、unused、govet、ineffassign)。省略時はこれ
none何も有効にしない。enable に書いたものだけを使う
allすべて有効にする。disable で外していく
fast高速に動くlinterだけを有効にする

標準セットに足していく書き方がおすすめです。何が動いているかを明確にしたい場合は、default: none にして使うlinterを全部 enable に書きます。

コマンドラインで指定する

設定ファイルを変えずに一時的に試すときに使えます。

# 指定したlinterを追加で有効にする
golangci-lint run --enable gosec,bodyclose ./...

# 指定したlinterを無効にする
golangci-lint run --disable errcheck ./...

v1形式との違い

古い設定ファイルを見かけたときのために、主な違いをまとめておきます。

v1v2
version の記述なしversion: "2" が必須
disable-all: truedefault: none
enable-all: truedefault: all
linters-settings:(トップレベル)linters.settings:
gofmtなども linters に書くformatters に分離
gosimple、stylecheckが独立したlinterstaticcheckに統合

既存のv1設定は golangci-lint migrate でv2形式に変換できます。

一覧へ戻る