Хуки жизненного цикла — BeforeCreate, AfterUpdate, валидация и SkipHooks в GORM

Дока формулирует предмет точно: Hooks are functions that are called before or after creation/querying/updating/deletion — хуки это функции, вызываемые до или после создания, чтения, обновления и удаления. И второе предложение важнее первого: if any callback returns an error, GORM will stop future operations and rollback current transaction — если колбэк вернул ошибку, GORM останавливает дальнейшие операции и откатывает текущую транзакцию. Хук — это не настройка и не параметр вызова, а метод самой модели: вы объявляете func (t TodoItem) BeforeCreate(tx gorm.DB) error, и GORM сам находит его при каждой операции. Технически список сверен с исходниками: девять интерфейсов объявлены в callbacks/interfaces.go — BeforeCreateInterface, AfterCreateInterface, BeforeUpdateInterface, AfterUpdateInterface, BeforeSaveInterface, AfterSaveInterface, BeforeDeleteInterface, AfterDeleteInterface и AfterFindInterface, каждый требует ровно один метод с сигнатурой func(gorm.DB) error — так и записано на gorm.io/docs/hooks.html: The type of hook methods should be func(gorm.DB) error. Перед операцией GORM проверяет модель на соответствие интерфейсу — метод есть, значит будет вызван; нет метода — нет вызова, никаких регистраций в конфиге. Отсюда два следствия. Первое: нужен приёмник-указатель — хук правит поля структуры, и правка должна остаться в том объекте, который уедет в INSERT; мы разберём эту ловушку отдельно. Второе: хук — свойство типа, а не данных: у карты значений нет методов, поэтому валидацию в db.Create(map...) не встроить. Кто ищет по запросу hooks gorm, обычно хочет именно этого: повесить бизнес-правило на саму модель, чтобы оно срабатывало везде, где модель создают или правят.

Чтобы рассуждать о порядке, откроем callbacks/callbacks.go — в RegisterDefaultCallbacks конвейер создания собран из семи колбэков, и это буквально порядок вызовов: gorm:begin_transaction, gorm:before_create, gorm:save_before_associations, gorm:create, gorm:save_after_associations, gorm:after_create и gorm:commit_or_rollback_transaction. Дока рисует то же самое схемой, записанной сплошным комментарием: begin transaction BeforeSave BeforeCreate save before associations insert into database save after associations AfterCreate AfterSave commit or rollback transaction. Обратите внимание: BeforeSave стоит перед BeforeCreate, и это не случайность — Save-хуки общие для создания и обновления, частные — после них. Сам вызов хука живёт в callbacks/callmethod.go: callMethod берёт отражённое значение модели, для среза перебирает элементы по одному (батч-вставка дёргает хук на каждую запись), и передаёт в него tx := db.Session(&gorm.Session{NewDB: true}) — свежую сессию. Дока называет это Modify current operation: через tx.Statement вы можете править текущую операцию — tx.Statement.Select("Name", "Age"), tx.Statement.AddClause(clause.OnConflict{DoNothing: true}) — а текст поясняет: tx is new session mode with the NewDB option, operations based on it will run inside same transaction but without any current conditions. Переведём в термины пятнадцатого урока: tx внутри хука — это транзакционный инстанс на том же ConnPool, что и основная операция (его подменил gorm:begin_transaction), но Statement у него чистый — условия исходной цепочки не протекают. Поэтому операции из хука едут в ту же транзакцию и разделяют её судьбу: откат основной операции откатит и их.

Пятнадцатый урок обещал связку — вот она, с точностью до строки исходников. Каждый хуковой колбэк начинается с охраны db.Error == nil: если ошибка уже есть, BeforeCreate, AfterCreate, BeforeUpdate и соседи не вызываются вовсе — первое заражение останавливает конвейер. Ошибка из хука попадает в db через AddError (gorm.go): если db.Error был пуст, он становится вашей ошибкой, а если уже был — новая приклеивается через fmt.Errorf("%v; %w"). Дальше два сценария. При одиночной операции в дело вступает последний колбэк конвейера: gorm:commit_or_rollback_transaction, разобранный в пятнадцатом уроке, видит db.Error != nil и делает Rollback — вернув ошибку из BeforeCreate, вы откатили ещё не отправленный INSERT; INSERT даже не поедет в базу, потому что gorm:create проверяет db.Error и выходит сразу. А внутри db.Transaction ошибка операции приедет в err вашего if err := tx.Create(...).Error — и вы вернёте её из fc, откатив весь блок. Дока закрепляет NOTE-ом: Save/Delete operations in GORM are running in transactions by default, so changes made in that transaction are not visible until it is committed, if you return any error in your hooks, the change will be rollbacked — изменения в транзакции не видны, пока она не закоммичена, и ошибка из хука её откатит. Симметричное следствие: AfterCreate стоит после INSERT, но до COMMIT — ошибка в нём откатывает уже выполненный INSERT. Дока даже приводит такой хук с errors.New("rollback invalid user") — строка, отправленная в базу, выжить не успевает.

