Создание сущностей

Главная привычка, которую придётся поменять: в ent нет формы Create(ctx, User), принимающей готовую структуру. client.User.Create() вызывается без единого аргумента и возвращает UserCreate — билдер, внутри которого живёт UserMutation в режиме OpCreate. Дальше вы метод за методом наполняете мутацию: SetName записывает поле, AddGroupIDs добавляет ребро. Контекст появляется только на исполнении — Save(ctx). Это не случайность, а разделение ролей: сборка и исполнение — разные шаги. Билдер можно собрать один раз и исполнить в двух разных контекстах, отдать в функцию, которая дополнит его своими полями, повесить на него хук — мутация и есть то, на что подписываются хуки семнадцатого урока. А привычку «создать из структуры» ent предлагает заменить тем, что вы перекладываете поля сеттерами: компилятор проверит каждое, и ни одно не потеряется молча. Ещё одна особенность станет важна ниже: у билдера нет метода ID(ctx) — он появится только после OnConflict(), потому что «вернуть id вставленного» осмысленно и для обновлённой строки, а это уже другой тип билдера.

У каждого create-билдера четыре метода исполнения, и различаются они двумя осями: вернуть сущность или нет, вернуть ошибку или паниковать. Save(ctx) — основной: (*User, error), полный контроль в руках вызывающего. SaveX(ctx) — то же самое, но вместо ошибки паника: документация описывает его одной фразой «SaveX calls Save and panics if Save returns an error». Exec(ctx) — для случаев, когда сущность не нужна: метод возвращает только error, это удобный финал для цепочек-побочек вроде записи лога или факта «пользователь кликнул». ExecX(ctx) — Exec с паникой. Правило выбора простое: где ошибку обрабатывают — там Save и Exec (HTTP-хендлеры, воркеры), где ошибке нечего делать — там SaveX (инициализация приложения, сидинг демо-данных, тесты, CLI-утилиты). Паника из SaveX в HTTP-хендлере превратится в 500 через recovery-механизм фреймворка — переживёт пользователь, но не ваша логика повторов. Поэтому в прикладном коде каноничен Save, а SaveX — рабочая лошадка кода запуска и тестов.

API-слои любят указатели: поле формы пришло как string, и непонятно, то ли это «пусто», то ли значение. Для таких случаев генератор выпускает SetNillable-сеттеры: SetNillableWebsite(p string) устанавливает поле, только если p не nil, — в документации это звучит как «Avoid nil checks»: одну if-проверку на каждое поле срезает сам сеттер. Передали nil — сеттер молча пропустит, поле останется незаданным, и для Optional-колонки это законный исход: Save пройдёт, в базе будет NULL. SetNillable генерируется у полей с Optional и у полей с Default — роль SetNillableRole(string) существует, хотя сама роль обязательна: nil лишь значит «возьми дефолт». Здесь же честная тонкость, дополняющая таблицу четвёртого урока: у Nillable-полей отдельный SetNillable не генерируется вовсе. Для bio, объявленного Optional().Nillable(), сеттер SetBio уже принимает string — null-safe-версия была бы полным дублем, и в шаблоне генератора этот случай исключён комментарием про то, что nillable-сеттеры для nillable-типов не нужны. Итого: website — пара SetWebsite(string) и SetNillableWebsite(string); bio — только SetBio(string) плюс ClearBio.

Десять пользователей по одному Save — это десять INSERT и десять кругов до базы. CreateBulk собирает их в один. Точная сигнатура из сгенерированного клиента: client.User.CreateBulk(builders ...UserCreate) UserCreateBulk — метод принимает уже собранные create-билдеры, а его собственный Save возвращает ([]*User, error): сущности в том же порядке, что и билдеры. Внутри это sqlgraph.BatchCreate: один INSERT с несколькими кортежами VALUES. Следствия читаются прямо из этой механики. Если билдеры задали разные наборы полей, ent выровняет колонки, заполнив пропуски NULL-ами — INSERT требует одинаковой арки. Если ID задан хоть у одного билдера, он обязан быть у всех — иначе ошибка «inconsistent id values for batch insert»: частично заданные идентификаторы ломают расчёт id на MySQL и SQLite. Ошибка в любой строке пакета — ошибка всей операции: стейтмент один, «полу-вставки» не существует. А если у билдеров есть рёбра, ent снова откроет транзакцию сам: узлы и join-строки покатятся вместе. Для типового сценария «вставить всех из среза» есть второй вход — MapCreateBulk, он же и есть способ не собирать билдеры руками.

