golangci-lint вглубь: линтеры Go как инструмент, а не галочка

golangci-lint на стенде с размеченными дефектами: что находит набор по умолчанию и что пропускает, что добавляет курируемый конфиг и сколько шума даёт «включить всё», что молча прячут обрезка вывода и пресеты исключений, что делает голый //nolint, что видит new-from-rev в изменённом старом коде и как своё правило на go/analysis встраивается в линтер плагином. Плюс тренажёр из четырёх уровней. Всё — счётом находок

Обычная история линтера в Go-проекте: поставили golangci-lint, запустили с настройками по умолчанию, CI позеленел — галочка стоит. Что за этой галочкой, обычно не проверяют: какие классы ошибок она вообще умеет видеть, сколько находок выводит, а сколько молча отбрасывает, что прячут исключения, которые кто-то когда-то включил «чтобы не шумело».

Здесь на эти вопросы отвечает стенд, и отвечает счётом. В Go-модуль подсажены дефекты, каждый помечен на своей строке, и у каждого есть исправленная пара. Находка засчитывается, только если совпали файл, строка и линтер. Так видно не «линтер что-то нашёл», а что именно он нашёл, что пропустил и что выдал сверх задуманного.

Ретрофутуристский инженерный лист: линия контроля качества. По одной ленте конвейера идут одинаковые шестерни и кронштейны под рядом из десяти инспекционных ламп; горят только три, первая, четвёртая и седьмая, и их оранжевые конусы света падают на ленту. Внизу пульт «конфиг» с десятью тумблерами, по одному под каждой лампой: подняты три, под горящими лампами, остальные опущены. На ленте два кронштейна с трещиной: тот, что под горящей лампой, отмечен оранжевым ярлыком; второй, под тёмной лампой, без ярлыка и подсветки уходит к выходу

В статье

Стенд: разметка вместо впечатлений

golangci-lint — не линтер, а запускатель линтеров: он один раз загружает пакеты и проверяет типы, а затем прогоняет на этом общем результате десятки анализаторов параллельно и кеширует итог (устройство). В версии 2.14, на которой построен стенд, линтеров 112, форматтеров 6. Скорость стенд не меряет — только что найдено.

Всё запускается в образе golangci/golangci-lint:v2.14.0, закреплённом по дайджесту, — на хост ставить ничего не нужно. Код с дефектами лежит в sample/ по пакетам: ошибки, HTTP-клиент, база, безопасность, go vet, мёртвый код, лишние аллокации. Разметка двух видов. // want <линтер> — ожидаемая диагностика: на этой строке этот линтер обязан сработать. На одной строке их может быть две, если один дефект видят два линтера, поэтому стенд считает отдельно диагностики (пары «место + линтер») и места. // noise <линтер> — находка на коде, исправном по смыслу при допущениях стенда: непроверенный Close после чтения, путь к файлу от доверенного вызывающего. Шум не ошибка линтера — это место, где его правило шире, чем нужно проекту, и где конфиг должен его погасить, по возможности узко.

Ещё одна деталь постановки, без которой счёт врёт: все прогоны идут с --max-same-issues 0 --max-issues-per-linter 0 --uniq-by-line=false. Почему — в разделе про вывод.

Что находит набор по умолчанию

Постановка. Три конфигурации на одном sample/: набор по умолчанию (--no-config, в v2 это standard — errcheck, govet, ineffassign, staticcheck, unused); курируемый конфиг стенда; --default all — включено всё. 20 ожидаемых диагностик на 18 местах. Места трёх классов, и класс задан меткой в разметке, а не выведен из линтера. 15 — ошибки относительно контракта, записанного в комментарии функции: «Merge возвращает срез, не делящий память с a», «Normalize обрезает пробелы». Без такого контракта append в другой срез может быть вполне корректным — go-critic сам называет его подозрительным, а не ошибочным. 1 — мёртвый код: неиспользуемая функция ничего не ломает. 2 — предложения оптимизации (prealloc, perfsprint): медленнее не значит неверно, и стенд не доказывает, что эти места — проблема производительности. Контроль — исправленные пары fixed/ под курируемым конфигом.

