返回 Skills
cxuu/golang-skills· Apache-2.0 内容可用

go-linting

Use when setting up linting for a Go project, configuring golangci-lint, or adding Go checks to a CI/CD pipeline. Also use when starting a new Go project and deciding which linters to enable, even if the user only asks about "code quality" or "static analysis" without mentioning specific linter names. Does not cover code review process (see go-code-review).

安装

与 skills.sh 相同的 Command / Prompt 安装方式


name: go-linting description: Use when setting up linting for a Go project, configuring golangci-lint, or adding Go checks to a CI/CD pipeline. Also use when starting a new Go project and deciding which linters to enable, even if the user only asks about "code quality" or "static analysis" without mentioning specific linter names. Does not cover code review process (see go-code-review). allowed-tools: Bash(bash:*)

Go Linting

Core Principle

More important than any "blessed" set of linters: lint consistently across a codebase.

Consistent linting helps catch common issues and establishes a high bar for code quality without being unnecessarily prescriptive.

Resource Routing

  • scripts/setup-lint.sh - Run when generating a .golangci.yml, validating the first lint pass, or producing JSON metadata.
  • assets/golangci.yml - Use as the v2 golangci-lint baseline for established projects.

Setup Procedure

  1. Create .golangci.yml with scripts/setup-lint.sh or copy assets/golangci.yml
  2. Run golangci-lint run ./...
  3. If errors appear, fix them category by category (formatting first, then vet, then style)
  4. Re-run until clean

After generating .golangci.yml, run golangci-lint config verify --config .golangci.yml to verify the configuration schema before relying on lint results.


Minimum Recommended Linters

These linters catch the most common issues while maintaining a high quality bar:

LinterPurpose
errcheckEnsure errors are handled
goimportsFormat code and manage imports
reviveCommon style mistakes (modern replacement for golint)
govetAnalyze code for common mistakes
staticcheckVarious static analysis checks

Note: revive is the modern, faster successor to the now-deprecated golint.


Lint Runner: golangci-lint

Use golangci-lint as your lint runner. See the example .golangci.yml from uber-go/guide.


Example Configuration

Use assets/golangci.yml as the maintained example. It targets golangci-lint v2 (verified with 2.10.1 on 2026-06-19), keeps goimports under formatters, and enables the core linters plus common production additions.

Running

# Install the version this skill's config is verified against
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.10.1

# Run all linters
golangci-lint run

# Run on specific paths
golangci-lint run ./pkg/...

Additional Recommended Linters

Beyond the minimum set, consider these for production projects:

LinterPurposeWhen to enable
gosecSecurity vulnerability detectionAlways for services handling user input
ineffassignDetect ineffectual assignmentsAlways — catches dead code
misspellCorrect common misspellings in comments/stringsAlways
gocycloCyclomatic complexity thresholdWhen functions exceed ~15 complexity
exhaustiveEnsure switch covers all enum valuesWhen using iota enums
bodycloseDetect unclosed HTTP response bodiesAlways for HTTP client code

Nolint Directives

When suppressing a lint finding, always explain why:

//nolint:errcheck // fire-and-forget logging; error is not actionable
_ = logger.Sync()

Rules:

  • Use //nolint:lintername — never bare //nolint
  • Place the comment on the same line as the finding
  • Include a justification after //

CI/CD Integration

Run golangci-lint run ./... in CI after tests. Pin the golangci-lint version used by CI so local and release behavior do not drift.

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit
golangci-lint run --new-from-rev=HEAD~1

Use --new-from-rev to lint only changed code, keeping the feedback loop fast.


Quick Reference

TaskCommand/Action
Install golangci-lintgo install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.10.1
Run lintersgolangci-lint run
Run on pathgolangci-lint run ./pkg/...
Config file.golangci.yml in project root
CI integrationRun golangci-lint run in pipeline
Nolint directives//nolint:name // reason — never bare //nolint
CI integrationUse golangci/golangci-lint-action for GitHub Actions
Pre-commitgolangci-lint run --new-from-rev=HEAD~1

