В поисках хорошего стиля. Часть 2. Пишем свой линтер на Go для golangci-lint

Привет! Меня зовут Артём Блохин, я Go-разработчик в команде интеграций Островка. Сегодня поговорим о линтинге кода.

Если бы «Сумерки» были про код, Эдвард — был линтером, а Белла — легаси-кодом, их диалог звучал бы так:

— Линтер смотрел на этот код с болью и отвращением.
— Какая глупая, забытая всеми кодовая база.
— Ну, а разработчик, который взялся её чинить, — просто мазохист.

Любой, кто пытался разобраться в старом коде без статики, знает: чем глубже копаешь, тем страшнее становится. В первой части мы говорили о том, как линтеры помогают поддерживать порядок в проекте. Теперь пора перейти к практике — написать собственный линтер и встроить его в golangci-lint, чтобы он сам выслеживал проблемные места.

Disclaimer

Линтер довольно объёмный (200+ строк кода), и если бы я попытался запихнуть всё в одну статью, это было бы жестоко — и для вас, и для моей клавиатуры. Поэтому в этой части мы разберёмся только с базовой логикой, остальное можно посмотреть в репозитории. 

Пристёгивайтесь, будет интересно!

Как родился ProperOrder, или «разорвать семейные узы»

Перед тем как писать линтер, я долго ломал голову: какой кейс взять? Он должен быть полезным, не слишком сложным и при этом не повторять уже существующие решения. В итоге выбор пал на наш новый линтер — ProperOrder.

Что делает ProperOrder?

Он проверяет, что код написан в осмысленном порядке:

• сначала объявляется структура;

• потом конструктор (если есть);

• затем методы этой структуры.

А теперь посмотрим на два варианта кода и выберем более читаемый. Это поможет понять, как порядок объявления влияет на восприятие и как ProperOrder помогает его соблюдать.

Пример 1 (неудачный):

type Man struct {...}  type Woman struct {...}  func (m Man) GetName() string {...}  func (w Woman) GetName() string {...}

Здесь метод GetName для Man разрывается объявлением структуры Woman. Когда код разрастается, подобные вещи снижают читаемость.

Пример 2 (удачный):

type Man struct {...}  func (m Man) GetName() string {...}  type Woman struct {...}  func (w Woman) GetName() string {...}

Теперь всё логично: объявили Man, затем сразу его метод.

Когда можно нарушать порядок?

Иногда структуры должны появляться не строго друг за другом, а в зависимости от их использования в функциях. Например:

type Man struct {...}  type Health struct {...}  func NewMan(h Health) Man {..}  type Woman struct {...}  func (m Man) FindLove(w []Woman) (Woman) {...}

В этом коде структура Health идёт до конструктора NewMan, хотя сам Man уже объявлен. Почему так? Потому что Health нужен в параметрах конструктора.

То же самое с FindLove: здесь массив []Woman передаётся в аргумент метода Man, а сам метод возвращает Woman. В таком случае линтер не будет ругаться, потому что порядок логичен: Типы, используемые в параметрах или возвращаемых значениях, могут объявляться раньше.

А существует ли читаемый шаблон для линтера?

Одна из основных сложностей, с которой я столкнулся в начале своего пути — это отсутствие чёткого образца или шаблона структуры линтеров, которому можно было бы следовать. Исследование чужих репозиториев в поисках оптимального варианта зачастую не давало результата.

Поразительно, но факт: даже линтеры, отличающиеся высокой скоростью и точностью анализа, нередко страдают от неудобной и запутанной архитектуры. Это становится настоящим барьером для тех, кто хочет глубже погрузиться в разбор механизмов их работы. Отсюда и возникло решение создать индивидуально адаптированный подход к структурированию линтеров, уделяя особое внимание прозрачности, логичности организации и user-friendly интерфейсу. Это позволит облегчить задачу для будущих пользователей и исследователей.

Как итог, я пришел к такому виду:

├── analyzers │   └── custom_linter │       ├── analyzer.go │       ├── analyzer_test.go │       └── testdata │           └── src │               └── src.go ├── cmd │   └── custom_linter │       └── main.go │── internal │   └── tests │       └── tests.go └── plugin     └── main.go

Рассмотрим директории подробнее:

analyzers/        — здесь живёт вся логика линтера   ├── analyzer.go        — основная логика анализа кода   ├── analyzer_test.go   — тесты для линтера   └── testdata/          — примеры кода, на которых тестируется линтер                              (то, что он должен пропускать и то,                                                что должен ругать) cmd/              — точка входа   └── main.go           — запускает линтер (если хотим прогнать его                                            отдельно от golangci-lint) internal/         — вспомогательные вещи для тестов и других внутренних задач   └── tests.go          — поддерживающие функции и сценарии plugin/           — загрузка линтера в golangci-lint   └── main.go

