golangci-lint run不报API风格问题，是因为默认仅启用govet和errcheck，而revive（需配置exported/var-naming等规则）、swag（校验Swagger注释）和staticcheck（SA1019检查弃用HTTP函数）等API相关linter均被关闭；多module项目须每个子模块单独配置.golangci.yml，且CI/IDE中必须显式指定--config=.golangci.yml才生效。
为什么 golangci-lint run 不报 API 风格问题
默认配置下，golangci-lint 根本不检查 API 命名、注释结构、HTTP 方法一致性这些规范——它只开 govet 和 errcheck，而真正管 API 规范的 linter（比如 revive 的自定义规则、swag 的注释校验）全被关着。你跑通命令 ≠ 有 API 检查。
必须启用的 API 相关 linter 组合
光靠官方工具不够，得组合使用：
-
revive：启用exported、var-naming、function-length等规则，强制导出函数/类型首字母大写、避免my_api_handler这类命名 -
swag：不是 linter，但它是唯一能静态验证 Swagger 注释是否合法的工具；运行swag init -d ./internal/handler -g ./cmd/server/main.go会直接报错 if// @Summary缺失或// @Param类型写错 -
staticcheck：开启SA1019（调用弃用 HTTP handler 函数如http.Handle而非http.HandleFunc），间接约束 API 接口层写法
注意：golint 已归档，别再用；revive 是它的替代品，且支持 YAML 规则开关。
.golangci.yml 中要写的 API 强制项
以下配置片段直接贴进和 go.mod 同级的 .golangci.yml 即可生效：
立即学习“go语言免费学习笔记（深入）”；
linters-settings:
revive:
rules:
- name: exported
disabled: false
- name: var-naming
disabled: false
- name: function-length
disabled: false
arguments: [20] # 超过 20 行函数标黄，提醒拆分 API handler
run:
skip-dirs:
- "docs" # swag 生成的 docs/ 不扫
- "migrations"
issues:
exclude-rules:
- path: "_test\.go$" # 测试文件不强求 API 注释
- text: "exported.*func.*should have comment" # 允许部分测试辅助函数跳过
linters:
- revive
- staticcheck
- govet多 module 项目里，每个含 go.mod 的子模块（比如 api/、internal/handler/）都得单独放一份这个配置，不能只在根目录放一个。
CI 和本地开发中容易漏掉的三件事
API 规范检查常在 CI 里失效，原因很具体：
- CI 脚本没加
--config=.golangci.yml，导致读的是默认极简配置 -
swag init没放在golangci-lint run之前执行，结果注释错误根本没机会暴露 - IDE 插件没勾选「Use config file」，或者路径填成
./.golangci.yml（相对路径无效），导致编辑器里不标红func MyApi() {}这种非法命名
真实项目里，API 规范最脆弱的环节不是写错 @Success，而是 handler 函数本身没按 Go 导出规则命名、参数顺序混乱、error 处理被 _ = xxx() 忽略——这些全靠 revive + errcheck + 显式配置才能守住底线。