Пара Save-хуков существует потому, что у создания и обновления правила разные. BeforeSave вызывается в обоих конвейерах записи — в create-колбэке условие db.Statement.Schema.BeforeSave || db.Statement.Schema.BeforeCreate, в update-колбэке BeforeSave || BeforeUpdate; туда просится валидация, обязательная всегда: заголовок не пуст, приоритет в диапазоне, статус из допустимого набора. BeforeCreate — только перед INSERT: генерация уникальных значений вроде u.UUID = uuid.New() из доковского примера, сборка слага, подстановка стартовых значений. Прежде чем ставить проверку, задайте себе вопрос: при обновлении это поле может стать невалидным? Если да — BeforeSave. Доковский пример собирает обе идеи в одном методе: u.UUID = uuid.New() — генерация, if !u.IsValid() { err = errors.New("can't save invalid data") } — валидация, return — и ошибка, как мы выяснили, откатывает операцию. Симметричная пара AfterCreate/AfterSave стоит после записи: там делают дозаполнение структур, Related-операции той же транзакцией, уведомления. Валидацию туда ставить не стоит — мусор к этому моменту уже поехал в INSERT; максимум, что уместно в After, — проверка пост-условий, когда нарушение говорит не о данных, а о сбое логики. И не путайте слои: хук валидирует бизнес-правила, а последнее слово всё равно за ограничениями базы — уникальный Slug защищает UNIQUE-индекс из четвёртого урока, и дубликат вернёт ошибку драйвера, какую бы проверку вы ни написали. Хук ускоряет обратную связь, индекс гарантирует инвариант.

Обновление собирается из восьми колбэков: gorm:begin_transaction, gorm:setup_reflect_value, gorm:before_update, gorm:save_before_associations, gorm:update, gorm:save_after_associations, gorm:after_update, gorm:commit_or_rollback_transaction. gorm:setup_reflect_value — служебный: он восстанавливает отражённое значение модели после цепочек. Затем пара BeforeSave/BeforeUpdate — в этом порядке, как и у создания. Доковский пример BeforeUpdate — защитник неизменяемых записей: if u.readonly() { err = errors.New("read only user") } — попробовали отредактировать read-only пользователя, обновление даже не уехало. А AfterUpdate в доке демонстрирует операцию той же транзакцией: if u.Confirmed { tx.Model(&Address{}).Where("user_id = ?", u.ID).Update("verfied", true) } — подтверждение пользователя тянет за собой правку его адресов, и если она упадёт, AddError положит ошибку в db.Error, а финальный колбэк откатит и основной UPDATE. Отдельного разговора заслуживает правка состава самой операции из хука. Прямой путь — tx.Statement: Select перечисляет колонки, AddClause дописывает клозу. Для подмешивания значения в набор колонок есть Statement.SetColumn из statement.go: с картой-приёмником он добавляет ключ в dest, со структурой — пишет поле; doc-комментарий различает режимы: stmt.SetColumn("Name", "jinzhu") — Hooks Method, а с третьим аргументом true — Callbacks Method. Именно так BeforeUpdate из канона добавляет audited=true в тот же UPDATE: один запрос, ноль лишних кругов в базу, и флаг едет в одной транзакции с основными полями.

Флаг, которым UpdateColumn выключает хуки, публичен и управляется тремя способами. Точечный — Session: db.Session(&gorm.Session{SkipHooks: true}).Model(&task).Updates(...) — Statement унаследует SkipHooks, и BeforeSave/BeforeUpdate/AfterUpdate пропустятся. Глобальный — Config при gorm.Open: в gorm.go поле SkipHooks есть прямо в Config, и Open переносит его в Statement каждого соединения. А третий способ вы уже знаете — UpdateColumn и UpdateColumns из finisher_api.go, обе строки tx.Statement.SkipHooks = true мы видели в восьмом уроке, когда говорили про служебные правки без updated_at. Теперь ту механику можно объяснить честно: AutoUpdateTime-логика при обновлении стоит под тем же условием !stmt.SkipHooks в callbacks/update.go — поэтому UpdateColumn не двигает updated_at, и обычный Update в сессии с SkipHooks тоже его не тронет. Нюанс на стороне создания: в ConvertToCreateValues автополя CreatedAt/UpdatedAt живут без оглядки на SkipHooks — это AutoCreateTime, а не хук, и Create в сессии с SkipHooks всё равно проставит время. Есть и скрытый вызов: Save на записи, чья update-ветка затронула ноль строк, дофоллбечивает на Create с Session{SkipHooks: true} и Upsert-клозой UpdateAll — восстановление пропавшей строки в терминах Save хуков не дёргает. Практический вывод: хуки — не охрана от админа, а слой по умолчанию; тот, кто захочет обойти, обойдёт легально, поэтому инварианты дублируются ограничениями базы. И наоборот: если вы сами зовёте модель из хука, воспользуйтесь тем же флагом — об этом в ловушках ниже.

