Golang 编写自定义的 Golang Linter 规则

大家好，我们又见面了啊~本文《Golang 编写自定义的 Golang Linter 规则》的内容中将会涉及到等等。如果你正在学习Golang相关知识，欢迎关注我，以后会给大家带来更多Golang相关文章，希望我们能一起进步！下面就开始本文的正式内容~

因为go vet和golangci-lint仅做语言层静态检查，不理解业务语义，如强制HTTP handler含context.Context或结构体字段禁用time.Time；需通过go/analysis编写自定义analyzer并集成到golangci-lint中。

为什么 go vet 和 golangci-lint 默认规则不够用

因为它们不理解你的业务语义。比如你要求所有 HTTP handler 函数必须带 context.Context 参数，或禁止在结构体字段里用 time.Time（强制用 *time.Time 避免零值问题），这类约束不会出现在标准 linter 的检查列表里。go vet 只做语言层安全检查，golangci-lint 是工具聚合，本身不生产规则逻辑——它靠插件（即自定义 analyzer）扩展。

用 go/analysis 编写 analyzer 的最小可行结构

核心是实现 analysis.Analyzer 类型，它包含名字、文档、运行时依赖和最关键的 Run 函数。不要从头写 AST 遍历器：直接用 inspect.WithStack 或 pass.Report 配合 pass.ResultOf[...] 获取类型信息更稳。

• Analyzer.Name 必须小写、无下划线（如 ctxparam），否则 golangci-lint 加载失败
• Run 函数接收 *analysis.Pass，它封装了 AST、类型信息、文件路径等；别手动解析 .go 文件内容，用 pass.Files 和 pass.TypesInfo
• 报错必须调用 pass.Reportf(node, "message")，其中 node 要属于当前包的 AST 节点（比如 *ast.FuncDecl），否则位置信息错乱

示例：检查函数参数是否含 context.Context

func run(pass *analysis.Pass) (interface{}, error) {
    for _, file := range pass.Files {
        ast.Inspect(file, func(n ast.Node) bool {
            funcDecl, ok := n.(*ast.FuncDecl)
            if !ok || funcDecl.Type.Params == nil {
                return true
            }
            for _, field := range funcDecl.Type.Params.List {
                for _, name := range field.Names {
                    if ident, ok := field.Type.(*ast.Ident); ok && ident.Name == "Context" {
                        if pkg, ok := pass.Pkg.Path(); ok && strings.HasSuffix(pkg, "/context") {
                            pass.Reportf(field.Pos(), "function %s should accept context.Context", funcDecl.Name.Name)
                        }
                    }
                }
            }
            return true
        })
    }
    return nil, nil
}

集成到 golangci-lint 的三步验证法

光编译出 analyzer 不代表能用。golangci-lint 对插件有隐式契约：导出变量名必须是 Analyzers，类型为 []*analysis.Analyzer，且每个 analyzer 的 Doc 字段不能为空字符串。

• 在 analyzer 包根目录放 main.go，导出 var Analyzers = []*analysis.Analyzer{myAnalyzer}
• 运行 go build -buildmode=plugin -o ctxparam.so . 生成插件（注意：Go 1.22+ 默认禁用 plugin，需加 GO111MODULE=off go build -buildmode=plugin 或改用静态链接方式）
• 在 .golangci.yml 中启用：

  linters-settings:
    gocritic:
      enabled-checks: ["ctxparam"]
  linters:
    enable:
      - ctxparam

  但实际要写成 enable: ["ctxparam"] 并确保 ctxparam 在 linters-settings.golangci-lint.plugins 里声明路径

常见失败现象：can't find analyzer "ctxparam" —— 90% 是 Analyzers 变量没导出，或 plugin 编译时未指定 -buildmode=plugin，或 golangci-lint 版本低于 v1.52（旧版不支持插件机制）。

AST 匹配容易忽略的边界条件

直接遍历 *ast.FuncDecl 会漏掉方法接收者里的 context.Context 检查，也抓不到嵌套函数。更可靠的是用 pass.ResultOf[inspect.Analyzer] 获取 *inspect.Inspector，再用 Nodes() 精确匹配节点类型。

• 函数参数可能是 *ast.StarExpr（指针类型）、*ast.SelectorExpr（如 ctx context.Context 中的 context.Context），不能只比对 *ast.Ident.Name
• 要区分 context.Context 和用户自定义的同名类型，得结合 pass.TypesInfo.TypeOf(node) 查类型对象的完整路径
• 测试 analyzer 时，务必用 analysis/testutil 写 run 测试，而不是手动跑命令——它能模拟真实构建上下文，避免因类型信息缺失导致误报

真正卡住人的从来不是写规则，而是搞清「这个 AST 节点对应的类型信息在哪」「报错位置能不能准确定位到参数名而非整行」。多打几行 fmt.Printf("%#v", node) 看结构，比查文档快。

今天关于《Golang 编写自定义的 Golang Linter 规则》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！