Українська
Інтерфейси репозиторіїв
Крок 1. Навіщо репозиторії
Навіщо. Бізнес-рівень міг би використовувати ChatexDbContext напряму: db.Messages.Where(...). Chatex вставляє між ними тонкий шар репозиторіїв (repositories), і бізнес-рівень бачить лише їхні інтерфейси. Причини:
- Одне місце для кожного запиту. «50 повідомлень перед цим, з профілями відправників і вкладеннями» записано один раз, у
MessageRepository, і кожен сервіс, якому потрібна сторінка історії, викликаєGetPageAsync. Без репозиторіїв той самий ланцюжокInclude/Where/OrderByкопіювався б – і пізніше виправлявся б лише в одній копії. - Імена, що кажуть що, а не як.
chats.GetDirectAsync(alice, bob)читається як бізнес-правило; подробиці – прямий ключ, унікальний індекс, фільтр видалених чатів – лишаються всередині. - Чітка межа. Chatex.Core узагалі не посилається на типи EF Core: ні
DbContext, ніIQueryable, ніInclude. Сервіси модуля 3 можуть робити лише те, що пропонують інтерфейси, тож запит ніколи не прокрадеться в сервіс і не виконуватиметься для кожного елемента в циклі. - Шов для тестів і змін. Інтерфейси описують саме те, що бізнес-рівню потрібно від сховища.
Репозиторій і Unit of Work
Обидва патерни походять із книги Мартіна Фаулера Patterns of Enterprise Application Architecture. Репозиторій поводиться як колекція сутностей у пам’яті: додати, видалити, знайти. «Одиниця роботи» (Unit of Work) збирає зміни, зроблені під час однієї бізнес-операції, і фіксує їх разом. DbContext уже реалізує обидва, тому деякі команди користуються ним напряму; Chatex додає тонкі інтерфейси з наведених причин. Кожен метод репозиторію – це один рядок або один запит; універсального IRepository<T> із десятками нікому не потрібних методів немає.
Крок 2. Моделі результатів
Навіщо. Більшість методів репозиторіїв повертають сутності. Два види результатів потребують власних типів:
- Сторінка списку повертає елементи і курсор наступної сторінки або
nullна останній; - Рядок списку чатів об’єднує дані з кількох таблиць: чат, роль користувача й прапорець вимкнених сповіщень, попередній перегляд останнього повідомлення, кількість непрочитаних повідомлень і, для особистих чатів, співрозмовника.
Що зробити. Створіть папку Models:
cs
namespace Chatex.Data.Models;
/// <summary>One page of a keyset-paginated list. <paramref name="NextCursor"/> is null on the last page.</summary>
public sealed record CursorPage<TItem, TCursor>(IReadOnlyList<TItem> Items, TCursor? NextCursor)
where TCursor : struct;CursorPage – узагальнений запис (record): клас, рівність якого порівнює значення, записаний в один рядок із первинним конструктором. Обмеження where TCursor : struct дозволяє TCursor? означати Nullable<TCursor>, тож курсор типу Guid стає Guid? – null означає «сторінок більше немає».
cs
using Chatex.Data.Entities;
namespace Chatex.Data.Models;
/// <summary>A row of a user's chat list.</summary>
/// <param name="Peer">The other member of a direct chat; null for groups and channels.</param>
public sealed record ChatListItem(
Chat Chat,
ChatMemberRole Role,
bool IsMuted,
MessagePreview? LastMessage,
int UnreadCount,
UserSummary? Peer);
public sealed record MessagePreview(Guid Id, Guid SenderId, string Body, DateTimeOffset CreatedAt);
public sealed record UserSummary(Guid Id, string UserName, string DisplayName, string? AvatarPath);
/// <summary>Position in the chat list, which is ordered by (LastActivityAt, ChatId) descending.</summary>
public readonly record struct ChatListCursor(DateTimeOffset LastActivityAt, Guid ChatId);MessagePreview і UserSummary містять лише те, що показує список чатів, а не цілі сутності. ChatListCursor – це readonly record struct: невеликий тип-значення з рівністю за значеннями, ідеальний для курсора з двох значень. Чому саме двох – тема розділу Список чатів.
Крок 3. Інтерфейси
Що зробити. Створіть папку Abstractions. Інтерфейси публічні: їх використовує Chatex.Core. Прочитайте коментарі – вони є контрактом кожного методу й кажуть, які результати відстежуються (зміни в них збереже наступний SaveChangesAsync), а які лише для читання, і які методи пишуть негайно, не чекаючи SaveChangesAsync.
cs
using Chatex.Data.Entities;
namespace Chatex.Data.Abstractions;
/// <summary>
/// Users and their profiles. Creating users, passwords and email confirmation go through Identity's
/// <c>UserManager<User></c>, which uses the same DbContext.
/// </summary>
public interface IUserRepository
{
Task<User?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
Task<User?> GetWithProfileAsync(Guid id, CancellationToken cancellationToken = default);
/// <summary>Case-insensitive substring search on user name and display name. Read-only results.</summary>
Task<IReadOnlyList<User>> SearchAsync(string query, int limit, CancellationToken cancellationToken = default);
/// <summary>The ids from <paramref name="ids"/> that belong to existing users.</summary>
Task<IReadOnlyList<Guid>> GetExistingIdsAsync(IReadOnlyCollection<Guid> ids, CancellationToken cancellationToken = default);
void AddProfile(UserProfile profile);
/// <summary>Writes immediately, without <see cref="IUnitOfWork.SaveChangesAsync"/>.</summary>
Task UpdateLastSeenAsync(Guid userId, DateTimeOffset lastSeenAt, CancellationToken cancellationToken = default);
}Користувачів створюють через UserManager<User> з Identity (тема 8), який хешує пароль і перевіряє правила; репозиторій лише читає користувачів і додає профілі.
cs
using Chatex.Data.Entities;
namespace Chatex.Data.Abstractions;
public interface IRefreshTokenRepository
{
void Add(RefreshToken token);
/// <summary>Finds a token by its hash, with its user, tracked for revocation.</summary>
Task<RefreshToken?> GetByHashAsync(string tokenHash, CancellationToken cancellationToken = default);
/// <summary>Revokes every active token of the user (log out everywhere). Writes immediately; returns the count.</summary>
Task<int> RevokeAllForUserAsync(Guid userId, DateTimeOffset revokedAt, CancellationToken cancellationToken = default);
/// <summary>Deletes tokens that expired or were revoked before <paramref name="before"/>. Writes immediately.</summary>
Task<int> DeleteStaleAsync(DateTimeOffset before, CancellationToken cancellationToken = default);
}cs
using Chatex.Data.Entities;
using Chatex.Data.Models;
namespace Chatex.Data.Abstractions;
/// <summary>Direct chats, groups and channels. Soft-deleted chats are never returned.</summary>
public interface IChatRepository
{
/// <summary>Adds the chat; members added to <see cref="Chat.Members"/> are saved with it.</summary>
void Add(Chat chat);
Task<Chat?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
Task<Chat?> GetDirectAsync(Guid userA, Guid userB, CancellationToken cancellationToken = default);
/// <summary>Handles are stored lower-case; the lookup lower-cases <paramref name="handle"/>.</summary>
Task<Chat?> GetByHandleAsync(string handle, CancellationToken cancellationToken = default);
/// <summary>Public groups and channels whose title or handle contains <paramref name="query"/>. Read-only results.</summary>
Task<IReadOnlyList<Chat>> SearchPublicAsync(string query, int limit, CancellationToken cancellationToken = default);
/// <summary>The user's chats, most recently active first, with last message, unread count and direct-chat peer.</summary>
Task<CursorPage<ChatListItem, ChatListCursor>> GetUserChatsAsync(
Guid userId, ChatListCursor? after, int limit, CancellationToken cancellationToken = default);
/// <summary>Moves <see cref="Chat.LastActivityAt"/> forward to <paramref name="at"/>. Writes immediately.</summary>
Task TouchAsync(Guid chatId, DateTimeOffset at, CancellationToken cancellationToken = default);
}cs
using Chatex.Data.Entities;
using Chatex.Data.Models;
namespace Chatex.Data.Abstractions;
public interface IChatMemberRepository
{
void Add(ChatMember member);
void Remove(ChatMember member);
Task<ChatMember?> GetAsync(Guid chatId, Guid userId, CancellationToken cancellationToken = default);
Task<bool> IsMemberAsync(Guid chatId, Guid userId, CancellationToken cancellationToken = default);
Task<int> CountAsync(Guid chatId, CancellationToken cancellationToken = default);
/// <summary>The users from <paramref name="userIds"/> who are already members of the chat.</summary>
Task<IReadOnlyList<Guid>> GetExistingUserIdsAsync(
Guid chatId, IReadOnlyCollection<Guid> userIds, CancellationToken cancellationToken = default);
/// <summary>Members ordered by user id, with user and profile. Pass the previous page's cursor as <paramref name="afterUserId"/>.</summary>
Task<CursorPage<ChatMember, Guid>> GetMembersAsync(
Guid chatId, Guid? afterUserId, int limit, CancellationToken cancellationToken = default);
/// <summary>Ids of the user's (not deleted) chats, e.g. to join SignalR groups on connect.</summary>
Task<IReadOnlyList<Guid>> GetChatIdsForUserAsync(Guid userId, CancellationToken cancellationToken = default);
/// <summary>
/// Moves the read position to <paramref name="messageId"/> if it is newer than the current one.
/// Writes immediately; returns false when nothing changed.
/// </summary>
Task<bool> MarkReadAsync(Guid chatId, Guid userId, Guid messageId, CancellationToken cancellationToken = default);
}cs
using Chatex.Data.Entities;
using Chatex.Data.Models;
namespace Chatex.Data.Abstractions;
public interface IMessageRepository
{
void Add(Message message);
/// <summary>Tracked, with attachments, for editing or deleting.</summary>
Task<Message?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
/// <summary>Read-only, with sender profile and attachments, as history pages return it.</summary>
Task<Message?> GetDetailsAsync(Guid id, CancellationToken cancellationToken = default);
Task<bool> ExistsInChatAsync(Guid chatId, Guid messageId, CancellationToken cancellationToken = default);
/// <summary>
/// Keyset page of a chat's history, with sender profile and attachments. Read-only results.
/// <list type="bullet">
/// <item>Neither cursor: newest messages, newest first.</item>
/// <item><paramref name="before"/>: older messages, newest first (scrolling up).</item>
/// <item><paramref name="after"/>: newer messages, oldest first (filling the gap after a reconnect).</item>
/// </list>
/// <see cref="CursorPage{TItem,TCursor}.NextCursor"/> is the id to pass in the same direction for the next page.
/// </summary>
Task<CursorPage<Message, Guid>> GetPageAsync(
Guid chatId, Guid? before, Guid? after, int limit, CancellationToken cancellationToken = default);
}cs
using Chatex.Data.Entities;
namespace Chatex.Data.Abstractions;
public interface IAttachmentRepository
{
void Add(Attachment attachment);
void Remove(Attachment attachment);
/// <summary>Tracked, with its message (if any) to check access through the message's chat.</summary>
Task<Attachment?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
/// <summary>The uploader's attachments from <paramref name="ids"/> not yet linked to a message. Tracked.</summary>
Task<IReadOnlyList<Attachment>> GetPendingAsync(
Guid uploaderId, IReadOnlyCollection<Guid> ids, CancellationToken cancellationToken = default);
/// <summary>Uploads never linked to a message and created before <paramref name="before"/>. Tracked.</summary>
Task<IReadOnlyList<Attachment>> GetStalePendingAsync(
DateTimeOffset before, int limit, CancellationToken cancellationToken = default);
}cs
namespace Chatex.Data.Abstractions;
/// <summary>
/// Stores uploaded files (attachments, avatars). Files are addressed by a storage path the storage picks itself,
/// e.g. <c>2026/11/{guid}</c>; client file names are never part of it.
/// </summary>
public interface IFileStorage
{
/// <summary>Writes <paramref name="content"/> to a new file and returns its storage path.</summary>
Task<string> SaveAsync(Stream content, CancellationToken cancellationToken = default);
/// <exception cref="FileNotFoundException">No file has this storage path.</exception>
Task<Stream> OpenReadAsync(string storagePath, CancellationToken cancellationToken = default);
/// <summary>Deletes the file; does nothing if it does not exist.</summary>
Task DeleteAsync(string storagePath, CancellationToken cancellationToken = default);
}Крізь усі них проходять кілька угод:
AddіRemoveсинхронні. Вони лише наказують контексту відстежувати об’єкт; до бази даних ніщо не звертається, доки «одиниця роботи» не збереже зміни.- Кожен асинхронний метод приймає
CancellationTokenзі значенням за замовчуванням. Коли браузер закриває з’єднання, ASP.NET Core скасовує токен, і запит зупиняється, а не завершується даремно. Аналізатори з теми 2 попереджають, коли токен доступний, але не передається далі. - Колекції повертаються як
IReadOnlyList<T>, тож викликач не може додати щось до списку результатів і вважати, що це змінить базу даних. Task<T?>із результатом, що допускає null означає «може не існувати»: викликач мусить обробитиnull, і компілятор про це нагадає.
Перевірка
dotnet build успішний. Коментар до IUserRepository.UpdateLastSeenAsync посилається на IUnitOfWork, якого ще немає; компілятор перевіряє такі посилання лише під час генерування файлів документації, тож IDE може підкреслювати його до наступного розділу.