Канон живёт связками: задача принадлежит списку, теги — m2m. Что происходит с хуками, когда сохраняется вся пачка одним Create? Доковская схема уже содержит ответ: между BeforeCreate владельца и INSERT стоят save before associations, а после INSERT — save after associations. По исходникам это два колбэка из callbacks/associations.go: SaveBeforeAssociations сохраняет belongs to-связи — список задачи, если он задан структурой с нулевым ключом, — а SaveAfterAssociations — has one, has many и many2many вместе со строками join-таблицы. Важнейшая деталь: дети сохраняются не сырым SQL, а полноценным Create через saveAssociations — tx собирается как Session{NewDB: true} с наследуемыми настройками, включая SkipHooks: db.Statement.SkipHooks. Значит, хуки детей работают: у списка, создаваемого вместе с задачей, вызовутся его BeforeSave/BeforeCreate, у тегов — свои. Флаг наследуется: если владельца сохраняли со SkipHooks, дети тоже пройдут без хуков. Порядок целиком: BEGIN; BeforeSave/BeforeCreate владельца; belongs to-дети с их хуками; INSERT владельца; has many/m2m-дети с их хуками; INSERT строк join-таблицы — здесь это отдельный Create для модели связи из тринадцатого урока; AfterCreate/AfterSave владельца; COMMIT или ROLLBACK. Заметьте асимметрию: принадлежности съезжают ДО владельца — их ключи нужны для внешних ключей, потомки — ПОСЛЕ, когда есть ключ владельца. Ошибка на любом уровне кладёт db.Error и откатывает всё одним ROLLBACK — общая судьба, ради которой авто-транзакция и обёртывает каскад.

Чтение имеет свой хук — AfterFind, и конвейер у него свой: gorm:query, затем gorm:preload из четырнадцатого урока, затем gorm:after_query. Колбэк AfterQuery в callbacks/query.go сначала подчищает клозу FROM — чтобы join-данные не мешали последующим выборкам, — а затем вызывает AfterFind, и у вызова два охранника: db.Error == nil и db.RowsAffected > 0 — на пустой выборке, когда First вернул ошибку «запись не найдена», хук не зовётся вовсе: нечего обрабатывать. Дока рисует порядок чтения так: load data from database / Preloading (eager loading) / AfterFind — жадная загрузка успевает до хука, значит в AfterFind дети уже на месте. Пример из доки подставляет значение по умолчанию: if u.MemberShip == "" { u.MemberShip = "user" } — и наш AfterFind делает ровно то же со статусом строк, переживших смену дефолта. Второй жанр — вычисляемые поля: возраст задачи, человекочитаемый приоритет, собранный из частей адрес — всё, что база не хранит, но API отдаёт. Границы жанра помните: AfterFind выполняется на каждую прочитанную запись — тяжёлая логика умножится на длину выборки; и он не запускается у сырых запросов Raw и Row из десятого урока — там сканирование идёт мимо конвейера модели, у карт нет методов. Выборки в структуры зовут его по-прежнему — схема модели та же.

Хуки встроили модель в конвейеры, которые пятнадцатый урок научил открывать и закрывать: сигнатура func(tx *gorm.DB) error даёт вам транзакционный инстанс, а ошибка — гарантированный откат; механика AutoUpdateTime и служебных правок, теперь понятая через SkipHooks, живёт в восьмом уроке, а весь маршрут BEGIN—COMMIT — в пятнадцатом. Логичный следующий вопрос — чтение больших таблиц: когда AfterFind зовётся на тысячу строк, а выборка отдаётся страницами, встаёт пагинация. Семнадцатый урок «Пагинация и сортировка» покажет Offset/Limit, keyset-пагинацию и Order — как отдавать данные порциями, не выгребая таблицу целиком и не пересчитывая смещения дважды. Карта курса из 25 уроков — на странице курса. Домашка ниже прогоняет хуки по всем четырём конвейерам.