Web服务golangci-lint必须显式启用staticcheck、exhaustive、nilaway、gosec，禁用maligned、scopelint等无关linter，以精准拦截HTTP handler中error未处理、switch缺default、nil指针panic及安全漏洞等高频线上故障。
Web 服务项目对稳定性、可观测性和并发安全要求高，golangci-lint 配置不能套用通用模板——必须显式启用 staticcheck、exhaustive、nilaway 和 gosec，同时禁用所有已归档或与 HTTP 语义无关的 linter（如 maligned、scopelint），否则会漏掉 http.HandlerFunc 中未处理 error、switch r.Method 缺少 default、JSON 解析后未校验 nil 指针等高频线上故障点。
必须启用的 4 个 Web 关键 linter
Web 服务的错误传播链长、请求生命周期复杂，仅靠 govet 和 errcheck 远不够：
-
staticcheck：唯一能捕获time.After在 handler 循环中滥用、sql.Rows.Close()忘记调用、context.WithTimeout后未 defer cancel 的 linter；需在.golangci.yml的linters.enable下显式添加，它默认被禁用 -
exhaustive：强制switch r.Method或switch status覆盖全部分支，避免新增HTTP PATCH后 handler 返回 501 却无日志；注意它依赖 Go 1.23+ 的iter包，旧版本会静默跳过 -
nilaway：专治json.Unmarshal(req.Body, &v)后直接v.Field导致 panic；它不依赖类型断言，而是基于控制流分析 nil 可达性，比staticcheck的SA5011更早拦截 -
gosec：检测硬编码 token、http.ListenAndServe(":8080", nil)缺少 TLS、os.ReadFile读取配置未限制大小等安全红线；禁用G101（密码硬编码）和G304（文件路径拼接）是常见误配，这两项必须保留
Web 场景下要禁用的 linter 及原因
Web 服务大量使用中间件、反射注册和动态路由，部分 linter 会产生大量误报或与框架行为冲突：
-
golint：已归档，且其风格建议（如函数名大写）与 Gin/Echo 的MiddlewareFunc命名习惯冲突，直接禁用 -
maligned：结构体字段对齐优化对 HTTP 请求/响应体内存布局无实际收益，反而因字段重排导致json.Marshal输出顺序变化，影响前端依赖字段顺序的逻辑 -
scopelint：Web handler 中常有var err error被多个if err != nil复用，它会误报“变量重复声明”，但这是刻意为之的错误传播模式 -
lll（行长度检查）：禁用，因为 Swagger 注释、OpenAPI Schema 定义、SQL 查询字符串天然超长，强行换行反而降低可读性
CI 中 --out-format 和 issues 的 Web 专项调优
Web 服务 CI 流水线需快速定位 PR 中引入的 HTTP 层问题，输出格式和问题阈值必须匹配这一目标：
立即学习“go语言免费学习笔记（深入）”；
- GitHub Actions 必须用
--out-format=github-actions命令行参数，即使.golangci.yml里写了output.formats；否则 CI 日志只显示彩色终端文本，PR 页面不会自动标注问题行 -
max-issues-per-linter: 0（不限制）：Web 项目常因一个中间件 bug 引发下游 20+ handler 连锁报错，设为默认 50 会截断关键链路 -
max-same-issues: 0：禁用合并，因为SA1021（循环中 time.After）在多个 handler 里出现，说明架构设计有问题，不能折叠成“同一问题出现 N 次” -
exclude-rules应排除**/mocks/**和**/testdata/**，但**不能**排除**/handlers/**或**/middleware/**—— 这些才是检查重点
GoLand 实时检查绑定 Web 开发工作流
Web 开发调试周期短，IDE 必须秒级反馈 handler 层问题，不能依赖手动 run：
- GoLand 的
Settings → Go → 静态分析器中，“Path” 必须填绝对路径（如/home/you/go/bin/golangci-lint），填golangci-lint或依赖$PATH会导致灰显失效 - 勾选 “Use configuration” 并指向项目根目录的
.golangci.yml，否则 IDE 仍跑默认内置规则，nilaway和exhaustive不生效 - File Watcher 的
Arguments设为run -c .golangci.yml --fast --out：其中--fast跳过unused等非 Web 关键检查，提速 40% 以上，但保留staticcheck和gosec - 关闭 IDE 自带的
Vet和Unused code检查，否则与golangci-lint冗余报错，handler 函数上会叠加两层波浪线
Web 服务 lint 配置最难的不是加哪些规则，而是理解每个 linter 在请求生命周期中的作用位置——比如 nilaway 在 decode 阶段起效，exhaustive 在路由分发阶段起效，gosec 在启动初始化阶段起效。漏掉任一环节，都可能让一个 nil panic 或未授权访问逃过静态检查。