линтер что размечено по умолчанию курируемый «всё»
errcheck непроверенная ошибка os.Remove 1 из 1 1 из 1 1 из 1
errorlint сравнение ошибок через ==, обёртка через %v 0 из 2 2 из 2 2 из 2
bodyclose незакрытое тело ответа 0 из 1 1 из 1 1 из 1
noctx http.Get без контекста 0 из 1 1 из 1 1 из 1
rowserrcheck не проверен rows.Err() 0 из 1 1 из 1 1 из 1
sqlclosecheck не закрыт rows при раннем выходе 0 из 1 1 из 1 1 из 1
gosec секрет в коде, math/rand для токена 0 из 2 2 из 2 2 из 2
govet неверный глагол формата; затенённая ошибка; разыменование nil 1 из 3 3 из 3 1 из 3
staticcheck сравнение выражения с собой; дубли находок ineffassign и govet 3 из 3 3 из 3 3 из 3
ineffassign обрезанная строка тут же перезаписана 1 из 1 1 из 1 1 из 1
unused функция, которую никто не вызывает 1 из 1 1 из 1 1 из 1
prealloc срез растёт в цикле при известной длине 0 из 1 1 из 1 1 из 1
perfsprint fmt.Sprintf("%d", n) 0 из 1 1 из 1 1 из 1
gocritic результат append в другой срез: общий массив с входом 0 из 1 1 из 1 1 из 1
ожидаемых диагностик пары место + линтер 7 из 20 20 из 20 18 из 20
мест найдено хоть одним ожидаемым линтером 5 из 18 18 из 18 16 из 18
из них ошибки против контракта в комментарии функции 4 из 15 15 из 15 13 из 15
из них мёртвый код unused 1 из 1 1 из 1 1 из 1
из них оптимизация prealloc, perfsprint 0 из 2 2 из 2 2 из 2
шум исправный по смыслу код 2 0 5
вне разметки 0 0 66

Контроль сошёлся: на исправленных парах курируемый конфиг не находит ничего.

$ python3 scripts/run-default.py standard
{"variant": "standard", "outcome": "scored", "detail": "диагностик 7 из 20, мест 5 из 18, шум 2, вне разметки 0"}
$ python3 scripts/run-default.py curated
{"variant": "curated", "outcome": "scored", "detail": "диагностик 20 из 20, мест 18 из 18, шум 0, вне разметки 0"}
$ python3 scripts/run-default.py all
{"variant": "all", "outcome": "scored", "detail": "диагностик 18 из 20, мест 16 из 18, шум 5, вне разметки 66"}

Набор по умолчанию выдаёт 7 из 20 ожидаемых диагностик, но приходятся они на 5 мест из 18, и одно из них — мёртвый код: staticcheck дважды повторяет то, что уже нашли ineffassign и govet. Незакрытое тело ответа, непроверенный rows.Err(), незакрытый rows, секрет в коде, math/rand для токена, сравнение ошибок через == — всё это проходит мимо: ни один из пяти линтеров по умолчанию об этом не знает. Отдельный случай — govet: он включён, но два из трёх его мест пропущены. Затенённая ошибка и разыменование заведомо нулевого указателя — это анализаторы shadow и nilness, а внутри govet они выключены, пока их не назвать в настройках.

Курируемый конфиг находит все 18 мест и не шумит. Он не длинный — стандартные пять плюс девять линтеров, каждый из которых ловит класс реальных дефектов. Шум погашен узко: настройкой линтера там, где правило шире нужного по типу, и правилом на конкретный файл там, где всё держится на допущении о входе.

# configs/curated.yml
version: "2"
run:
  relative-path-mode: gomod
linters:
  default: standard
  enable:
    - bodyclose
    - errorlint
    - gocritic
    - gosec
    - noctx
    - perfsprint
    - prealloc
    - rowserrcheck
    - sqlclosecheck
  settings:
    govet:
      enable:
        - nilness
        - shadow
    errcheck:
      exclude-functions: # rows только читаются; ошибка закрытия после чтения ничего не меняет
        - (*database/sql.Rows).Close
    gosec:
      excludes:
        - G104 # непроверенная ошибка — это уже ловит errcheck
  exclusions:
    presets: []
    rules:
      # Допущение стенда: URL и путь здесь задаёт вызывающий код из доверенной
      # конфигурации, а не запрос. Правило — на файл, а не на весь проект.
      - path: (sample|fixed)/httpx/httpx\.go
        linters: [gosec]
        text: G107
      - path: (sample|fixed)/errs/errs\.go
        linters: [gosec]
        text: G304
      # Тело ответа HTTP-клиента: после чтения ошибка закрытия не меняет результат.
      - linters: [errcheck]
        text: "`resp\\.Body\\.Close`"

