Модели и соглашения: gorm.Model, теги, именование

Три правила. Первое: имя таблицы — snake_case во множественном числе от имени структуры. User превращается в users, TodoItem — в todo_items, Address — в addresses (склонение делает библиотека inflection, и она знает про нерегулярные формы вроде person → people). Второе: имя колонки — snake_case от имени поля. FullName становится full_name, CreatedAt — created_at. Третье: Go-аббревиатуры GORM распознаёт и не разрывает — UserID превратится в user_id, а не в u_s_e_r_i_d, APIKey — в api_key, HTTPStatus — в http_status. Список «понятных» аббревиатур зашит в код: ID, API, URL, HTTP, JSON, SQL, UUID и другие.

Эти же правила работают на автоматические таблицы связей many-to-many — их мы будем разбирать в уроке 13, и там знание конвенций прямо спасает от сюрпризов. Пока достаточно запомнить: всё, что Go пишет CamelCase, база видит в snake_case, а единственное число становится множественным на уровне таблицы.

Почти каждая модель в реальных проектах начинается со встраивания gorm.Model — стандартного набора служебных полей. Вот его настоящее определение из исходников:

Когда имя поля недостаточно или нужна особая логика, в игру входят структурные теги. Тег gorm — строка с настройками через точку с запятой, каждая вида ключ или ключ:значение. Теги читаются при разборе схемы — то есть один раз, при первом использовании модели. Самые ходовые: column переименовать колонку, size задать размер текстового типа, uniqueIndex повесить уникальный индекс, index — обычный, type вписать SQL-тип вручную, default указать значение по умолчанию, not null запретить пустоты, а дефис — полностью выкинуть поле из таблицы (удобно для кэша и вычисляемых вещей).

Соглашения — это дефолт, а не закон. Метод TableName возвращает имя таблицы напрямую и имеет высший приоритет: хватит, когда работаете с legacy-схемой, где таблицы называются по-другому, или когда компания держит префиксы. Если правило глобальное (например, все таблицы с префиксом shop_), вместо десятка методов TableName настраивается NamingStrategy в конфиге подключения: TablePrefix добавляет префикс ко всем таблицам, SingularTable запрещает множественное число — структура User будет мапиться на user, а не users. Есть и NameReplacer для точечных замен имён. Стратегию передают в gorm.Open через поле NamingStrategy конфига, тип берётся из пакета gorm.io/gorm/schema.

Тип колонки GORM выводит из типа поля, а точный SQL-тип зависит от диалекта. Строка без size превращается в text (Postgres) или varchar нужного размера; int — в bigint, bool — в boolean, float64 — в double precision, time.Time — в timestamptz, []byte — в binary/blob. Правило денег повторю отдельно: для сумм используйте явный тип:decimal или целые копейки в int — float64 в базе — источник «копеечных» расхождений в бухгалтерии.

Отдельная история — отсутствующие значения. Обычный string не различает пустую строку и NULL: оба превратятся в "". Если колонка допускает NULL, поле делают указателем (string, time.Time) — GORM запишет NULL, когда указатель nil. Альтернатива — типы sql.NullString и compañía из стандартной библиотеки; сравнение обоих подходов и третья опция, sql.Null[T] из Go 1.22, ждут вас в уроке 21. А если хочется хранить в колонке структуру или карту — это тег serializer:json и пользовательские типы, урок 22.

Модель описана — пора её материализовать. В четвёртом уроке — автомиграции: что делает AutoMigrate, чего он не умеет и когда нужны версионированные миграции. В пятом и шестом — создание записей и чтение через First и Find. Теги индексов мы использовали мельком — в уроке 18 разберём индексы всерьёз: составные, частичные и как проверить план запроса. А если хочется видеть, как модели живут в настоящем проекте, — финальный урок курса собирает слой данных блога целиком.