Поля: типы и валидация

Все конструкторы полей живут в пакете entgo.io/ent/schema/field — мы импортировали его ещё во втором уроке. Синтаксис единый: field.String("name") — первый аргумент становится именем колонки, методы после него — атрибуты поля. Числовые поля самые разветвлённые: field.Int даёт в структуре int, рядом есть Int8, Int16, Int32, Int64 и беззнаковые варианты, field.Float — это float64 (есть и Float32). Поддерживаются все числовые типы Go, так что узких мест здесь почти не бывает. Строки делятся на field.String под короткие значения и field.Text под длинные тексты — body поста просится именно туда. Дальше по списку: field.Bool, field.Time со структурой time.Time, field.Bytes для сырых байтов ([]byte).

Три конструктора устроены иначе: они принимают не имя типа, а пример значения. field.UUID("token", uuid.UUID{}) выводит Go-тип из переданного образца, field.JSON("prefs", Prefs{}) — из вашего собственного типа, field.Enum("role") вообще работает со списком допустимых строк. Тип поля определяет тип в сгенерированной структуре и тип колонки в базе; правила второй трансформации — тема урока про миграции, пока следим за Go-стороной.

И имя поля превращается в имя колонки как есть — мы писали created_at с подчёркиванием именно поэтому. Если колонка должна называться иначе, есть StorageKey: field.String("name").StorageKey("user_name") оставит в коде поле Name, а в базе появится колонка user_name. Развязка нужна редко — обычно против легаси-схем, которые нельзя переименовывать, но знать про неё стоит до того, как колонки разъедутся по проекту.

Поля с Default не требуют Set-вызова: при создании ent сам подставит значение. Для констант это выглядит скучно и надёжно: field.Bool("verified").Default(false), field.Enum("role") с Default("user"). Интересное начинается со времени. У time-полей Default принимает функцию: field.Time("created_at").Default(time.Now) — time.Now без скобок, вы передаёте саму функцию, а ent вызывает её в момент создания каждой записи. Классическая ошибка — time.Now() со скобками: выражение вычислится один раз на старте, и все записи за жизнь процесса получат одно и то же время. Ошибка коварная: код собирается, тесты на свежем клиенте проходят, а через неделю в базе обнаруживается поле created_at, застывшее в моменте.

Для любых типов с генерацией значения есть DefaultFunc — туда передают свою функцию-генератор, например cuid.New. Поле с Default остаётся обязательным по смыслу: записи без значения не будет, просто заполняет его ent, а не вы. Ограничение: уникальным полям Default запрещён — авторы ent сознательно не смешивают автозначения с уникальностью.

Рядом живут два атрибута из таблицы describe. UpdateDefault — функция, применяемая при каждом обновлении: поле updated_at описывают парой Default(time.Now).UpdateDefault(time.Now). Immutable — поле, которое задаётся только при создании: для update-билдеров сеттер просто не генерируется, поменять created_at через код не выйдет. Вернём оба атрибута в схему чуть ниже.

Поля ent обязательны по умолчанию: не вызвали SetAge — Save вернёт ошибку вида ent: missing required field "User.age". ent не подставляет нулевые значения молча, и это спасает от половины тихих багов. Метод Optional() переводит поле в другой режим: его можно не задавать при создании, а колонка в базе становится NULL-able. Биография пользователя — классический кандидат: есть она не у всех.

Но у Optional есть особенность, о которой редко думают заранее: в сгенерированной структуре поле остаётся обычным string. Пропустили SetBio — в Bio пустая строка, неотличимая от намеренно пустой биографии «я ничего о себе не рассказываю». Нулевое значение Go и отсутствие значения в базе слиплись в одно — знакомая болезнь, если вы привыкли к GORM: в его вводном уроке мы видели, как нулевые значения и «нет данных» путаются в одном поле структуры.

Разводит их Nillable(). Для Optional-поля типа T он меняет тип в структуре на T: ent читает NULL из базы и кладёт в поле nil. Получилась классическая пара Optional().Nillable(): SetBio можно не вызывать, а в коде Bio — string, где nil значит «в базе NULL». Nillable работает и на обязательных полях — чтобы не ловить нулевые значения при частичных выборках, — но в прикладных схемах почти всегда встречается в этой паре. Предикаты для проверки на NULL и остальная NULL-семантика — тема четвёртого урока, здесь берём минимум, который нужен для схемы.