Две строки в нём из-за особенностей v2. version: "2" обязателен — формат конфига v1 v2 не читает, и golangci-lint migrate переводит старый файл. А run.relative-path-mode по умолчанию в v2 — cfg: пути в выводе считаются от каталога конфига, и с конфигом в подкаталоге находки приходят как ../sample/.... Правила исключений по пути тоже считаются от него. Проверить конфиг на соответствие схеме — golangci-lint config verify; все конфиги стенда её проходят.

Прежде этот конфиг гасил шум шире: G107 и G304 отключались на весь проект, а errcheck не проверял ни один Close через (io.Closer).Close — «на чтении», хотя интерфейс не различает чтение и запись. Чем это оборачивается, показывает ось исключений ниже.

«Включить всё» выглядит надёжнее, но находит меньше курируемого — 16 мест из 18: анализаторы shadow и nilness не включаются и так. А сверх разметки даёт 66 находок, и почти все — про оформление:

линтер находок вне разметки
wsl 20
wsl_v5 16
nlreturn 12
wrapcheck 9
err113 2
noinlineerr 2
revive 2
forbidigo 1
varnamelen 1
wastedassign 1

wsl в 2.14 помечен устаревшим, wsl_v5 — его замена, и --default all включает оба: одно правило о пустых строках считается дважды. Шум такого объёма приучает читать отчёт по диагонали, и настоящая находка в нём тонет. Набор, где каждый линтер включён ради известного класса дефектов, читается целиком.

Ещё одно наблюдение из таблицы: один дефект часто дают два линтера. staticcheck дублирует ineffassign на перезаписанном присваивании и govet на неверном глаголе формата, gosec G104 повторяет errcheck. На этом держится настройка по умолчанию, о которой дальше.

Зелёный линтер — ещё не исправная программа

Разметка стенда — утверждение «здесь дефект». Линтер его не доказывает: он проверяет, выполнено ли правило. Прежний пример стенда для sqlclosecheck это и показал. Функция дочитывала выборку до конца и не закрывала rows; sqlclosecheck честно сработал, а утечки не было: полный проход rows.Next() закрывает rows сам (database/sql). Поэтому смысл разметки стенд проверяет отдельно, тестом поведения: фиктивный драйвер database/sql с одним соединением и db.Stats().InUse после вызова.

случай занятых соединений после вызова
полный проход rows.Next() без Close (контроль) 0
sample/db.First: ранний выход без Close 1
fixed/db.First: defer rows.Close() 0
$ python3 scripts/run-semantics.py TestDrainedRowsReleaseConnection
{"variant": "TestDrainedRowsReleaseConnection", "outcome": "confirmed", "detail": "in_use=0"}
$ python3 scripts/run-semantics.py TestSampleFirstHoldsConnection
{"variant": "TestSampleFirstHoldsConnection", "outcome": "confirmed", "detail": "in_use=1"}
$ python3 scripts/run-semantics.py TestFixedFirstReleasesConnection
{"variant": "TestFixedFirstReleasesConnection", "outcome": "confirmed", "detail": "in_use=0"}

Утечка — в раннем выходе: функция взяла первую строку и вернулась, rows остался открытым, соединение занято. Сейчас пример стенда — именно такой. Для линтера оба варианта одинаковы: Close не вызван. Находка sqlclosecheck полезна и во втором случае — defer rows.Close() защищает от раннего выхода, который добавят позже, — но называть её утечкой можно, только проверив поведение.

Тем же способом проверены контракты из комментариев — и исправления. Ошибки Merge и Normalize тест показывает на исходном коде и не находит на исправленной паре. А исправление prealloc контракт ломает, если делать его механически: make([]string, 0, len(n)) на пустом входе возвращает пустой срез вместо nil, и в JSON вместо null уходит [] (encoding/json). Исправленная пара стенда поэтому сохраняет nil на пустом входе.

