Українська
Від можливостей до сутностей
Пошук сутностей
Сутність (entity) – це річ, яку застосунок мусить пам’ятати й відрізняти від інших речей того самого виду за ідентичністю, а не за значеннями. Два повідомлення з однаковим текстом – усе одно два повідомлення. Простий спосіб знайти сутності – прочитати перелік можливостей із теми 1 і виписати іменники, які мають пережити перезапуск сервера:
- користувач, що входить за іменем або поштою та паролем;
- публічний профіль користувача: відображуване ім’я, короткий опис, аватар;
- токен оновлення, що тримає користувача в системі 30 днів;
- чат – особистий, група чи канал;
- членство користувача в чаті з роллю та позицією, до якої користувач прочитав повідомлення;
- повідомлення в чаті, можливо, відповідь на інше повідомлення;
- вкладення: файл, завантажений разом із повідомленням.
Інші іменники з переліку можливостей сутностями не є. «Онлайн-статус» і «набір тексту» – короткочасні стани, що живуть у пам’яті (тема 14); «лічильник непрочитаних» обчислюється з позиції читання; «сповіщення про прочитання» – це позиція читання, яку бачать інші.
Зв’язки
Рис. 3.2 показує сутності та те, як вони пов’язані. Читайте кожну лінію в обидва боки: користувач має рівно один профіль, а профіль належить рівно одному користувачеві; чат має нуль або більше учасників, і кожен учасник належить одному чату.
Рис. 3.2. Сутності Chatex та їхні зв’язки
Найцікавіший зв’язок – «багато до багатьох» між користувачами й чатами: користувач перебуває в багатьох чатах, а чат має багатьох користувачів. Це не пряме посилання, а окрема сутність ChatMember, бо зв’язок несе дані: роль, час приєднання, позицію читання, прапорець «вимкнено сповіщення».
У C# зв’язок виражається двічі:
- як властивість зовнішнього ключа, що містить ідентифікатор пов’язаної сутності:
Message.ChatId,Message.SenderId; - як навігаційна властивість, що містить пов’язаний об’єкт або колекцію:
Message.Chat,Chat.Messages. EF Core заповнює навігаційні властивості, коли ми просимо його завантажити пов’язані дані (тема 5).
Ідентифікатори: UUIDv7
Кожній сутності потрібен ідентифікатор – первинний ключ. Два звичні варіанти – ціле число, що збільшується автоматично (1, 2, 3, …, його призначає база даних), і Guid (випадкове 128-бітне значення, його призначає застосунок). Chatex використовує третій варіант – UUID версії 7, який створює Guid.CreateVersion7() (.NET 9 і новіші).
UUIDv7 починається з поточного часу в мілісекундах, за яким ідуть випадкові біти:
01a1e0ce-526e-742b-8216-1fab814b067a
└───────────┘ └───────────────────┘
milliseconds version, randomЦе дає Chatex переваги обох звичних варіантів:
- як випадковий
Guid, ідентифікатор створюється в C# до збереження сутності, тож сервіс може побудувати в пам’яті цілий граф пов’язаних об’єктів і зберегти їх одразу; ідентифікатори з різних серверів чи тестів ніколи не збігаються; а ідентифікатор нічого не каже про те, скільки є користувачів чи повідомлень; - як ціле число, ідентифікатори сортуються за часом створення. Це стає важливим у темі 5: ідентифікатор повідомлення – це також його позиція в історії. «Завантажити 50 повідомлень, старших за це» – просто
id < x, а «користувач прочитав усе до цього повідомлення» – це один ідентифікатор. Упорядковані ідентифікатори також тримають індекс бази даних компактним, бо нові рядки потрапляють у його кінець.
У межах однієї мілісекунди порядок двох ідентифікаторів випадковий. Для месенджера це не проблема: два повідомлення, надіслані в одну мілісекунду, однаково не мають природного порядку.
Чому не DateTime як ключ сортування?
Часова мітка не є унікальною: два повідомлення можуть її мати спільну, і тоді «старше за це» стає неоднозначним. Ідентифікатор унікальний за означенням, а UUIDv7 до того ж несе час.
Часові мітки
Майже кожна сутність фіксує, коли її створено, а деякі – коли її востаннє оновлено. Ми не хочемо, щоб кожен сервіс пам’ятав про встановлення цього часу, і хочемо, щоб тести керували годинником (тест «токен спливає за 30 днів» не може чекати 30 днів). Тому час встановлюється в одному місці: у темі 4 компонент EF Core – перехоплювач (interceptor) – заповнює його автоматично безпосередньо перед збереженням.
Для цього перехоплювачу потрібен спосіб розпізнавати сутності з такими часовими мітками. Їх позначають два невеликі інтерфейси.
Що зробити. Створіть папку Source/Chatex.Data/Entities і перший файл у ній:
cs
namespace Chatex.Data.Entities;
/// <summary>Creation time is stamped by <c>TimestampInterceptor</c> when the entity is first saved.</summary>
public interface IHasCreatedAt
{
DateTimeOffset CreatedAt { get; set; }
}
/// <summary>Update time is stamped by <c>TimestampInterceptor</c> on every insert and update.</summary>
public interface IHasUpdatedAt
{
DateTimeOffset UpdatedAt { get; set; }
}Коментарі <summary> – це XML-коментарі документації: IDE показує їх, коли ви наводите курсор на тип чи член, а <c> позначає код усередині тексту. Chatex документує те, що неочевидне з назви, а коментарі є частиною лістингів, бо вони – частина коду, який ви читаєте.
Де місце правилам
Сутність у Chatex – це переважно набір властивостей, які EF Core відображає на стовпці. Але деякі правила залежать лише від даних однієї сутності і потрібні в кількох місцях:
- «чи може цей учасник писати в чаті цього типу?» залежить лише від ролі учасника;
- «чи ще чинний цей токен оновлення в момент t?» залежить лише від часу його спливу та відкликання;
- «який ключ особистого чату між користувачами A і B?» залежить лише від двох ідентифікаторів.
Такі правила – методи самої сутності: їх легко знайти, легко протестувати й не можна забути. Правила, яким потрібні інші дані – «чи є відправник учасником цього чату?», «чи зайнято вже цей псевдонім?», – потребують бази даних і належать сервісам Chatex.Core (модуль 3).
Анемічні та багаті моделі предметної області
Модель, сутності якої мають лише властивості, називають анемічною; ту, де сутності самі забезпечують усі свої правила, – багатою. Chatex обирає середній шлях, що добре поєднується з EF Core: відкриті сеттери (властивості задають EF Core і сервіси) плюс методи для самодостатніх правил. Більші предметні області часто йдуть далі до багатих сутностей із закритими сеттерами та конструкторами, що забезпечують кожен інваріант; EF Core підтримує обидва стилі (про те, як він відображає класи на таблиці, див. тему про EF Core курсу C#).
Файли моделі
Модель предметної області складається з десяти файлів у Source/Chatex.Data/Entities. Ми пишемо їх трьома групами:
| Розділ | Файли |
|---|---|
| Користувачі, профілі й токени | User.cs, UserProfile.cs, RefreshToken.cs |
| Чати й учасники | ChatType.cs, ChatMemberRole.cs, Chat.cs, ChatMember.cs |
| Повідомлення й вкладення | Message.cs, Attachment.cs |
Сутності посилаються одна на одну через навігаційні властивості, тож проєкт збирається лише тоді, коли існують усі. Не турбуйтеся через помилки компілятора на кшталт «The type or namespace name Chat could not be found», поки ви на півдорозі; перевірка буде наприкінці останнього розділу.