Запуск линтера

package main  import (   "golang.org/x/tools/go/analysis/singlechecker"   "gitlab.com/common/linter/analyzers/properorder" )  func main() {   singlechecker.Main(properorder.New()) }

singlechecker.Main(properorder.New()) создаёт интерфейс командной строки для линтера.

Если хочется поддерживать несколько линтеров, вместо singlechecker можно использовать multichecker.Main().

Линтер, или современный Прометей

Код рождается из идеи. Какая у нас идея? Порядок.
Главная проблема, связанная с ProperOrder, — как запомнить, что за чем следует?

Как мы можем быть уверены, что когда мы видим метод GetName для структуры Man, где-то выше уже объявлена эта структура? Или что перед конструктором NewPerson сначала идёт type Person struct {}?

Ответ прост: будем использовать стек. Но самое главное – стек нужно вычищать полностью, когда мы заходим в новый файл.

Стек — ключ к порядку

Когда линтер анализирует файл, он складывает все важные узлы в стек и проверяет, не нарушен ли порядок.

Что мы будем хранить в стеке?

• ast.FuncDecl — функции и методы (func Foo() или func (r *Receiver) Foo());

• ast.TypeSpec — объявления типов (type Man struct{}).

А теперь вернемся к примеру 1 и пройдёмся по коду сверху-вниз, попутно записывая в стек значения:

Что же мы видим? Красный элемент стека (метод Man) не соответствует нижележащему (тип Woman).

Как ProperOrder анализирует код?

Весь анализ выполняется в функции run(), которая вызывается для каждого файла. run() — это сердце линтера. Именно она отвечает за обработку AST, хранение контекста и вызов проверок.

Но перед тем, как перейдем к функции run(), нужно инициализировать наш линтер:

package properoder  import "golang.org/x/tools/go/analysis"  func New() *analysis.Analyzer {   return &analysis.Analyzer{     Name:     "properorder",     Doc:      "short documentation about linter",     Run:      run,     URL:      "https://documentation.com",     Requires: []*analysis.Analyzer{inspect.Analyzer},   } }

Узнаем, что скрывается под ним:

• Name – имя линтера.

• Doc – документация линтера (что делает, для чего и т.д.). Длинным быть не предполагается.

• Run – функция, в которой содержится логика линтера.

• URL – опциональное поле, которое содержит ссылку на полную документацию.

• Requires – некая оптимизация: golangci-lint запустит inspect.Analyzer только один раз для всех анализаторов (наших линтеров). То есть, мы не будем для каждого линтера заново строить AST-дерево.

Как работает run()?