контракт из комментария исходный код исправленная пара наивное исправление
Merge: результат не делит память с a нет да —
Normalize: пробелы обрезаны нет да —
IDs: на пустом входе nil (null в JSON) да да нет

Проверки требует и обоснование подавления. Прежний уровень L3 тренажёра подавлял ошибку json.NewEncoder(w).Encode(v) с причиной «клиент ушёл». Но Encode падает и до записи — неподдерживаемый тип, NaN, ошибка MarshalJSON: тест с chan int получил ошибку при пустом теле ответа, и после неё статус 500 ещё выставляется. Директива прятала бы настоящую ошибку сериализации. Теперь L3 подавляет ошибку Write готового тела после WriteHeader, и причина в директиве — не «это только обрыв соединения»: у ResponseWriter есть и ErrContentLength, и ErrHandlerTimeout (net/http). Честная причина — статус уже выбран, и ошибку выдачи готового тела здесь намеренно не обрабатывают.

Что прячет вывод

У вывода golangci-lint три ограничения по умолчанию: не больше трёх находок с одинаковым текстом, не больше 50 находок одного линтера и одна находка на строку. Первые два спасают отчёт от тысячи одинаковых строк, третье — от дублей вроде пары staticcheck и ineffassign. Но они не различают, что прячут.

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

пакет найдено показано по умолчанию что обрезало
5 одинаковых находок errcheck 5 3 --max-same-issues (3)
60 вызовов разных локальных функций, errcheck 60 3 --max-same-issues (3)
60 неиспользуемых функций, unused 60 50 --max-issues-per-linter (50)
errcheck и noctx на одной строке 2 1 --uniq-by-line

Контроль сошёлся: без ограничений показано всё найденное.

$ python3 scripts/run-truncate.py local default
{"variant": "local/default", "outcome": "truncated", "detail": "показано 3 из 60 найденных, код выхода 1"}
$ python3 scripts/run-truncate.py many default
{"variant": "many/default", "outcome": "truncated", "detail": "показано 50 из 60 найденных, код выхода 1"}

Самая неочевидная строка — вторая. У errcheck текст находки для вызова локальной функции не содержит её имени: «Error return value is not checked». Шестьдесят разных мест в коде для --max-same-issues — одна и та же находка, и в отчёт попадают три. Код выхода при этом 1, CI падает — но человек, который откроет отчёт, увидит три замечания и починит три. На пробе стенда так же пропал noctx на http.Get: на той же строке gosec выдал G107, и uniq-by-line оставил одну находку из двух.

Для локальной работы ограничения удобны. Для CI и для любого подсчёта — 0, 0 и --uniq-by-line=false, иначе «замечаний стало меньше» может значить «стало меньше видно».

Конфиг v2: исключения и пресеты

В v2 всё, что убирает находки, собрано в linters.exclusions: пресеты (именованные наборы правил), правила по пути и тексту, режим для сгенерированного кода. Пресеты удобны тем, что их не надо писать, и опасны тем же — что именно они прячут, из конфига не видно.

Постановка. Конфиг без исключений (контроль: находит всё размеченное, и дефекты, и шум) на sample/ и excl/. В excl/ — дефект в тесте, два сгенерированных файла (со стандартным заголовком Code generated … DO NOT EDIT. и с нестандартным) и excl/danger: те же правила, что дают шум в sample/, но на настоящих дефектах — URL и путь к файлу из запроса, Close после записи. Каждый вариант добавляет одно исключение; два последних — курируемый конфиг целиком, с прежними широкими исключениями и с узкими.

исключение спрятано дефектов спрятано шума
пресет comments 0 0
пресет std-error-handling 5 3
пресет common-false-positives 0 1
пресет legacy 0 4
правило по пути _test.go для errcheck 1 0
generated: lax (по умолчанию) 2 2
generated: strict 1 1
курируемый, широкие исключения (G107/G304 на проект, (io.Closer).Close) 1 9
курируемый, узкие исключения (правила на файл, resp.Body.Close по тексту) 0 9

Контроль сошёлся: без исключений найдены все 28 ожидаемых диагностик и 9 находок шума.