Валидатор — метод на билдере поля, который добавляет проверку значения. NotEmpty и Unique вы уже видели в первом уроке — они появились в схеме User в первые минуты знакомства с ent. Теперь соберём каталог целиком. Для строк: MinLen и MaxLen — границы длины, Match — совпадение с регулярным выражением, NotEmpty — запрет пустой строки, который внутри устроен просто как MinLen(1) (пробел, кстати, пройдёт). Для чисел: Min и Max с включёнными границами, Range(i, j) для отрезка, Positive, Negative и NonNegative как готовые комбинации — Positive устроен как Min(1), поэтому ноль не пройдёт, и это надо помнить, описывая «необязательный» возраст. Валидаторов на одном поле может быть несколько — ent применит их все по очереди.

У MaxLen есть скрытая вторая работа: она же подсказывает генератору размер строковой колонки. А если встроенных проверок мало, любой билдер принимает Validate(fn) — вашу функцию, возвращающую nil или ошибку.

Рядом с валидаторами по смыслу живёт Sensitive(). Это не проверка, а пометка: поле вроде пароля не печатается в логах и отладочных выводах ent и пропускается при кодировании в JSON. struct-тегов у sensitive-полей не бывает — ent убирает их из сгенерированного представления сознательно.

field.Enum("role").Values("user", "moderator", "admin") — Values задаёт полный список допустимых значений, и это список навсегда: добавить четвёртую роль значит отредактировать схему и перегенерировать код, других путей нет. Генератор отработает щедро: в пакете ent появится тип Role — строка с репутацией — и константы RoleUser, RoleModerator, RoleAdmin, так что в прикладном коде роли живут именованными значениями, а не сырыми строками.

Честно про границу защиты. Компилятор от произвольной строки не спасёт: SetRole("boss") соберётся, потому что нетипизированная строковая константа присваивается любому строковому типу. Но дальше в дело вступает сгенерированный валидатор: Save сверит значение со списком Values и вернёт ошибку вида «invalid enum value» ещё до базы. Свой контур защиты у enum замкнут, и это приятная новость.

Default("user") заполняет роль, если её не задали: новые пользователи по умолчанию обычные, а модератора назначает отдельная операция обновления. По умолчанию в PostgreSQL и SQLite enum — обычная строковая колонка, в MySQL колонка становится нативным ENUM; если хочется нативных enum-типов и в PostgreSQL, у ent есть отдельный сценарий миграций — вернёмся к нему в уроке про миграции.

Самое важное про валидацию — где она выполняется. Валидаторы живут в сгенерированном коде: Save сначала прогоняет все проверки и только потом идёт в базу. Провал валидатора выглядит так: Save(ctx) возвращает не nil-ошибку, а значение типа ValidationError из пакета blog/ent, и текст у неё конкретный: ent: validator failed for field "User.age": value out of range. Обязательное поле, которое забыли задать, — тоже ValidationError, но с другим текстом: ent: missing required field "User.age". Обе ошибки типизированы, различаются через errors.As, у ValidationError есть поле Name с именем провинившегося поля — удобно логировать.

Уникальность живёт отдельно: Unique() создаёт уникальный индекс, и проверяет его сама база. Дубликат email рождает ошибку от СУБД, которую ent заворачивает в ConstraintError — она прилетает после похода в базу, а не до. Это не причуда, а честное распределение ролей: валидатор не увидит параллельную вставку из другого процесса, индекс увидит.

Теперь границы честности. Валидаторы исполняются в клиенте ent — всё, что обходит клиент, мимо проверок: рукописный INSERT, второй сервис на той же базе, скрипт миграции данных. Поэтому правила, от которых зависит целостность, дублируют ограничениями базы: NOT NULL, уникальные индексы, CHECK. Валидаторы — это ранний отказ в вашем коде с понятным текстом ошибки, а не бронированная дверь в данные.

Схема User повзрослела, пост получил свои поля — фундамент для связей готов. Четвёртый урок полностью посвящит паре Optional и Nillable: предикаты для проверки на NULL, поведение Set-методов и то, как NULL ведёт себя в чтении и загрузках. Пятый и шестой — рёбра: наконец свяжем User и Post, добавим комментарии, и поля author_id появятся в таблице posts сами. Напоминание из второго урока остаётся в силе: после каждой правки схемы — go generate ./ent, иначе новые Set-методы не скомпилируются. Полный план из 25 уроков лежит на странице курса ent, а домашка ниже — лучший способ закрепить сегодня описанные поля.