68 lines
4.0 KiB
Markdown
68 lines
4.0 KiB
Markdown
# Конвенции кода: бэклог
|
|
|
|
Кандидаты в [docs/conventions/](../conventions/README.md), ещё не принятые.
|
|
Пишем по мере реального трения, а не вперёд; принятое переезжает в
|
|
`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` — при желании свести в один
|
|
короткий инвариант.
|