Пресет std-error-handling задуман против непроверенных Close, Flush и печати — и это он делает: все три находки шума про Close пропадают. Но вместе с ними пропадают пять настоящих дефектов: четыре непроверенных os.Remove — удаление файла, о провале которого никто не узнает, — и Close после записи в excl/danger. При записи ошибка сброса данных часто приходит именно из Close; вызывающий получит nil, а данных не будет. Курируемый конфиг стенда поэтому обходится без пресета.

Тот же вопрос — к собственным исключениям. Прежний курируемый конфиг прятал Close через (io.Closer).Close, и Close после записи пропал так же, как от пресета. Узкий конфиг гасит только resp.Body.Close правилом по тексту и не прячет ни одного дефекта при том же погашенном шуме. G107 и G304 он отключает не на весь проект, а на два файла, где URL и путь приходят от вызывающего кода, — и это допущение записано рядом с правилом.

Одно наблюдение не совпало с ожиданием. Глобальное отключение G107 и G304 не спрятало URL и путь из запроса: на них в gosec этой версии срабатывают другие правила, G704 (SSRF) и G703 (обход каталога), основанные на отслеживании данных из запроса, а заодно G705 — запись непроверенных данных в ответ. G107 и G304 остаются эвристиками «переменная вместо константы» и срабатывают там, где источник данных не виден. Узкие правила от этого не теряют смысла: там, где отслеживание источник не видит, остаётся только эвристика, и глобальное отключение спрячет её находку молча. Стенд такой случай не ставил — это граница опыта, а не результат.

common-false-positives убрал только gosec G304 в sample/ — путь к файлу из переменной. legacy — gosec G104 на всех четырёх строках с os.Remove; дефекты errcheck на тех же строках остались, но гипотеза стенда («legacy здесь ничего не спрячет») не подтвердилась — пресет шире, чем выглядит. comments относится к линтерам комментариев, которых в этом конфиге нет, и не убрал ничего.

Сгенерированный код golangci-lint по умолчанию не проверяет (generated: lax), и lax узнаёт его не только по стандартному заголовку: файл с подписью «This file was automatically generated. Do not edit by hand.» пропущен тоже. strict пропускает только стандартный заголовок. Если в проекте есть рукописный файл с похожей подписью — например, оставшейся от генератора, которым давно не пользуются, — при lax его ошибки не увидит никто.

//nolint и nolintlint

Подавление в строке — нормальная часть работы с линтером: бывает, что правило право в общем и неправо здесь. Вопрос в том, что подавляет директива и кто следит за самими директивами.

Постановка. Шесть форм директивы в nolint/cases/cases.go, у каждой своя строка с размеченным дефектом. Прогоны: errcheck и noctx без проверки директив; то же с nolintlint (require-specific, require-explanation, allow-unused: false); контроль — та же копия кода без директив.

// nolint/cases/cases.go
// TwoBare — две находки на строке, голая директива прячет обе.
func TwoBare() {
	// case two-bare
	// want-next errcheck noctx
	exec.Command("true").Run() //nolint
}
директива показано подавлено nolintlint
//nolint — errcheck без имени линтера, без причины
//nolint:errcheck — errcheck без причины
//nolint:errcheck // причина — errcheck —
//nolint:noctx // причина errcheck — не используется
//nolint, на строке errcheck и noctx — errcheck, noctx без имени линтера, без причины
//nolint:errcheck // причина, на строке errcheck и noctx noctx errcheck —

Контроль сошёлся: без директив найден каждый размеченный дефект.

$ python3 scripts/run-nolint.py strict two-bare
{"variant": "strict/two-bare", "outcome": "scored", "detail": "показано —, подавлено ['errcheck', 'noctx'], nolintlint: ['без имени линтера', 'без причины']"}

Подавление одинаково с nolintlint и без него: nolintlint ничего не включает обратно, он только отмечает плохие директивы. Директива с чужим линтером не подавляет ничего — и nolintlint говорит, что она не используется. Голый //nolint прячет все находки строки. Автор директивы думал о непроверенной ошибке, а заодно спрятал вызов без контекста, о котором не знал; nolintlint отметит форму директивы — нет имени линтера, нет причины, — но о втором дефекте не скажет ничего. Узкая директива на той же строке оставляет noctx на виду.