Linter Selection Guidelines

When you need...Use
Error handling coverageerrcheck
Import formattinggoimports
Style consistencyrevive
Bug detectiongovet, staticcheck
All of the abovegolangci-lint with config

Related Skills

  • Style foundations: See go-style-core when resolving style questions that linters enforce (formatting, nesting, naming)
  • Code review: See go-code-review when combining linter output with a manual review checklist
  • Error handling: See go-error-handling when errcheck flags unhandled errors and you need to decide how to handle them
  • Testing: See go-testing when running linters alongside tests in CI pipelines

附带文件

assets/golangci.yml
version: "2"
linters:
  enable:
    # Minimum recommended
    - errcheck
    - govet
    - revive
    - staticcheck
    # Additional recommended
    - bodyclose
    - gocyclo
    - gosec
    - ineffassign
    - misspell
  settings:
    revive:
      rules:
        - name: exported
    gocyclo:
      min-complexity: 15
  exclusions:
    generated: lax
    paths:
      - third_party$
      - builtin$
      - examples$

issues:
  max-issues-per-linter: 0
  max-same-issues: 0

formatters:
  enable:
    - goimports
  exclusions:
    generated: lax
    paths:
      - third_party$
      - builtin$
      - examples$
scripts/setup-lint.sh
#!/usr/bin/env bash
set -euo pipefail

VERSION="1.0.0"
SCRIPT_NAME="$(basename "$0")"

usage() {
    cat <<EOF
$SCRIPT_NAME v$VERSION — Generate .golangci.yml and run initial lint

USAGE
    bash $SCRIPT_NAME [options] [local-prefix]

DESCRIPTION
    Creates a .golangci.yml with a curated set of linters (errcheck,
    goimports, revive, govet, staticcheck) and runs golangci-lint.
    If local-prefix is provided, configures goimports to group local
    imports separately.

    Exits 0 if lint passes, 1 if lint issues found, 2 on error.

OPTIONS
    -h, --help       Show this help message
    -v, --version    Show version
    --json           Output results as JSON
    --force          Overwrite existing .golangci.yml
    --dry-run        Print generated config to stdout without writing
    --limit N        Max lint issue lines in JSON output (default: 50, 0 = unlimited)

ARGUMENTS
    local-prefix     Module path prefix for goimports grouping
                     (e.g., github.com/myorg/myrepo)

EXAMPLES
    bash $SCRIPT_NAME
    bash $SCRIPT_NAME github.com/myorg/myrepo
    bash $SCRIPT_NAME --force github.com/myorg/myrepo
    bash $SCRIPT_NAME --dry-run github.com/myorg/myrepo
    bash $SCRIPT_NAME --json
    bash $SCRIPT_NAME --json --limit 20
EOF
}

json_escape() {
    local s="$1"
    s="${s//\\/\\\\}"
    s="${s//\"/\\\"}"
    s="${s//$'\t'/\\t}"
    s="${s//$'\r'/}"
    s="${s//$'\n'/\\n}"
    printf '%s' "$s"
}

JSON_OUTPUT=false
FORCE=false
DRY_RUN=false
LIMIT=50
LOCAL_PREFIX=""

while [[ $# -gt 0 ]]; do
    case "$1" in
        -h|--help)    usage; exit 0 ;;
        -v|--version) echo "$SCRIPT_NAME v$VERSION"; exit 0 ;;
        --json)       JSON_OUTPUT=true; shift ;;
        --force)      FORCE=true; shift ;;
        --dry-run)    DRY_RUN=true; shift ;;
        --limit)
            if [[ $# -lt 2 ]]; then
                echo "error: --limit requires a number" >&2
                exit 2
            fi
            LIMIT="$2"
            shift 2
            ;;
        -*)           echo "error: unknown option: $1" >&2; usage >&2; exit 2 ;;
        *)            LOCAL_PREFIX="$1"; shift ;;
    esac
