.golangci.yml

# golangci-lint v2 config.
#
# Why gci instead of goimports here: golangci-lint v2 ships a vendored
# goimports whose grouping disagrees with the upstream `goimports` CLI on
# this repo's short module name (`go-skeleton`, no dot — gets misread as
# stdlib). gci lets us declare the import sections explicitly, which is
# what we actually want.
#
# Why gofumpt: strict superset of gofmt, picks up the readability rules
# gofmt doesn't enforce (multi-line struct alignment, redundant blank
# lines, long-call argument formatting, etc.).
#
# Order matters: golangci-lint v2 runs gofumpt first, then gci. If we
# ran gci before gofumpt, gofumpt would re-shuffle imports because it
# falls back to gofmt's stdlib heuristic and treats `go-skeleton/...`
# as stdlib. v2 sequences them correctly for us.
#
# Tool versions are pinned by the Makefile (GCI_VERSION /
# GOFUMPT_VERSION); `make init` keeps locally installed binaries
# aligned with these pins.

version: "2"

formatters:
  enable:
    - gofumpt
    - gci
  settings:
    gofumpt:
      # Must be set explicitly: golangci-lint's embedded gofumpt does not
      # auto-detect `module` from go.mod the way the standalone gofumpt
      # binary or gopls does. Without it gofumpt groups our packages as
      # third-party and the linter flags random files as "not gofumpt-ed".
      # https://github.com/golangci/golangci-lint/issues/4004
      module-path: go-skeleton
      extra-rules: true
    gci:
      # standard         → "errors", "net/http", ...
      # default          → everything not matched (third-party deps)
      # prefix(go-skel)  → this repo's packages
      sections:
        - standard
        - default
        - prefix(go-skeleton)
      # Don't auto-rewrite import blanks/dot imports (e.g. _ "embed").
      custom-order: true
  exclusions:
    # Generated code shouldn't be reformatted — `make oapi` owns it.
    paths:
      - internal/oapi

linters:
  # 显式开 errcheck：v2 默认就包含，但显式 enable 在 lint 报告里更明确，且
  # 配套 settings.errcheck.exclude-functions 列出"故意忽略返回值"的常见点。
  enable:
    - errcheck
  settings:
    errcheck:
      # 这些函数返回的 error 在多数业务里是无意义的：
      # - gin.Context.Error 只是把 err 塞 c.Errors 链供后续中间件读，写日志侧
      #   已经在 Recovery / handler 里处理过；
      # - fmt.Fprint* 写 ResponseWriter / Stderr 的 error 在我们的场景不可控；
      # - http.Server.Shutdown 的 err 已由 cmd/api/main.go 走 applog.Warn 接住，
      #   多余的 errcheck 报警会引导写没必要的 _ = 赋值。
      exclude-functions:
        - (*github.com/gin-gonic/gin.Context).Error
        - fmt.Fprint
        - fmt.Fprintf
        - fmt.Fprintln
  exclusions:
    paths:
      - internal/oapi