Отсюда правило: только //nolint:<линтер> // причина и nolintlint с require-specific в конфиге. Причина в директиве — это то, что прочитает следующий человек, когда захочет её убрать.

Легаси: new-from-rev

Включить строгий набор на живом проекте — значит получить сотни старых замечаний, которые никто не будет чинить разом. Для этого есть --new-from-rev, --new-from-merge-base и --new-from-patch: показывать только находки в изменённых строках.

Постановка. Скрипт legacy/build-repo.sh собирает git-репозиторий: в main старый код — три непроверенные ошибки в двух файлах. Ветка feature меняет строку одного старого дефекта (другое имя файла, ошибка всё так же не проверена) и добавляет функцию с новым дефектом; второй файл не тронут. Автор и даты коммитов фиксированы. Контроль — полный прогон видит все четыре.

прогон новая старая, строка изменена старая, тот же файл старая, другой файл
полный прогон да да да да
--new-from-rev=HEAD~1 да да — —
--new-from-merge-base=main да да — —
--new-from-rev=HEAD~1 --whole-files да да да —
$ python3 scripts/run-legacy.py new-from-rev
{"variant": "new-from-rev", "outcome": "scored", "detail": "показано 2 из 4: legacy/a.go:8, legacy/a.go:14"}
$ python3 scripts/run-legacy.py whole-files
{"variant": "whole-files", "outcome": "scored", "detail": "показано 3 из 4: legacy/a.go:8, legacy/a.go:9, legacy/a.go:14"}

Правка строки «усыновляет» её старую находку: строка изменена, значит, для new-from-rev она новая, и непроверенная ошибка, жившая там годами, становится проблемой автора правки. Это скорее достоинство — трогаешь строку, приводишь её в порядок, — но его стоит знать заранее, иначе переименование файла в вызове внезапно ломает CI. Соседняя старая строка в том же файле не показана. --whole-files показывает все находки в изменённых файлах — режим для постепенной чистки «трогаешь файл — чинишь файл».

В CI --new-from-merge-base с основной веткой надёжнее, чем HEAD~1: ветка с несколькими коммитами при HEAD~1 покажет только последний.

Своё правило на go/analysis

Готовые линтеры не знают правил конкретного проекта. В статье про gRPC опыт с deadline показал, как звено, создавшее context.Background() вместо того, чтобы передать полученный контекст, доделывает работу, о которой уже никто не спросит. Такую ошибку легко описать правилом: внутри функции, у которой уже есть параметр context.Context, не создавать новый корневой контекст.

Правило ctxloss написано на go/analysis. Главное в нём — функция run:

// analyzer/ctxloss/ctxloss.go
func run(pass *analysis.Pass) (any, error) {
	ins := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)
	// Обход по вызовам со стеком: вызов считается, если хоть одна объемлющая
	// функция — объявление или литерал — получила context.Context. Так видны и
	// замыкания внутри функции с ctx, и литерал со своим ctx внутри функции без него.
	ins.WithStack([]ast.Node{(*ast.CallExpr)(nil)}, func(n ast.Node, push bool, stack []ast.Node) bool {
		if !push {
			return true
		}
		name := rootContext(pass, n.(*ast.CallExpr))
		if name == "" || !insideContextFunc(pass, stack) {
			return true
		}
		pass.Reportf(n.Pos(), "context.%s() в функции с параметром context.Context: "+
			"срок и отмена вызывающего теряются; передайте ctx, а если работа намеренно фоновая — "+
			"context.WithoutCancel(ctx) со своим сроком", name)
		return true
	})
	return nil, nil
}

// insideContextFunc — есть ли в стеке функция с параметром context.Context.
func insideContextFunc(pass *analysis.Pass, stack []ast.Node) bool {
	for _, s := range stack {
		var ft *ast.FuncType
		switch f := s.(type) {
		case *ast.FuncDecl:
			ft = f.Type
		case *ast.FuncLit:
			ft = f.Type
		}
		if ft != nil && hasContextParam(pass, ft) {
			return true
		}
	}
	return false
}

Правило идёт по вызовам и смотрит на стек объемлющих узлов: вызов context.Background() или TODO() считается, если хоть одна объемлющая функция — объявление или литерал — получила context.Context. Так видны и замыкание внутри функции с ctx, и литерал со своим ctx внутри функции без него.

