golangci-lint如何配置自定义检查规则？

Question

如何在 golangci-lint 中配置自定义检查规则以支持团队特定的编码规范？例如，希望禁止使用 `print` 类函数或强制接口命名以 `er` 结尾，但 golangci-lint 默认不提供此类检查。虽然可通过启用内置 linter（如 `forbidigo`）实现部分功能，但复杂逻辑仍需自定义 linter。如何开发并集成一个 Go 语言的自定义 linter 插件，并通过配置文件将其纳入 golangci-lint 的检查流程中？是否需要编译为二进制插件？配置时应注意哪些路径、版本兼容性问题？

Answer 1

一、golangci-lint 自定义检查规则的配置与实现路径

在现代 Go 项目开发中，golangci-lint 已成为静态代码分析的事实标准工具。它集成了数十种 linter，并支持高度可配置化。然而，当团队需要实施特定编码规范（如禁止使用 print 类函数或强制接口命名以 er 结尾）时，内置 linter 往往无法完全满足需求。

1.1 常见场景与内置解决方案初探

• 禁止 print 函数调用：可通过启用 forbidigo linter 实现。
• 接口命名规范：golint 曾建议接口以 er 结尾，但已被废弃；目前无原生支持。
• 自定义逻辑检查：如“不允许包内循环依赖”、“必须使用 context.WithTimeout 而非 WithCancel”等复杂规则需定制开发。

示例：使用 forbidigo 禁止打印函数：

linters-settings:
  forbidigo:
    forbid:
      - '^(fmt\.Print(|f|ln)|print|println)$'

该配置能有效拦截常见的打印语句，适用于日志统一管理场景。但对于更复杂的语义分析（如类型断言深度检查、方法签名模式匹配），则必须引入自定义 linter。

1.2 自定义 Linter 的实现方式分类

方式	是否需编译为二进制	集成难度	适用场景
Go 编写的外部 linter（CLI）	是	中	通用性强，可复用
内嵌于 golangci-lint 的插件（Go plugin）	是（plugin 形式）	高	高性能、深层集成
利用 revive 配置扩展	否	低	轻量级规则，无需编码
编写 AST 分析器 + 外部脚本调用	可选	中	一次性检查，CI 集成

其中，最灵活且可持续维护的方式是开发一个符合 go-critic 或独立运行的 AST-based linter，并通过 golangci-lint 的 external linter 机制集成。

二、开发自定义 Linter 插件的技术路径

2.1 使用 go/ast 构建基础检查器

自定义 linter 的核心是对 Go 源码进行抽象语法树（AST）遍历。以下是一个强制接口命名以 er 结尾的简单实现框架：

package main

import (
    "go/ast"
    "go/parser"
    "go/token"
    "log"
    "strings"
)

func main() {
    fset := token.NewFileSet()
    node, err := parser.ParseFile(fset, "example.go", nil, parser.ParseComments)
    if err != nil {
        log.Fatal(err)
    }

    ast.Inspect(node, func(n ast.Node) bool {
        if typeSpec, ok := n.(*ast.TypeSpec); ok {
            if _, isInterface := typeSpec.Type.(*ast.InterfaceType); isInterface {
                if !strings.HasSuffix(typeSpec.Name.Name, "er") {
                    log.Printf("%s:%d: interface %s should end with 'er'",
                        fset.File(node.Pos()).Name(), fset.Line(node.Pos()),
                        typeSpec.Name.Name)
                }
            }
        }
        return true
    })
}

此程序可作为独立工具运行，输出不符合命名规范的接口。

2.2 将自定义 Linter 集成到 golangci-lint

从 v1.50+ 开始，golangci-lint 支持通过 externalLinters 字段注册外部 linter。配置如下：

linters:
  disable-all: true
  enable:
    - myinterfacer # 自定义启用名

linters-settings:
  external:
    myinterfacer:
      path: ./bin/myinterfacer-linter # 可执行文件路径
      description: "Checks that all interfaces end with 'er' suffix"
      original-url: github.com/team/linters/myinterfacer

注意：path 必须指向已编译的二进制文件，且具备可执行权限。构建命令示例：

GOOS=linux GOARCH=amd64 go build -o bin/myinterfacer-linter cmd/mylinter/main.go

三、架构设计与工程化考量

3.1 插件化部署流程图

graph TD A[编写 AST 分析逻辑] --> B[构建为可执行二进制] B --> C[放入项目 bin/ 目录或 CI PATH] C --> D[在 .golangci.yml 中注册 external linter] D --> E[golangci-lint run 触发检查] E --> F[输出违规信息至控制台或 SARIF] F --> G[CI/CD 流程阻断或告警]

该流程确保了自定义规则可在本地开发与持续集成环境中一致生效。

3.2 版本兼容性与路径管理注意事项

1. Go 版本一致性：编译 linter 所用 Go 版本应不低于目标项目的最低支持版本。
2. 操作系统差异：若在 macOS 编译而在 Linux CI 运行，需交叉编译对应平台二进制。
3. 路径问题：推荐将二进制置于项目根目录下的 tools/bin 并加入 .gitignore，避免污染仓库。
4. 模块依赖隔离：使用 go.mod 独立管理 linter 工具的依赖，防止与主项目冲突。
5. 缓存失效策略：golangci-lint 默认缓存结果，更新 linter 后需清除缓存（--no-cache）。
6. 退出码处理：自定义 linter 应在发现错误时返回非零状态码，否则 golangci-lint 视为成功。
7. 输出格式要求：建议遵循 filename:line:column: message 格式以便解析。
8. 性能影响评估：复杂 AST 遍历可能显著增加 lint 时间，建议对大型项目做增量检查优化。
9. 文档化规则语义：每个自定义 linter 应附带 README.md 说明其检查逻辑和例外情况。
10. 团队协作机制：通过 PR 模板或 CODEOWNERS 引导开发者理解并遵守新规则。

此外，还可结合 revive（golint 的继任者）实现部分规则而无需编码。例如，通过配置模板实现命名检查：

# revive.toml
[rule.interface-naming]
    arguments = [ "er" ]
    disabled = false

再在 golangci-lint 中启用：

linters:
  enable:
    - revive

这种方式适合快速落地常见规范，但灵活性低于手写 AST 分析器。