Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой миграций, а также оглавление документации и README шаблона.
100 lines
6.2 KiB
Markdown
100 lines
6.2 KiB
Markdown
# Сущности, таблицы и колонки
|
|
|
|
## Расположение сущностей
|
|
|
|
Все 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` использует её:
|
|
|
|
```ts
|
|
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` статическими импортами.
|
|
|
|
Обратная сторона того же правила: значение константы менять **можно**, миграции на него не смотрят.
|
|
Переименование таблицы — это новое значение константы плюс миграция с двумя литералами:
|
|
|
|
```ts
|
|
await queryRunner.renameTable('contests', 'brand_contests');
|
|
```
|
|
|
|
## Имена колонок
|
|
|
|
Колонки — `camelCase` (`logoId`, `totalBudget`, `createdAt`), в отличие от `snake_case` у таблиц.
|
|
Это не разнобой, а следствие дефолтной стратегии именования TypeORM: имя колонки выводится из имени
|
|
свойства как есть, и в `@Column()` его не дублируют. С таблицей так нельзя — её имя выводилось бы из
|
|
имени класса, — поэтому она и задаётся явно.
|
|
|
|
Практическое следствие: Postgres приводит неэкранированный идентификатор к нижнему регистру, так что
|
|
в raw-SQL такая колонка пишется только в двойных кавычках:
|
|
|
|
```sql
|
|
ALTER TABLE "contests" DROP COLUMN IF EXISTS "totalBudget";
|
|
```
|
|
|
|
## Nullable-колонки — явный `type`
|
|
|
|
Если тип свойства — объединение с `null`, тип колонки задаётся в декораторе явно:
|
|
|
|
```ts
|
|
@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` у уже существующей колонки миграции не требует.
|
|
|
|
Как писать сами миграции — [Написание миграций](20-migrations.md).
|