func run(pass *analysis.Pass) (any, error) {   var lastFile *token.File   v := validator{     Pass: pass,     Stack: stack.New(),   }

pass *analysis.Pass — объект, содержащий всю информацию о коде (файлы, позиции узлов и т. д.).

validator — структура, которая отвечает за проверки в линтере. В ней есть:

• Pass — переданный объект analysis.Pass;

• Stack — стек узлов AST, где мы храним, какие структуры и функции уже встретились.

Какие узлы нас интересуют?

nodeTypes := []ast.Node{   (*ast.FuncDecl)(nil), // func Foo() or func (r *Receiver) Foo()   (*ast.TypeSpec)(nil), // type smt (e.g. struct, int, array etc) }

Здесь мы фильтруем AST и говорим, что нас интересуют только объявления типов и функций.

Как run() анализирует код?

При встрече нового узла мы вызываем enterNode(), которая решает, что с ним делать:

enterNode := func(n ast.Node) bool {   currentFile := pass.Fset.File(n.Pos())    if lastFile == nil || currentFile != lastFile {     v.flushStack() // Очистка стека при смене файла   }   lastFile = currentFile

Если мы зашли в новый файл — очищаем стек. Это важно, чтобы линтер не сравнивал элементы из разных файлов.

Как enterNode() обрабатывает узлы?

switch node := n.(type) { case *ast.TypeSpec:   v.CheckTypeSpecPosition(node) // Проверяем, где объявлен тип   v.Stack.Push(node)             // Добавляем его в стек  case *ast.FuncDecl:   v.TraverseStack(node)         // Проверяем порядок методов   v.Stack.Push(node)             // Добавляем метод в стек }

Если это структура (TypeSpec) – проверяем её порядок и кладём в стек.

Если это функция или метод (FuncDecl) – проверяем, стоит ли она на своём месте, затем добавляем в стек.

Как линтер проходит по AST?

inspect := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector) inspect.WithStack(nodeTypes, func(n ast.Node, push bool, stack []ast.Node) (proceed bool) {   if push {     return enterNode(n) // Анализируем узел   }   return true })

WithStack проходит по AST, анализирует только нужные узлы (TypeSpec, FuncDecl) и вызывает enterNode() для их обработки.

push bool означает:

• true – мы вошли в узел, анализируем его (enterNode(n));

• false – мы вышли из узла, просто продолжаем обход.

Proceed = true, мы спускаемся глубже в ast, = false, прекращаем обход узла.

В итоге получаем такой код:

func run(pass *analysis.Pass) (any, error) {   var lastFile *token.File   v := validator{     Pass: pass,     Stack: stack.New(),   }    nodeTypes := []ast.Node{     (*ast.FuncDecl)(nil), // func Foo() or func (r *Receiver) Foo()     (*ast.TypeSpec)(nil), // type smt (e.g. struct, int, array etc)   }   enterNode := func(n ast.Node) bool {     currentFile := pass.Fset.File(n.Pos())     if lastFile == nil || currentFile != lastFile {       v.flushStack()     }     lastFile = currentFile      switch node := n.(type) {     case *ast.TypeSpec:       v.CheckTypeSpecPosition(node)       v.Stack.Push(node)     case *ast.FuncDecl:       v.TraverseStack(node)       v.Stack.Push(node)     }     return false   }    inspect := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)   inspect.WithStack(nodeTypes, func(n ast.Node, push bool, stack []ast.Node) (proceed bool) {     if push {       return enterNode(n)     }     return true   })    return nil, nil }

На самом деле именно здесь и заканчивается вся сложность. Почему? Потому что дальше будут лишь проверки корректности. Приступим.

Раз мне не дано вселять любовь, я буду вызывать страх

Кажется, именно так можно описать две ключевые структуры в AST, с которыми работает наш линтер:

• ast.FuncDecl — узлы, представляющие функции и методы;

• ast.TypeSpec — узлы, представляющие объявления типов.

Разбираем ast.FuncDecl (функции и методы)

Рассмотрим метод:

func (m Man) MakeItGreatAgain(a int, b float64) (enemy int, err error) {..}

Структура FuncDecl из пакета go/ast выглядит так:

FuncDecl struct {   Doc  *CommentGroup // associated documentation; or nil   Recv *FieldList    // receiver (methods); or nil (functions)   Name *Ident        // function/method name   Type *FuncType     // function signature: type and value parameters, results, and position of "func" keyword   Body *BlockStmt    // function body; or nil for external (non-Go) function }

Визуализация:

На основе этой структуры делаем выводы:

• если Recv = nil, значит, это обычная функция;

• если Recv != nil, значит, это метод.

Разбираем ast.TypeSpec (объявления типов)

Допустим, у нас есть структура:

type Person[T any] = struct {    Name string   Age  int   }

Она в AST представлена как TypeSpec:

TypeSpec struct {   Doc        *CommentGroup  // associated documentation; or nil   Name       *Ident         // type name   TypeParams *FieldList     // type parameters; or nil   Assign     token.Pos      // position of '=', if any   Type       Expr           // *Ident, *ParenExpr, *SelectorExpr, *StarExpr, or any of the *XxxTypes   Comment    *CommentGroup  // line comments; or nil }

Визуализация:

Что важно для нас:

• поле Type указывает, к какому типу относится объявление — например, это может быть структура, интерфейс или другой тип;

• линтер может анализировать Name и Type, чтобы проверять порядок.

Путешествие на запад. Король порядка

Наш линтер научился разбирать код, находить объявления типов, функций и методов. Теперь пора разобраться, как он следит за порядком объявлений.

Как линтер следит за порядком объявления типов? (CheckTypeSpecPosition)

Представим ситуацию

func NewPerson(name string) Person {   return Person{Name: name} }  type Person struct {   Name string }

Ошибка! Конструктор объявлен раньше типа. Линтер должен это отловить и сообщить об ошибке.

Логика проверки

Посмотреть, что на вершине стека (Stack) находится функция. Убедиться, что это конструктор (NewPerson). Проверить, совпадает ли возвращаемый тип с объявленным Person. Если да — вывести ошибку.

Реализация в коде

func (v *validator) CheckTypeSpecPosition(typeSpec *ast.TypeSpec) {   if interfaceValue := v.Stack.Peek(); interfaceValue != nil {     if funcDecl, ok := interfaceValue.(*ast.FuncDecl); ok {       if isFunc(funcDecl) && isFuncHasResults(funcDecl) {         result := funcDecl.Type.Results.List[0]         if isTypeNamedAsExpected(           unstar(v.Pass.TypesInfo.TypeOf(result.Type)),            typeSpec.Name.Name,         ) {           v.reportInvalidOrder(result.Pos(), result.Pos(),             "the constructor must be positioned after the type is defined.")           _ = v.Stack.Pop() // Удаляем обработанный элемент из стека         }       }     }   } }

Как это работает?

• Stack.Peek() берёт последний добавленный элемент (конструктор);

• isFunc(funcDecl) проверяет, что это функция, а не метод;

• isFuncHasResults(funcDecl) проверяет, что функция что-то возвращает;

• isTypeNamedAsExpected() сравнивает имя возвращаемого типа с объявленным.

Если всё совпало, выводим ошибку и удаляем конструктор из стека, чтобы не проверять его дважды.

Тестируем через комментарии

Мы уже написали большую часть кода и готовы проверить, как работает наш линтер. Но как убедиться, что он действительно находит ошибки?

Так как мы пишем линтер, я решил, что удобнее всего сразу рядом с кодом указывать ожидаемые ошибки. Это даёт несколько преимуществ:

• мы сразу видим, где должна быть ошибка;

• можно проверять разные сценарии, просто добавляя новые файлы;

• тесты не требуют внешних зависимостей — всё хранится прямо в репозитории.

Настройка тестов

Тесты запускаются в файле: analyzers/properorder/analyzer_test.go

package properorder_test  import (   "testing"    "gitlab.com/common/linter/analyzers/properorder"   "gitlab.com/common/linter/internal/tests" )  func TestAll(t *testing.T) {   tests.AnalyzeCodeInTestdata(t, properorder.New()) }

• tests.AnalyzeCodeInTestdata(t, properorder.New()) запускает линтер на тестовых файлах;

• Если линтер не найдёт ошибку там, где должен, или выдаст ошибку не там — тест провалится.

Добавляем тест с ошибкой

Теперь создадим тестовый файл, который будет содержать ошибки. Файлы с тестами хранятся в analyzers/properorder/testdata/src.go

type Car struct {   Model string }  func (c Car) Drive() { // want "the method must be located below the constructor function."   println("Driving") }  func NewCar(model string) Car {   return Car{Model: model} }

• комментарий // want "..." указывает, что линтер ДОЛЖЕН здесь выдать ошибку;

• если линтер не выдаст ошибку, тест упадёт;

• если ошибка будет в другом месте, тест тоже упадёт.

Результаты запуска тестов

Если тест написан без тега // want

Линтер нашёл ошибку, но тест не знает, ожидали ли мы её, поэтому он провалится:

=== RUN   TestAll linter/analyzers/properorder/testdata/src/properorder.go:7:7  diagnostic the method must be located below the constructor function. --- FAIL: TestAll (0.02s)

Если тест написан с тегом // want

Линтер нашёл ошибку в нужном месте, тест успешно прошёл:

=== RUN   TestAll --- PASS: TestAll (0.02s) PASS

Встраивание ошибок в виде комментариев

Функция AnalyzeCodeInTestdata(t testing.T, analyzer analysis.Analyzer) запускает линтер на тестовых файлах в testdata/src и проверяет, правильно ли он находит ошибки.

Разбор кода

func AnalyzeCodeInTestdata(t *testing.T, analyzer *analysis.Analyzer) {   wd, err := os.Getwd()   if err != nil {     panic(err)   }    var printer errsPrinter   analysistest.Run(&printer, filepath.Join(wd, "testdata/src"), analyzer, "./...")   if printer.PrintedLines > 0 {     t.Fail()   } }

• os.Getwd() получает текущую директорию, где выполняется тест;

• analysistest.Run() запускает линтер на файлах в testdata/src;

• Если printer.PrintedLines > 0 (есть ошибки), тест проваливается (t.Fail()).

Как ошибки перехватываются?

Функция errsPrinter.Errorf() отвечает за перехват ошибок от линтера и их вывод в консоль.

type errsPrinter struct {   PrintedLines int }  func (p *errsPrinter) Errorf(format string, args ...interface{}) {   fmt.Println(args...) // Вывод ошибки в консоль   p.PrintedLines++     // Увеличиваем счётчик ошибок }

• если линтер нашёл ошибку, он вызывает Errorf();

• ошибка выводится в консоль (fmt.Println()).

Заключение

В этой части мы разобрали и реализовали основу линтера ProperOrder. Мы шаг за шагом прошли через ключевые аспекты, включая:

• создание структуры проекта для удобной организации кода линтера;

• разбор AST и использование стека для отслеживания порядка объявлений;

• проверку правильного расположения типов, конструкторов и методов.

Что дальше?

Хотя на данном этапе наш линтер уже работает, в следующей части статьи мы:

• добавим поддержку Golangci-lint без необходимости merge’а в общий репозиторий;

• разберём, как правильно интегрировать кастомный линтер в CI/CD.

Если вы хотите поэкспериментировать с кодом или доработать линтер под свои нужды — весь код можно найти на GitHub: ProperOrder.

Больше технических новостей из Островка в нашем Telegram-канале.