Чтение записей: First, Find — Take, Last, сканирование и ловушка chaining

Начнём с внутренностей: в finisher_api.go библиотеки все три финишера одиночной записи устроены одинаково и отличаются буквально одной строкой. Каждый сначала ограничивает выборку — Limit(1), то есть LIMIT 1 в SQL: базе достаточно вернуть одну строку, лишнее сканирование отсечено. First и Last добавляют сортировку по первичному ключу — клоз ORDER BY с колонкой ключа: у First по возрастанию, у Last по убыванию (Desc: true в том же clause.OrderByColumn). Take сортировку не добавляет вообще — вернётся то, что база отдаст первой. Дальше все трое включают флаг RaiseErrorOnNotFound: если запрос не вернул ни строки, финишер вернёт ErrRecordNotFound, а не молчаливый ноль в RowsAffected. Find устроен скромнее: ни LIMIT, ни ORDER BY, ни флага ошибки — он выполняет условия и раскладывает результат в то, что вы передали. Отсюда правило выбора: одна запись с гарантированным порядком — First или Last, одна запись «как попало» или со своей сортировкой — Take, всё остальное — Find.

Самый частый шаблон чтения — достать запись по ключу. Условие передаётся прямо в финишер, это inline-условия: db.First(&task, 3) построит WHERE id = 3 и добавит свой LIMIT 1 с сортировкой. Число можно отдать строкой — db.First(&task, "3") даст тот же запрос: аргумент приводится к ключу. Для строковых ключей вроде uuid форма другая — db.First(&task, "id = ?", "uuid-строка"): с плейсхолдером, как положено SQL. Срез ключей разворачивается в IN: db.Find(&todos, []int{1, 2, 3}) уедет с WHERE id IN (1,2,3). Есть и скрытая форма: если в переданной структуре ключ уже заполнен, он сам станет условием — var draft = TodoItem{ID: 10}; db.First(&draft) выполнит WHERE id = 10. Нюанс напоследок: сортировку по ключу First и Last знают, только когда им передали указатель на структуру или вызвали через db.Model(&TodoItem{}); на чужой приёмник вроде db.Table("todo_items").First(&map) связка не работает — документация прямо предупреждает, — а Take в той же ситуации работает, сортировать он и не собирается.

ErrRecordNotFound — главная ошибка чтения, и проверять её принято канонически: errors.Is(result.Error, gorm.ErrRecordNotFound). Не через ==: это та же идиома работы с ошибками, что разобрана в курсе go-basics на уроке про несколько возвращаемых значений и ошибки — errors.Is разворачивает цепочку обёрток и находит ошибку, даже если между вами и оригиналом встал fmt.Errorf с %w или код диалекта. Прямое сравнение увидит только точный оригинал. Что делать дальше — два пути. Если «записи нет» — штатный сценарий (покажем пустой экран, отдадим 404, создадим черновик), ловите ошибку и ветвитесь. Если запись обязана существовать, а не-found — ЧП, берите альтернативу из документации: db.Limit(1).Find(&task) — Find флаг RaiseErrorOnNotFound не включает, ошибки not found не будет, проверяйте result.RowsAffected == 0. Только не пишите db.Find(&task) без Limit: такой запрос просканирует всю таблицу и вернёт первую попавшуюся строку — недетерминированно, без LIMIT 1, зато с лишней работой для базы.

Зачем Take, если First предсказуемее? Затем, что сортировка по ключу — не единственный порядок в жизни. Когда порядок диктуете вы, внутренний ORDER BY только мешает: db.Order("priority DESC, created_at ASC").Take(&task) возьмёт самую приоритетную задачу, а не самую старую по id. Take же незаменим там, где модели нет: выборки из чужой таблицы через db.Table, приёмники-карты — GORM не знает схемы и не может угадать ключ, а Take и не пытается. Обратная сторона честности: без явного Order результат Take недетерминирован — «первая строка» зависит от плана запроса, физического порядка строк в таблице и версии оптимизатора. В тестах такое оставлять нельзя: либо Order, либо First. Практическое правило звучит так: Take — «мне нужна одна строка из этого набора; порядок описал я сам, или он не важен». Всё остальное — территория First и Last.

