4.0 KiB
Конвенции кода: бэклог
Кандидаты в docs/conventions/, ещё не принятые.
Пишем по мере реального трения, а не вперёд; принятое переезжает в
docs/conventions/. Уже приняты: logging.md, config.md, errors.md.
Tier 2 — кандидаты в отдельный доку
Завести, когда паттерн подтвердит второй-третий проект (или поймаем трение в jellybit).
Раскладка пакетов и направление зависимостей
cmd/<bin> (точка входа) + internal/<компонент> по доменам. Домен не
импортирует транспорт; зависимости направлены внутрь, к домену. Без свалок
util/common/helpers. Стыкуется с «тонкие транспорты, единое ядро» из
архитектуры.
context.Context
Первый параметр функции; не хранить в структурах; в Value только
request-scoped данные, не зависимости. Перенос логгера/корреляции через ctx
(уже реализовано — internal/logctx, см. logging.md). Дедлайны/отмена
протягиваются сквозь стадии.
Внешние клиенты (HTTP к зависимостям)
Таймаут на каждый исходящий вызов (не полагаться на дефолт); не
http.DefaultClient; ретраи с backoff и потолком попыток; HTTP-прокси из
конфига (proxy-поля уже есть). Прямое продолжение ext.*-логирования
(logging.md) и трансляции ошибок (errors.md). Кандидат — общий
конструктор клиента вместо копипасты в qbt/llm/jellyfin/metadata.
Тесты
Table-driven; фикстуры в testdata/; t.Parallel() где безопасно; выбрать
и зафиксировать stdlib testing vs testify; разделение быстрых и
интеграционных (уже есть *_integration_test.go + env-гейты). Что считаем
обязательным к покрытию (валидация конфига, распознавание, раскладка).
Tier 3 — тонкий бюллетень или мелочь
Не тянет на отдельный доку: строка-инвариант в CLAUDE.md или стек-специфика.
БД и миграции (SQLite + goose)
Миграции forward-only; запросы только параметризованные (без склейки строк);
явные транзакции для многошаговых изменений; context-aware запросы. Сильно
стек-специфично — возможно, в CLAUDE.md, не в общий доку.
Конкурентность
Каждая горутина знает, как останавливается (ctx/закрытие канала); без
утечек; errgroup для связанных задач; фоновые процессы гасятся при
shutdown. Актуально для воркера/фоновых задач, не для всего проекта.
CLI
Данные — в stdout, логи и диагностика — в stderr; осмысленные коды
возврата. Для CLI-подмножества проектов (у jellybit — диагностические
команды add/recognize/healthcheck).
Время
Явный TZ всегда; хранение и логи — в UTC; бизнес-логика в Europe/Moscow.
Уже частично в CLAUDE.md и logging.md — при желании свести в один
короткий инвариант.