golangci-lint Environment Setup

Core Principle: Make existing code pass lint by adjusting configuration, do not modify existing code. Only affects new code.

When to Use

• Initializing Go projects and need to add linter
• Adding code quality checks to existing projects
• Integrating lint into CI/CD workflows

Execution Flow

1. Detect Environment

# Check Go version in go.mod (priority)
cat go.mod | grep "^go "

# Check system Go version (reference)
go version

# Check for existing configuration (supports 4 formats)
ls .golangci.* 2>/dev/null || echo "No config"

# Check CI configuration
ls .gitlab-ci.yml .github/workflows/*.yml .circleci/config.yml 2>/dev/null

# Check for Makefile
ls Makefile 2>/dev/null && echo "Has Makefile" || echo "No Makefile"

2. Select Version

go.mod

3. Install

# v2 (recommended)
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin latest

# v1
# curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.59.1

# Verify
$(go env GOPATH)/bin/golangci-lint --version

3.5. Configuration Migration (when v1 config exists)

.golangci.yml

# Automatically migrate v1 config to v2 format
$(go env GOPATH)/bin/golangci-lint migrate --skip-validation

# Notes:
# --skip-validation: Skip validation, convert directly (recommended)
# migrate command will automatically:
#   - Add version: 2
#   - Convert enable-all/disable-all to linters.default
#   - Change linters-settings to linters.settings
#   - Change issues.exclude-rules to linters.exclusions.rules

• linters.default

  value meets expectations (standard/all/none/fast)
• Disabled linters still have

  # TODO fix later by human

  comments
• Complexity thresholds are raised and marked with

  # TODO reduce this

4. Create Configuration

.golangci.yml

📌 AI Operation Requirements:

1. Must first visit official documentation to confirm latest format: https://golangci-lint.run/docs/configuration/file/
2. Core Principle: Do not modify existing code, only make code pass by adjusting configuration (settings/disable/exclusions)
3. Formatters Handling:
   • First run

     gofmt -l .

     and

     goimports -l .

     to check code format
   • If both have no output → enable formatters (uncomment)
   • If has output → keep commented, add

     # TODO format code and enable - X files currently non-compliant

     above
4. Workflow: Create minimal config → Run lint → Categorize and handle → Add standardized TODO comments
5. Universal Classification Logic (based on keywords in linter description):
   Step 1: Get linter description
   bash

   $(go env GOPATH)/bin/golangci-lint help <linter-name>

   Step 2: Categorize based on keywords in description

   Category	Keywords in Description	Action	Example Linters & Descriptions
   a. Configurable	complexity, long, deeply, count, length, size, max, min, limit	Adjust settings	funlen: "Checks for long functions"<br>gocyclo: "Checks cyclomatic complexity"<br>nestif: "Reports deeply nested if"<br>dogsled: "Checks too many blank identifiers"
   b. Code Style-Manual Confirm	style, format, naming, whitespace, align, order, declaration	disable + TODO	godot: "Check if comments end in period"<br>tagalign: "Check struct tags well aligned"<br>misspell: "Finds commonly misspelled"<br>varnamelen: "Checks variable name length"
   c. Critical Bugs-Suggest Fix	bug, security, error, check, nil, unsafe, detect, inspects	disable + TODO	errcheck: "Checking for unchecked errors"<br>gosec: "Inspects source code for security"<br>staticcheck: "set of rules from staticcheck"<br>nilerr: "returns nil even if error is not nil"
   d. Cannot Modify	(check specific error message, usually involves external constraints)	exclusions	canonicalheader: HTTP header spec (3rd-party APIs)<br>asciicheck: Non-ASCII symbols (Chinese function names)
   e. Can Fix Small	(determined by actual issue count, < 5)	exclude-rules	Any linter with few issues
   f. New Features-Defer	modern, new, latest, replace, simplification, feature	disable + TODO	modernize: "suggest simplifications using modern language"<br>exptostd: "replaced by std functions"<br>usestdlibvars: "use variables from standard library"

   Step 3: Complete Decision Tree

   1. Issue count < 5?
      ├── Yes → Category e (can fix small): exclude-rules
      └── No → Continue
   2. Description has complexity/long/deeply/max/min/limit/length?
      ├── Yes → Category a (configurable): Prioritize adjusting settings
      └── No → Continue
   3. Specific error caused by external constraints (3rd-party APIs/generated code/Chinese naming)?
      ├── Yes → Category d (cannot modify): exclusions path exclusion
      └── No → Continue
   4. Description has modern/new/latest/replace/std/simplification?
      ├── Yes → Category f (new features-defer): disable + TODO
      └── No → Continue
   5. Description has bug/security/error/check/nil/unsafe/detect/inspects?
      ├── Yes → Category c (critical bugs-suggest fix): disable + TODO
      └── No → Category b (code style-manual confirm): disable + TODO

   Example Demonstrations:

   Linter	Description	Keywords	Category
   cyclop	"Checks function complexity"	complexity	a
   gocritic	"checks for bugs, performance and style"	bugs (priority)	c
   revive	"replacement of golint"	(no clear keywords)	b
   bodyclose	"Checks whether response body is closed successfully"	error/check	c
   goconst	"Finds repeated strings that could be replaced by a constant"	(style)	b
   fatcontext	"Detects nested contexts"	nested → complexity	a

6. Configuration Priority:
   • 1st Priority: Adjust

     settings

     thresholds (e.g., funlen.lines, gocyclo.min-complexity)
   • 2nd Priority: Use

     linters.exclusions

     path exclusion (code that cannot be modified)
   • 3rd Priority: Use

     issues.exclude-rules

     rule-based exclusion (specific few issues)
   • Last Resort: Completely

     disable

     (many issues and cannot be resolved via config)
7. Avoid Duplicates: Each linter appears only once, check for duplicates

version: "2"

run:
  concurrency: 4
  timeout: 5m
  skip-dirs: [vendor, third_party, testdata, examples, gen-go]
  tests: true

output:
  format: colored-line-number
  print-linter-name: true

linters:
  default: all

formatters:
  enable:
    # TODO format code and enable - 17 files currently non-compliant with goimports
    # - gofmt
    # - goimports

Formatters Handling: First run

gofmt -l .

and

goimports -l .

to check, uncomment to enable if both have no output.

Notes:

• Start with minimal configuration, no preset disable
• After running, gradually add

  disable

  and

  exclusions

  based on errors
• Common linters that need adjustment (add as needed):

  • mnd

    (magic numbers) → style issues, can be permanently ignored

  • wsl

    (whitespace) → style issues, can be permanently ignored

  • lll

    (line length) → style issues, can be permanently ignored

  • err113

    → error handling, temporarily ignore and mark TODO

Note: v1 does not require

version

field. v2 is recommended.

run:
  concurrency: 4
  timeout: 5m
  skip-dirs: [vendor, testdata]

linters:
  enable-all: true

After running, add

disable

and

exclude-rules

based on errors.

5. Integrate CI

lint:
  stage: test
  image: golang:1.23-alpine
  script:
    - curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin latest
    - $(go env GOPATH)/bin/golangci-lint run --timeout=5m ./...

- name: golangci-lint
  uses: golangci/golangci-lint-action@v6
  with:
    version: latest

6. Update Makefile (Optional)

lint:  ## Run lint check
	golangci-lint run --timeout=5m ./...

lint-fix:  ## Auto-fix issues
	golangci-lint run --fix --timeout=5m ./...

7. Run and Adjust as Needed

# Run lint
$(go env GOPATH)/bin/golangci-lint run --timeout=5m ./...

Important: Resolve issues by adjusting configuration, do not modify existing code.

1. Linter Name Errors (e.g.,

   unknown linters

   ):
   bash

   # View supported linters
   $(go env GOPATH)/bin/golangci-lint help linters

   • gomnd

     →

     mnd

   • goerr113

     →

     err113

   • execinquery

     → removed
2. Configuration Format Errors:

   • output.formats

     needs map format, not list
   • Use singular form

     output.format

3. Adjust Configuration Based on Actual Errors:
   Configuration Priority (try in order):

   Priority	Action	Use Case
   1️⃣ Highest	Adjust settings thresholds	Linters with config options for complexity/length
   2️⃣ Second	linters.exclusions path exclusion	Code that cannot be modified (generated/3rd-party)
   3️⃣ Then	issues.exclude-rules rule exclusion	Specific few issues
   4️⃣ Last	disable completely	Many issues and no config options

   Category a: Configurable (Prioritize adjusting settings)
   yaml

   linters:
     settings:
       # Complexity linters: Prioritize adjusting thresholds rather than completely disabling
       funlen:
         lines: 100        # Default 60, raised to accommodate existing code
         statements: 60    # Default 40
       gocyclo:
         min-complexity: 25  # Default 15
       gocognit:
         min-complexity: 30  # Default 15
       nestif:
         min-complexity: 8   # Default 5
       # If still have issues after adjusting thresholds, then consider disable

   Category b: Code Style-Manual Confirm
   yaml

   linters:
     disable:
       # TODO code style-confirm whether to disable: Does not affect functionality, requires manual confirmation
       - mnd              # 47 issues: magic numbers, style issues
       - wsl              # 39 issues: whitespace, deprecated, replaced by wsl_v5
       - wsl_v5           # 50 issues: whitespace v5, code style
       - lll              # 46 issues: line length limit, style issues
       - godot            # 3 issues: comment period
       - tagalign         # 12 issues: struct tag alignment
       - tagliatelle      # 50 issues: struct tag naming convention
       - whitespace       # 3 issues: whitespace issues
       - goconst          # 7 issues: constant extraction suggestion
       - prealloc         # 2 issues: pre-allocate slice suggestion
       - nakedret         # 1 issue: naked return
       - nlreturn         # 9 issues: blank line before return
       - inamedparam      # 1 issue: named parameter
       - varnamelen       # 23 issues: variable name length
       - nonamedreturns   # 2 issues: named return values
       - paralleltest     # 47 issues: parallel test suggestion
       - testpackage      # 3 issues: test package naming
       - testifylint      # 3 issues: testify usage convention
       - ireturn          # 4 issues: interface return
       - intrange         # 3 issues: int range loop
       - nilnil           # 3 issues: nil interface
       - nilnesserr       # 3 issues: nil error check
       - noinlineerr      # 3 issues: inline error
       - gosmopolitan     # 3 issues: internationalization
       - usestdlibvars    # 1 issue: standard library constants
       - unparam          # 1 issue: unused parameter
       - perfsprint       # 9 issues: performance print suggestion

   Category c: Critical Bugs-Suggest Fix
   yaml

   linters:
     disable:
       # TODO critical bugs-suggest fix: Security and error handling issues, recommend gradual fixes
       - errcheck         # 13 issues: unchecked errors
       - gosec            # 10 issues: security checks
       - staticcheck      # 8 issues: static analysis
       - rowserrcheck     # 3 issues: database rows.Err check
       - errchkjson       # 4 issues: JSON error check
       - errorlint        # 1 issue: error handling convention
       - errname          # 2 issues: error variable naming
       - wrapcheck       # 44 issues: error wrapping
       - noctx            # 3 issues: context parameter check
       - forcetypeassert  # 2 issues: force type assertion
       - contextcheck     # 4 issues: context passing check
       - nilerr           # nil error check
       - govet            # 1 issue: vet check
       - unused           # 16 issues: unused variables/packages
       - err113           # 21 issues: dynamic error definition
       - ineffassign      # 1 issue: ineffective assignment
       - sqlclosecheck    # 3 issues: SQL not closed check
       - wastedassign     # 2 issues: wasted assignment

   Category d: Cannot Modify (Path Exclusion)
   yaml

   linters:
     exclusions:
       rules:
         # Generated code (cannot modify)
         - path: \.pb\.go|\.gen\.go|\.gen-\w+\.go|\.mock\.go
           linters: [all]
   
         # Third-party dependencies (cannot modify)
         - path: vendor/|third_party/
           linters: [all]
   
         # Example code (optionally modifiable)
         - path: examples/
           linters: [all]
   
   issues:
     exclude-rules:
       # Third-party APIs (cannot modify)
       - text: "non-canonical header"
         linters: [canonicalheader]
   
       # Chinese function names (business requirement, cannot modify)
       - text: "ID.*must match"
         linters: [asciicheck]
   
       # Internal project using internal packages (business requirement)
       - text: "import of package"
         linters: [depguard]

   Category e: Can Fix Small (Few Specific Issues)
   yaml

   issues:
     exclude-rules:
       # Specific business scenarios (cannot modify)
       - text: "G101: potential hardcoded credential"
         path: config/.*\.go
         linters: [gosec]
   
       # Relax for test files
       - path: _test\.go
         linters: [errcheck, gosec, contextcheck]
   
       # Relax for main function
       - path: cmd/
         linters: [gocyclo, funlen, errcheck]

   Category f: New Features-Defer
   yaml

   linters:
     disable:
       # TODO new features-defer: Does not affect current code, can be selectively enabled later
       - modernize        # 12 issues: modern Go syntax suggestions
       - revive           # 48 issues: revive ruleset
       - gocritic         # 10 issues: code style suggestions
       - godoclint        # 3 issues: godoc format
       - gomoddirectives  # module directive check
       - dogsled          # blank identifier count
       - embeddedstructfieldcheck # 2 issues: embedded field blank lines
       - exhaustruct      # 49 issues: struct field completeness
       - forbidigo        # 6 issues: forbid specific functions
       - gochecknoglobals # 15 issues: global variable check
       - gochecknoinits   # 2 issues: init function check
       - godox            # 2 issues: TODO/FIXME markers
       - nolintlint       # 1 issue: nolint comment check

8. Final Verification

# Run again to ensure pass
$(go env GOPATH)/bin/golangci-lint run --timeout=5m ./...

# Or use make
make lint

Output Report Template

# golangci-lint Configuration Complete

## Environment Information
- Go Version (go.mod): go 1.23
- golangci-lint Version: v2.8.0

## Configuration
- Created: .golangci.yml (version: 2)
- Initial Config: linters.default: all (minimal config)

## Issue Handling

### Handling Priority

| Priority | Method | Linters |
|----------|--------|---------|
| 1️⃣ Adjust settings | Threshold tuning | funlen, gocyclo, gocognit, nestif |
| 2️⃣ exclusions | Path exclusion | Generated code, 3rd-party dependencies, specific APIs |
| 3️⃣ exclude-rules | Rule exclusion | Test files, specific business scenarios |
| 4️⃣ disable | Completely disable | Linters with many issues |

### Linter Category Statistics

| Category | Count | Description |
|----------|-------|-------------|
| a. Configurable | 4 | Prioritize adjusting settings thresholds |
| b. Code Style-Manual Confirm | 26 | Style issues, need confirmation whether to disable |
| c. Critical Bugs-Suggest Fix | 18 | Security/error handling, recommend fixing |
| d. Cannot Modify | - | Path exclusion (external constraints) |
| e. Can Fix Small | - | Issues exclusion (few issues) |
| f. New Features-Defer | 13 | New features, consider later |

### Settings Threshold Adjustments
```yaml
linters:
  settings:
    funlen:
      lines: 100        # Default 60
      statements: 60    # Default 40
    gocyclo:
      min-complexity: 25  # Default 15
    gocognit:
      min-complexity: 30  # Default 15
    nestif:
      min-complexity: 8   # Default 5

Path Exclusions (Cannot Modify)

• Generated code:

  .pb.go

  ,

  .gen.go

  ,

  .mock.go

• Third-party dependencies:

  vendor/

  ,

  third_party/

• Example code:

  examples/

Issues Exclusions (Specific Scenarios)

• Third-party APIs:

  non-canonical header

  (canonicalheader)
• Chinese function names:

  ID.*must match

  (asciicheck)
• Test files: Relax errcheck, gosec, contextcheck

Next Steps

1. New code must pass lint
2. Prioritize fixing issues in "c. Critical Bugs-Suggest Fix" category
3. After code improvements, gradually reduce complexity thresholds
4. Regularly run

   make lint

   checks

## Notes

1. **Core Principle**: **Do not modify existing code**, only adjust configuration to make code pass lint
2. **v2 Configuration Format**: Must add `version: 2`, use `linters.default` instead of `enable-all`
3. **Do Not Modify Existing Configuration**
4. **Style Issues Can Be Permanently Ignored**: Function length, cyclomatic complexity, etc. do not affect functionality
5. **Critical Issues Need Fix Reminders**: errcheck, gosec, staticcheck, etc. (exclude via config, do not fix directly)
6. **New Code Must Not Bypass Checks**
7. **CI Needs Sufficient Resources**: Recommend at least 2GB memory

## Related Resources

- [Official Documentation](https://golangci-lint.run/)
- [Supported Linters](https://golangci-lint.run/usage/linters/)