done

if ! [[ "$LIMIT" =~ ^[0-9]+$ ]]; then
    echo "error: --limit must be a non-negative integer, got: $LIMIT" >&2
    exit 2
fi

generate_config() {
    cat <<'YAML'
version: "2"
linters:
  enable:
    # Minimum recommended
    - errcheck
    - govet
    - revive
    - staticcheck
    # Additional recommended
    - bodyclose
    - gocyclo
    - gosec
    - ineffassign
    - misspell
  settings:
    revive:
      rules:
        - name: exported
    gocyclo:
      min-complexity: 15
  exclusions:
    generated: lax
    paths:
      - third_party$
      - builtin$
      - examples$

issues:
  max-issues-per-linter: 0
  max-same-issues: 0

formatters:
  enable:
    - goimports
  exclusions:
    generated: lax
    paths:
      - third_party$
      - builtin$
      - examples$
YAML

    if [[ -n "$LOCAL_PREFIX" ]]; then
        cat <<YAML
  settings:
    goimports:
      local-prefixes:
        - ${LOCAL_PREFIX}
YAML
    fi
}

if $DRY_RUN; then
    generate_config
    exit 0
fi

CONFIG_PATH=".golangci.yml"

if [[ -f "$CONFIG_PATH" ]] && ! $FORCE; then
    echo "error: $CONFIG_PATH already exists (use --force to overwrite)" >&2
    exit 2
fi

generate_config > "$CONFIG_PATH"

LINT_OUTPUT=""
LINT_EXIT=0
if ! command -v golangci-lint &>/dev/null; then
    echo "error: golangci-lint is not installed" >&2
    exit 2
fi

LINT_OUTPUT=$(golangci-lint run ./... 2>&1) || LINT_EXIT=$?

if $JSON_OUTPUT; then
    LINT_TRUNCATED=false
    LINT_DISPLAY="$LINT_OUTPUT"
    if [[ $LIMIT -gt 0 && -n "$LINT_OUTPUT" ]]; then
        LINT_ARR=()
        while IFS= read -r line; do
            LINT_ARR+=("$line")
        done <<< "$LINT_OUTPUT"
        if [[ ${#LINT_ARR[@]} -gt $LIMIT ]]; then
            LINT_DISPLAY=""
            for (( i=0; i<LIMIT; i++ )); do
                [[ -n "$LINT_DISPLAY" ]] && LINT_DISPLAY+=$'\n'
                LINT_DISPLAY+="${LINT_ARR[$i]}"
            done
            LINT_TRUNCATED=true
        fi
    fi
    LINT_ESC="$(json_escape "$LINT_DISPLAY")"
    CONFIG_ESC="$(json_escape "$CONFIG_PATH")"
    PREFIX_ESC="$(json_escape "$LOCAL_PREFIX")"
    CREATED=true
    HAS_ISSUES=$( [[ $LINT_EXIT -ne 0 ]] && echo true || echo false )
    TRUNC_FIELD=""
    $LINT_TRUNCATED && TRUNC_FIELD=',"truncated":true'
    cat <<EOF
{"config_path":"$CONFIG_ESC","local_prefix":"$PREFIX_ESC","created":$CREATED,"lint_issues":$HAS_ISSUES,"lint_output":"$LINT_ESC"$TRUNC_FIELD}
EOF
else
    echo "Created $CONFIG_PATH"
    if [[ $LINT_EXIT -ne 0 ]]; then
        echo ""
        echo "$LINT_OUTPUT"
        echo ""
        echo "Lint issues found — fix them category by category (formatting first, then vet, then style)."
    else
        echo "golangci-lint: all clean."
    fi
fi

if [[ $LINT_EXIT -ne 0 ]]; then
    exit 1
fi
exit 0
    go-linting | Prompt Minder