Регистрация по email — сценарий «нет пользователя — вставь, есть — обнови». В SQL это INSERT ... ON CONFLICT (PostgreSQL, SQLite) или INSERT ... ON DUPLICATE KEY UPDATE (MySQL), в ent — методы из флага sql/upsert, который мы включали и изучали в седьмом уроке. Метод OnConflict(opts ...sql.ConflictOption) вызывается на create-билдере, но после него цепочка меняет тип: OnConflict() возвращает UserUpsertOne — отдельного upsert-билдера, и обычные SetX на нём уже недоступны. Повторный вызов OnConflict на том же билдере даёт ошибку «ent: OnConflict was set for builder» — флаг ставится один раз. Методы нового билдера: UpdateNewValues() — при конфликте обновить изменяемые поля значениями из вставки (Immutable-поля вроде created_at и заданный вручную ID генератор честно исключает); Ignore() — «каждой колонке её же значение», то есть фактически ничего не менять; DoNothing() — честный DO NOTHING, доступный только SQLite и PostgreSQL: в MySQL такого нет, ent подменяет его Ignore-вариантом; Update(func(u ent.UserUpsert)) — полный контроль над SET-частью. Пустой OnConflict() без цели конфликта MySQL поймёт (ON DUPLICATE KEY цели не имеет), а PostgreSQL потребует указать цель — об этом отдельный predict ниже. Исполнение — Exec(ctx) или ID(ctx): второй вернёт идентификатор вставленной или обновлённой строки.

Email в схеме Unique — второй пользователь с тем же адресом упрётся в уникальный индекс, и текст ошибки придёт от драйвера: MySQL скажет «Error 1062: Duplicate entry 'anna@entgo.io' for key 'users.email'», PostgreSQL — «duplicate key value violates unique constraint "users_email_key"», SQLite — «UNIQUE constraint failed: users.email». ent классифицирует такие ошибки в пакете dialect/sql/sqlgraph: функция IsUniqueConstraintError ищет в тексте ошибки маркеры всех трёх диалектов — именно те три строки, что выше. Параллельно есть более широкий IsForeignKeyConstraintError с маркерами нарушений внешних ключей. Дальше работает сгенерированный код: любой constraint-сбой оборачивается в тип ent.ConstraintError — его Error() даёт «ent: constraint failed: » плюс исходный текст, а Unwrap отдаёт оригинал, так что цепочка errors.Is и errors.As сохраняется целиком. Итого два уровня проверки на вашей стороне: ent.IsConstraintError(err) через errors.As — «это нарушение какого-либо констрейнта», и sqlgraph.IsUniqueConstraintError(err) — «это именно дубль». Честная деталь механизма: классификация строковая, по тексту драйвера, — поэтому ent и матчит только свои три маркера на диалект, а не пытается парсить всё подряд.

Контекст в ent — сквозной: Save(ctx) передаёт его драйверу, и отмена добирается до уровня database/sql. Клиент закрыл вкладку, дедлайн истёк — драйвер вернёт context.Canceled или context.DeadlineExceeded, и ent их не заворачивает и не переписывает: обычная проверка errors.Is(err, context.Canceled) работает без сюрпризов. Полезно знать порядок этапов, чтобы понимать, что успеет произойти до отмены. Сборка дефолтов, хуки и check() с валидацией — чистый Go, контекст им не нужен: невалидный билдер вернёт ValidationError даже на уже отменённом контексте, потому что до базы дело просто не дойдёт. И наоборот: идеально собранная вставка на отменённом контексте упадёт на драйвере, ни одна строка не будет записана. С пакетами та же логика плюс атомарность: один INSERT не умеет частично исполниться, а пакет с рёбрами накрывает всё авто-транзакцией — отмена на середине откатит и узлы, и join-строки. Поэтому повтор на свежем контексте — безопасная стратегия: ent не оставляет обломков между вызовами.

Писать мы научились — но вставленные строки нужно доставать обратно. Девятый урок — 09-zaprosy «Запросы: Query builder»: client.User.Query(), предикаты из ent/user, All, Only, First и Get по идентификатору — тот словарь, который мы уже щупали в самом первом уроке на примере NameEQ. Сегодняшний арсенал вам там пригодится сразу: Only и First бросают ошибки по своим правилам, и вы уже умеете читать классификацию ent. Полный план из 25 уроков — на странице курса. Домашнее задание переводит формы из урока в пальцевую память — пройдите его на своей базе.