docs: документация по архитектуре, данным и деплою
Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой миграций, а также оглавление документации и README шаблона.
This commit is contained in:
1 parent
9d5478ddeb
commit
dbd5762ecf
10 files changed
+1308
-87
No files matched your search
@@ -0,0 +1,99 @@
|
||||
# Сущности, таблицы и колонки
|
||||
|
||||
## Расположение сущностей
|
||||
|
||||
Все 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).
|
||||
Reference in new issue
Block a user