Контекст правило узнаёт по типу, а не по имени: интерфейс с методом Done из своего пакета — не context.Context. У типа есть и вторая тонкость. Параметр ctx Ctx, где type Ctx = context.Context, в go/types имеет тип *types.Alias, а не *types.Named, и проверка «именованный тип context.Context» на нём промолчит, пока алиас не снят types.Unalias (go/types). Оба случая — алиас и литерал со своим ctx — положительные в analysistest; рядом отрицательные: переданный ctx, context.WithoutCancel(ctx), функция без параметра-контекста, main.

Граница правила — место создания. Оно сообщает о context.Background(), только если вызов стоит внутри функции с параметром-контекстом. Корневой контекст, созданный там, где такого параметра нет, — в переменной пакета, в конструкторе, — и потом использованный в обработчике с ctx, правило не увидит: путь данных между функциями оно не отслеживает. context.WithoutCancel оно пропускает намеренно, но не потому, что тот сохраняет срок: он тоже убирает и срок, и отмену вызывающего, оставляя только значения контекста (контракт). Исключение оправдано другим — это явное, видимое в коде решение отделить фоновую работу, например запись журнала после ответа. Такой работе обычно задают собственный срок: context.WithTimeout(context.WithoutCancel(ctx), …).

В golangci-lint правило встраивается как module plugin: пакет регистрирует анализатор, а golangci-lint custom собирает свой бинарь линтера с этим пакетом внутри.

// analyzer/plugin/plugin.go
func init() {
	register.Plugin("ctxloss", New)
}
# .custom-gcl.yml
version: v2.14.0
name: golangci-lint-ctx
destination: ./bin
plugins:
  - module: tech.khorost/golangci/analyzer
    import: tech.khorost/golangci/analyzer/plugin
    path: ./analyzer

В конфиге свой бинарь знает ctxloss как обычный линтер:

# configs/custom.yml
linters:
  default: none
  enable: [ctxloss, contextcheck, noctx]
  settings:
    custom:
      ctxloss:
        type: module
        description: context.Background()/TODO() в функции с параметром context.Context

Постановка. Пакет ctx/handler: пять функций теряют срок вызывающего по ошибке — через корневой контекст. Остальные — нет: передают ctx, вовсе не получают контекста или отрывают фоновую работу намеренно через context.WithoutCancel (срок она при этом тоже теряет, но это решение, а не ошибка). Свой бинарь с ctxloss, contextcheck и noctx; обычный — только готовые. Счёт по функциям, а не по строкам: contextcheck ставит находку туда, где контекст использован, а не где создан.

линтер поймано функций из 5 пропущено лишних срабатываний
ctxloss 5 — 0
contextcheck 3 Enqueue, Poll 0
noctx 0 Audit, Enqueue, Get, GetTimeout, Poll 0

Контроль сошёлся: analysistest прошёл, лишних срабатываний ни у одного линтера нет, а обычный бинарь с этим конфигом не запускается вовсе:

$ python3 scripts/run-custom.py plain-binary
{"variant": "plain-binary", "outcome": "scored", "detail": "обычный бинарь отказался: plugin \"ctxloss\" not found (код 3)"}

Гипотеза стенда была, что contextcheck про другое. Оказалось, он ловит три случая из пяти — те, где новый корневой контекст передан дальше в вызов. Не видит он два: ожидание <-bg.Done() на корневом контексте и корневой контекст, сохранённый в структуре задачи для запуска позже. Если в проекте этих случаев нет, своё правило не нужно — хватит готового. Свой линтер имеет смысл писать, когда готовые проверены на своём коде и что-то пропускают, а не раньше. И цена у него есть: свой бинарь надо собирать и обновлять вместе с версией golangci-lint.

CI и локально

