golangci-lint 默认不检查注释完整性,因其聚焦语义正确性等静态可推断问题,而注释规范属文档范畴,需通过 revive 等工具显式启用细粒度规则实现。

golangci-lint 本身不提供“代码注释完整度”检查 —— 它不校验函数是否写了 doc comment、参数是否都描述了、是否漏了 //go:generate 注释等。这类需求属于文档规范范畴,需靠 revive 或自定义规则实现,不是 staticcheck 或 govet 的职责。
为什么默认 linter 不检查注释完整性
golangci-lint 默认启用的 govet、staticcheck、errcheck 等,聚焦在语义正确性、资源泄漏、弃用 API、死代码等可静态推断的问题。Go 官方对注释没有语法强制(go doc 只解析格式,不验证覆盖率),所以主流 linter 也默认绕过。
常见误判场景包括:
- 把
func Foo() {}没写注释当成 bug —— 实际上 Go 并不要求每个导出函数必须有 doc comment,只有发布到pkg.go.dev时才建议 - 把
//nolint当成注释缺失 —— 它是 lint 抑制指令,不是文档注释 - 将内部未导出函数(
func foo())的注释缺失当作问题 —— 大多数团队不强制要求
用 revive 启用注释风格检查
revive 是当前唯一被广泛采用、支持细粒度注释规则的活跃 linter(golint 已归档且不维护)。它能检查导出标识符是否缺少 doc comment、comment 是否以大写字母开头、是否包含句号等。
在 .golangci.yml 中启用:
linters:
enable:
- revive
linters-settings:
revive:
rules:
- name: exported
severity: warning
arguments: [1] # 要求导出函数/类型必须有 doc comment
- name: comment-spelling
severity: info
- name: package-comments
severity: warning
注意:
-
revive必须显式加入linters.enable列表,它不在 golangci-lint 默认启用集里 -
exported规则只检查导出(首字母大写)的函数、方法、类型、常量,不会扫内部函数 - 若项目已有大量未注释导出项,可先设
severity: info避免 CI 爆红,再逐步收敛 -
revive的配置嵌套在linters-settings.revive.rules下,写错层级(如写成linters-settings.exported)会导致规则静默失效
CI 和 IDE 中让注释检查生效的关键点
即使配了 revive,本地和 CI 行为不一致仍很常见:
- GoLand:必须勾选
revive对应的 checkbox(Settings → Go → Static Analysis 表格中),或启用Use configuration并确认.golangci.yml路径正确——否则 IDE 只跑默认govet,根本看不到revive报告 - GitHub Actions:命令中必须显式传参
--config=.golangci.yml,否则golangci-lint run会跳过配置,revive不加载 - 版本兼容性:
revive v1.3+才完整支持 Go 1.21+ 泛型签名的 doc comment 解析;旧版可能跳过带泛型的函数检查 - 排除生成代码:
revive对pb.go、mock_*.go等文件报大量“缺少注释”是噪音,用exclude-rules过滤:
issues:
exclude-rules:
- path: ".*_test\.go$"
- path: ".*\.pb\.go$"
- path: "mocks/.*"
真正难的不是加一条 revive 规则,而是团队对“哪些注释算必要”达成共识 —— 比如是否要求每个 HTTP handler 都写 // @Summary,或者是否允许 // TODO 不带 issue 链接。这些得靠 revive 的自定义规则或 text-match 排除,而不是指望工具自动判断“完整度”。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











