CollectRows и RowToStructByName

Сигнатура говорит сама: CollectRows[T any](rows Rows, fn RowToFunc[T]) ([]T, error). Generic-параметр T — тип элементов среза, а второй аргумент — функция-коллектор, которая для каждой строки возвращает T или ошибку. Сама CollectRows устроена прозаично: цикл Next, вызов коллектора, append в срез, в конце проверка Err — ровно то, что вы писали руками, спрятано в библиотеку и не может быть забыто. Два контракта стоит проговорить. Первый: CollectRows закрывает курсор автоматически при выходе — defer rows.Close() не нужен, и ранние выходы больше не держат соединение пула. Второй: пустой результат — это пустой срез нулевой длины, а не ошибка и не nil: len(notes) == 0, обработка списков не ветвится. Рядом живут три родни. CollectOneRow — аналог QueryRow: берёт первую строку, при пустоте возвращает ошибку, для которой errors.Is(err, pgx.ErrNoRows) истинно. CollectExactlyOneRow — строже: более одной строки — ErrTooManyRows, и это готовый инструмент для запросов, где вторая строка означает сломанную инварианту; у обеих ошибок есть собственные тексты, no rows in result set и too many rows in result set, — их удобно оборачивать в доменные типы рядом, чтобы слой HTTP отдавал 404 и 409 из одной функции. ForEachRow — вариант без сборки среза: колбэк на каждую строку, удобно для стриминга больших выборок. CollectRows, CollectOneRow и CollectExactlyOneRow принимают один и тот же RowToFunc, поэтому коллекторы взаимозаменяемы; ForEachRow — отдельная сигнатура: срез приёмников и колбэк без аргументов, зато возвращает pgconn.CommandTag, как и Exec. Родня CollectRows — AppendRows: та же прогулка по курсору, но с дописыванием в переданный срез — удобно, когда результат нужно долить в уже собранный список.

RowToStructByName[T] — самый употребимый коллектор: он сопоставляет колонки результата с публичными полями структуры по именам, причём сравнение игнорирует регистр и подчёркивания. created_at и CreatedAt — пара, id и ID — пара, алиас вроде SELECT count(*) AS total найдёт поле Total: нормализация убирает подчёркивания с обеих сторон и сравнивает остаток без учёта регистра. Нестандартные имена — с кавычками, символами или кириллицей — проще всего заводить через db-тег, который сравнивается с колонкой буквально. Непубличные поля пропускаются: структуру с приватным кэшем или мьютексом это не сломает. Коллектор требует, чтобы каждая колонка результата нашла своё поле: лишняя колонка в SELECT приносит ошибку вида struct doesn't have corresponding row field — драйвер называет имя, которому не нашлось места. Зеркальный случай срабатывает так же строго: колонку удалили или переименовали в схеме, а поле в структуре осталось — ошибка cannot find field <имя поля> in returned row называет уже имя поля. Оба текста читаются за секунду и прямо указывают, какая из двух сторон разошлась. Сам тег при этом пишется прямо в структуру: db:"created_at" сопоставится именно с этой колонкой. Сопоставление не бесплатно — отражение и построение карты полей, — поэтому pgx кэширует карту для пары «тип структуры, набор колонок»: после первого запроса с этим же набором колонок маппинг берётся из кэша, и повторные вызовы почти не добавляют накладных расходов. Если имена всё же расходятся принципиально, нижняя граница скорости — RowToStructByPos, о нём ниже.

Тег db — единственная аннотация, которую семейство RowTo понимает из коробки. Три формы полезны на практике. db:"created_at" переименовывает: поле CreatedAt в Go, колонка created_at в базе — уже и так совпало бы, но вот колонка created_at_ms или legacy_name совпадёт только так. db:"-" исключает поле из маппинга: поле не считается соответствием ни для какой колонки — удобно для вычисляемых полей, которые заполняются после выборки. Тег на встроенных структурах работает рекурсивно: если Note встроила Auditable с полями created_at и updated_at, колонки найдут свои поля внутри. Правила именования при отсутствии тега простые: нормализация убирает подчёркивания и не смотрит на регистр, поэтому NoteID найдёт note_id, а TableName спокойно совпадёт с table_name. Тонкость, которую стоит помнить: db-тег отключает нормализацию — db:"CreatedAt" совпадёт только с колонкой CreatedAt буква в букву, поэтому в тегах пишут точное имя колонки из базы. Стилевая вилка, которую наблюдают почти все команды: либо имена колонок заранее подогнаны под snake_case Go-полей и теги почти не нужны, либо база легаси с именами вроде nm_usr — тогда теги живут в одном файле с моделью и читаются как таблица соответствий. Второй вариант неприятно пахнет, зато локализует легаси в одном месте, а не в каждом запросе.

У сопоставления по именам есть цена: отражение, карта колонок в поля, кэш. RowToStructByPos[T] выбрасывает эту работу — он раскладывает колонки по публичным полям строго по порядку, как обычный Scan, и требует, чтобы число колонок не превышало число публичных полей структуры: больше значений, чем полей — ошибка got N values, but dst struct has only M fields. Взамен — минимум накладных расходов и никаких сюрпризов с именами: порядок приёмников в Scan и порядок полей структуры становятся контрактом, который ломается молча при перестановке колонок в SELECT. Я беру ByPos на горячих путях с фиксированным SELECT, где каждая строка проверена тестом, и ByName — везде, где читаемость важнее наносекунд. Переезд с одного на другой — механическая замена одного имени, поэтому решение легко пересмотреть, если профиль нагрузки изменится. Lax-варианты — RowToStructByNameLax и RowToAddrOfStructByNameLax — снимают требование полноты: колонки, которым не нашлось поля, просто пропускаются. Это делает их совместимыми с SELECT * и с запросами, которые формируются динамически. Аналогично RowToAddrOfStructByPos возвращает указатели. Пара gotcha на память: встроенные структуры разворачиваются в маппинге — поля внутри них участвуют как свои; db-тег со значением минус исключает поле и из позиционного маппинга, и из именного.

QueryRow из пятого урока закрывает тему «ровно одной строки» наполовину: он возвращает ErrNoRows, но молча пропускает вторую строку — SELECT без UNIQUE-ограничения мог принести неожиданный дубль, и никто бы не узнал. Обобщённая пара решает оба случая явно. CollectOneRow(rows, fn) берёт первую строку, применяет коллектор и возвращает ErrNoRows на пустоте — прямой аналог QueryRow, но с любым коллектором, включая структуры. CollectExactlyOneRow(rows, fn) дополнительно требует, чтобы строк была ровно одна: вторая строка приносит ErrTooManyRows, для которого errors.Is работает так же, как для ErrNoRows. Сценарий, где это не паранойя, а контракт: поиск пользователя по логину перед созданием — вторая строка означает битое ограничение уникальности, и лучше упасть с внятной ошибкой, чем неявно работать с первой попавшейся. Сюда же просится семнадцатый урок про 23505 — там конфликты уникальности разбираются как штатная ветка кода. Помните, что оба вызова закрывают курсор сами, в том числе при раннем выходе по ошибке, — defer rows.Close() не нужен и здесь.