Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой миграций, а также оглавление документации и README шаблона.
6.2 KiB
Сущности, таблицы и колонки
Расположение сущностей
Все TypeORM-сущности модуля лежат в подпапке entities/ в корне модуля:
apps/api/src/contests/
├── dto/
├── entities/
│ └── contest.entity.ts
├── contests.controller.ts
├── contests.module.ts
└── contests.service.ts
- Правило без исключений: даже если сущность в модуле одна, она всё равно в
entities/. Иначе при добавлении второй сущности пришлось бы переносить первую и править все её импорты. - Имя файла —
<сущность>.entity.tsв kebab-case (project-member.entity.ts). - Один файл — одна сущность.
Имя таблицы — единая точка правды
Рядом с сущностью, в том же файле, объявляется экспортируемая константа с именем таблицы, и
@Entity использует её:
export const CONTESTS_TABLE_NAME = 'contests';
@Entity({ name: CONTESTS_TABLE_NAME })
export class Contest {
// ...
}
- Константа именуется
<СУЩНОСТЬ>_TABLE_NAMEв SCREAMING_SNAKE_CASE. - Значение —
snake_case, множественное число (contests,project_members). @Entity()без явногоnameне используется: имя таблицы не должно выводиться из имени класса — переименование класса тогда молча меняет схему.
Константа — единая точка правды об имени таблицы для кода приложения: @Entity, DAL, raw-SQL,
алиасы createQueryBuilder, утилиты очистки в тестах. Строковый литерал с именем таблицы за
пределами объявления константы в коде приложения не пишется.
Миграции константу не используют
Миграция — снимок схемы на момент, когда её написали, и она обязана оставаться рабочей независимо от того, что стало с кодом дальше. Поэтому в миграции имя таблицы пишется строковым литералом.
Пример из репозитория: коммит b710c1b9 удалил модуль подписок вместе с файлом
subscriptions/subscription-plan.entity.ts — а миграции 1774000000000-add-subscription-plans.ts и
1788825600000-drop-subscriptions-and-metrics-limits.ts никуда не делись и по-прежнему создают и
удаляют таблицу subscription_plans. Импортируй они константу из удалённого файла — сборка встала
бы целиком: миграции попадают в бандл data-source.js статическими импортами.
Обратная сторона того же правила: значение константы менять можно, миграции на него не смотрят. Переименование таблицы — это новое значение константы плюс миграция с двумя литералами:
await queryRunner.renameTable('contests', 'brand_contests');
Имена колонок
Колонки — camelCase (logoId, totalBudget, createdAt), в отличие от snake_case у таблиц.
Это не разнобой, а следствие дефолтной стратегии именования TypeORM: имя колонки выводится из имени
свойства как есть, и в @Column() его не дублируют. С таблицей так нельзя — её имя выводилось бы из
имени класса, — поэтому она и задаётся явно.
Практическое следствие: Postgres приводит неэкранированный идентификатор к нижнему регистру, так что в raw-SQL такая колонка пишется только в двойных кавычках:
ALTER TABLE "contests" DROP COLUMN IF EXISTS "totalBudget";
Nullable-колонки — явный type
Если тип свойства — объединение с null, тип колонки задаётся в декораторе явно:
@Column({ type: 'varchar', nullable: true })
banReason: string | null;
@Column({ type: 'timestamp', nullable: true })
emailVerificationTokenExpires: Date | null;
Без type TypeORM выводит тип колонки из метаданных декоратора (design:type), а для объединения
string | null TypeScript отдаёт Object — вывести из него тип колонки нельзя, и приложение падает
на старте с ColumnTypeUndefinedError ещё до первого запроса. Ошибка вылезает только при реальном
поднятии контекста: юнит-тесты сервиса метаданные сущностей не строят и остаются зелёными.
Само объявление string | null при этом предпочтительнее, чем string у nullable-колонки: тип
сущности должен отражать то, что лежит в базе, иначе «пустое» значение приходится проверять вопреки
типу. Схему явный type не меняет — varchar без длины это то же character varying, что и в
миграции, — так что переход на | null у уже существующей колонки миграции не требует.
Как писать сами миграции — Написание миграций.