Всё, что выше, держится на закреплённой версии. Набор линтеров по умолчанию, тексты находок, пресеты, эвристики (gosec G101 на тренажёре сработал на одно значение секрета и не сработал на другое при том же имени константы) меняются от версии к версии. Если локально стоит одна версия, а в CI берётся latest, зелёный прогон у разработчика ничего не говорит о CI.

  • Версия — одна на всех: образ по тегу и дайджесту или бинарь закреплённой версии; та же версия в .custom-gcl.yml, если есть свой бинарь. go install и go tool документация golangci-lint не рекомендует: линтер тогда собирается локальной версией Go и с зависимостями проекта (установка).
  • Конфиг — один файл в репозитории, проверенный golangci-lint config verify.
  • В CI — без ограничений вывода и с --new-from-merge-base, пока проект не вычищен целиком.
  • Кеш (~/.cache/golangci-lint) переживает прогоны и ускоряет повторные; на результат он не влияет — вторая сессия стенда шла с очищенным кешем и совпала с тёплой.

Как устроен сам конвейер, разобрано в статье про CI на GitHub Actions; линтеры как часть общей системы качества кода, вместе с форматтерами и pre-commit, — в статье про инструменты качества кодаСкоро.

Тренажёр: почини сам

Читать о находках и чинить их — разные навыки. Рядом со стендом лежит тренажёр из четырёх уровней: код с замечаниями, грейдер ./check.sh lN и подсказка на каждое замечание.

  • L1 — непроверенная ошибка, незакрытое тело ответа, лишнее присваивание.
  • L2 — секрет в коде, math/rand для идентификатора сессии, непроверенный rows.Err(), затенённая ошибка.
  • L3 — замечание, которое нужно не переписать, а подавить узко и с причиной: ошибка Write готового тела после выбранного статуса, которую здесь намеренно не обрабатывают; ранний выход без rows.Close(), который текущий конфиг не видит, — включить нужный линтер и починить.
  • L4 — дописать своё правило в скелет анализатора; проверка — analysistest.
$ python3 scripts/run-trainer.py l3 start
{"variant": "l3/start", "outcome": "red", "detail": "замечаний 3: errcheck, l3:no-linter, l3:no-nolint"}
$ python3 scripts/run-trainer.py l3 solution
{"variant": "l3/solution", "outcome": "green", "detail": "замечаний нет"}

Стенд проверяет тренажёр так же, как читатель: каждый уровень на старте красный, на эталоне из solutions/ зелёный, и у каждого замечания старта есть подсказка.

Как выбирать настройки

что на стенде что делать
набор линтеров по умолчанию — 4 из 15 ошибок; «всё» — 66 находок вне разметки стандартные пять плюс линтеры под классы дефектов проекта
govet shadow и nilness выключены и внутри включённого govet назвать анализаторы в settings.govet.enable
вывод обрезка прячет находки, код выхода тот же в CI --max-same-issues 0 --max-issues-per-linter 0 --uniq-by-line=false
шум гасится узко: по типу, по файлу, по тексту правило с записанным допущением, а не отключение правила на проект
пресеты std-error-handling прячет и настоящие дефекты проверять, что пресет убирает на своём коде, или не брать
сгенерированный код lax пропускает и нестандартные заголовки strict, если рукописные файлы похожи на сгенерированные
исправление исправление prealloc меняет nil на пустой срез проверять контракт исправления, а не только зелёный прогон
//nolint голый прячет все находки строки //nolint:<линтер> // причина и nolintlint; причина — проверяемая
легаси правка строки подхватывает её старую находку --new-from-merge-base в CI, --whole-files для чистки
своё правило готовый линтер мог поймать часть сначала проверить готовые на своём коде
версия тексты, наборы и эвристики меняются одна закреплённая версия везде

Чего эти результаты не значат

  • Ничего о скорости. Один проход загрузки пакетов и кеш — свойство golangci-lint, но здесь они не измерены.
  • Версия 2.14. Набор по умолчанию, тексты находок и пресеты — свойства этой версии; с другой версией числа будут другими.
  • Разметка — мнение автора стенда о том, что дефект, а что шум, при его допущениях о входе: URL и путь в sample/ считаются доверенными. Поведением подтверждены rows, Encode и контракты Merge, Normalize, IDs; остальная разметка опирается на документацию и устройство кода. В другом проекте os.Remove без проверки может быть нормой.
  • Зелёный линтер доказывает выполнение правил конфига, а не исправность программы. Пример sqlclosecheck без утечки — в разделе про набор по умолчанию.
  • По одному-два случая на линтер. Стенд показывает, что линтер ловит определённый случай, а не насколько полно он ловит свой класс дефектов.

Ссылки

Обсуждение в Telegram

Присоединиться →