db.Find(&open, "done = ?", false) — короткий путь; постоянная форма — цепочка Where: db.Where("done = ?", false).Find(&todos). В строковом условии плейсхолдер ? подставляется безопасно: параметры едут отдельно от текста запроса, тот же механизм, что и в database/sql. Вторая форма — структурная: db.Where(&TodoItem{Status: "todo"}).Find(&todos) соберёт WHERE status = 'todo' из непустых полей структуры. Здесь притаилась ловушка, зеркальная zero values из пятого урока: нулевые поля в структурном условии игнорируются — Where(&TodoItem{Priority: 0}) не даст WHERE priority = 0, условие окажется пустым, и Find молча вернёт всю таблицу. Карты вместо структур нули включают: db.Where(map[string]interface{}{"priority": 0}).Find(&todos) даст ровно priority = 0. Выборка вернула «слишком много»? Проверьте, не схлопнулись ли нули. Полный арсенал — IN, LIKE, диапазоны, Or, Not, группировки — ждёт в седьмом уроке про Where и операторы; здесь нужна была рамка для чтения, не больше.

Как результат запроса попадает в ваши переменные? Сканирование идёт по конвенции из третьего урока: колонка snake_case соответствует полю CamelCase (title → Title), лишние колонки игнорируются, отсутствующие остаются нулями. Для полных моделей это db.First и db.Find из начала урока. Когда нужны только часть полей, работают проекции — те, кто ищет по запросу select gorm, имеют в виду ровно это: ограничить выборку колонками через Select и принять её лёгкой структурой-проекцией, приём Smart Select Fields из документации. Экономится трафик и память: тянуть Status, Priority и обе метки ради списка заголовков расточительно. Третий приёмник — карта: db.Model(&TodoItem{}).First(&row) с row map[string]interface{}{} разложит первую строку по именам колонок; для многих строк — срез карт. Model(&TodoItem{}) здесь обязателен: GORM должен знать, откуда читать таблицу. В карте лежат типы драйвера database/sql: числа int64, строки []byte, время time.Time — приводить придётся самим. Для динамики карта незаменима; в обычном коде я держусь структур — типы проверяет компилятор.

Два финишера для частичных результатов. Pluck вынимает одну колонку в срез: db.Model(&TodoItem{}).Pluck("id", &ids) положит в ids все ключи. Требование жёсткое: приёмник — срез, обычно примитивного типа; колонка — одна, не две. Нужны две колонки — это уже проекция: Select плюс Scan или Find, как в прошлом разделе. Имя GORM сначала ищет среди полей модели — Pluck("ID") поймёт, что речь о колонке id, — и Distinct с ним дружит: db.Model(&TodoItem{}).Distinct().Pluck("status", &statuses) даст SELECT DISTINCT "status", список уникальных статусов. Count считает строки: приёмник — указатель на int64, db.Model(&TodoItem{}).Count(&cnt) выполнит SELECT count(). Условия применяются как обычно: Where перед Count отфильтрует. Тонкость изнутри: count() ставится только если вы не задали свой Select, а после выполнения прежний клоз SELECT восстанавливается — цепочка продолжается без сюрпризов. И не считайте строки через len(среза): тянуть все записи ради числа — работа для базы, а не для вашего кода.

Чтение закрыло вторую букву CRUD. Дальше — условия: седьмой урок посвящён Where и операторам (IN, LIKE, диапазоны, структурные условия и их подводные камни); сегодня вы видели их в минимальной дозе, там будет полный арсенал. Затем обновления, удаление и мягкое удаление с gorm.DeletedAt — которое, кстати, уже сейчас молча добавляет к каждому чтению фильтр по deleted_at, если поле есть в модели. Если хочется освежить, откуда взялись таблица, индексы и уникальный Slug, вернитесь к четвёртому уроку про миграции; вставки и их SQL-следы разобраны в пятом уроке; полный план из 25 уроков — на странице курса. Домашка ниже закрепляет чтение целиком — и одну осознанную поломку инстанса.