Обычная история линтера в Go-проекте: поставили golangci-lint, запустили с настройками по умолчанию, CI позеленел — галочка стоит. Что за этой галочкой, обычно не проверяют: какие классы ошибок она вообще умеет видеть, сколько находок выводит, а сколько молча отбрасывает, что прячут исключения, которые кто-то когда-то включил «чтобы не шумело».
Здесь на эти вопросы отвечает стенд, и отвечает счётом. В Go-модуль подсажены дефекты, каждый помечен на своей строке, и у каждого есть исправленная пара. Находка засчитывается, только если совпали файл, строка и линтер. Так видно не «линтер что-то нашёл», а что именно он нашёл, что пропустил и что выдал сверх задуманного.
В статье
- Стенд: разметка вместо впечатлений
- Что находит набор по умолчанию
- Что прячет вывод
- Конфиг v2: исключения и пресеты
//nolintи nolintlint- Легаси: new-from-rev
- Своё правило на go/analysis
- CI и локально
- Тренажёр: почини сам
- Как выбирать настройки
- Чего эти результаты не значат
Стенд: разметка вместо впечатлений
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 без утечки — в разделе про набор по умолчанию.
- По одному-два случая на линтер. Стенд показывает, что линтер ловит определённый случай, а не насколько полно он ловит свой класс дефектов.
Ссылки
- Стенд: digital-cookbook/go/golangci-lint — восемь осей, тренажёр в
trainer/. - golangci-lint: конфигурация
- golangci-lint: исключения и пресеты
- golangci-lint: module plugin system
- go/analysis
- staticcheck
- Контекст и сроки в Go — статья про context; ошибки — статья про обработку ошибок.
Обсуждение в Telegram
Присоединиться →