Українська
DTO та курсори
Крок 1. Що повертає сервіс
Навіщо. Сервіс Chatex.Core ніколи не повертає сутність. Він повертає DTO – об’єкт передавання даних (data transfer object): невеликий незмінний запис рівно з тими даними, які має бачити викликач. Причини такі:
- Безпека. Сутність
Userмістить хеш пароля, штамп безпеки та лічильник блокувань.UserSummaryDtoмістить ідентифікатор, імена й ознаку наявності аватара. Те, чого немає в DTO, не потрапить у відповідь JSON випадково. - Стабільний контракт. Сутності можуть змінюватися разом із базою даних; DTO – це контракт з API та клієнтом Angular, і вони змінюються лише навмисно.
- Жодних сюрпризів відкладеного завантаження. DTO – прості дані: жодної навігаційної властивості, що дорівнює
null, бо ніхто її не завантажив, і жодного відстеження змін.
Кожна функція визначає свої DTO поряд зі своїм сервісом (Users/UserDtos.cs, Chats/ChatDtos.cs, …) разом із командами – записами, які надсилає клієнт, наприклад RegisterCommand(UserName, Email, Password, DisplayName) – і методами розширення для відображення, як-от user.ToSummaryDto(). Вони з’являться в темах відповідних функцій. Цей розділ додає єдиний DTO, спільний для всіх списків: сторінку.
Крок 2. Сторінки й непрозорі курсори
Навіщо. Рівень даних читає сторінками за типізованими курсорами: Guid для повідомлень і учасників, ChatListCursor(LastActivityAt, ChatId) для списку чатів (тема 5). Клієнти не повинні бачити ці типи. Якби клієнт Angular дізнався, що курсор – це «ідентифікатор повідомлення», він міг би почати будувати курсори сам, і Chatex уже ніколи не зміг би змінити посторінкове читання, нічого не зламавши.
Тому бізнес-рівень перетворює кожен курсор на непрозорий рядок: кілька байтів, закодованих у Base64Url – варіанті Base64, безпечному в URL (- і _ замість + і /, без доповнення =). Клієнт лише повертає його без змін: GET /api/chats/{id}/messages?before=AZ4v0x.... Курсор, який клієнт підробив, відхиляється з помилкою перевірки й ніколи не вважається довіреним.
Що зробити.
cs
using System.Buffers.Binary;
using System.Buffers.Text;
using Chatex.Data.Models;
namespace Chatex.Core.Common;
/// <summary>One page of a list. Pass <see cref="NextCursor"/> back to get the next page; it is null on the last one.</summary>
public sealed record PageDto<T>(IReadOnlyList<T> Items, string? NextCursor);
internal static class Paging
{
public const int DefaultLimit = 50;
public const int MaxLimit = 100;
public static Error InvalidCursor { get; } = Error.Validation("cursor", "invalid_cursor", "The cursor is not valid.");
public static int Clamp(int? limit) => Math.Clamp(limit ?? DefaultLimit, 1, MaxLimit);
}
/// <summary>
/// Opaque cursors: clients pass them back unchanged and must not parse them, so their format can change.
/// </summary>
internal static class CursorCodec
{
private const int GuidLength = 16;
private const int ChatListLength = sizeof(long) + GuidLength;
public static string? Encode(Guid? id) =>
id is { } value ? Base64Url.EncodeToString(value.ToByteArray(bigEndian: true)) : null;
public static string? Encode(ChatListCursor? cursor)
{
if (cursor is not { } value)
{
return null;
}
Span<byte> bytes = stackalloc byte[ChatListLength];
BinaryPrimitives.WriteInt64BigEndian(bytes, value.LastActivityAt.UtcTicks);
value.ChatId.TryWriteBytes(bytes[sizeof(long)..], bigEndian: true, out _);
return Base64Url.EncodeToString(bytes);
}
/// <summary>Decodes a Guid cursor; a null or empty cursor means "first page".</summary>
public static bool TryDecode(string? cursor, out Guid? id)
{
id = null;
if (string.IsNullOrEmpty(cursor))
{
return true;
}
Span<byte> bytes = stackalloc byte[GuidLength];
if (!Base64Url.TryDecodeFromChars(cursor, bytes, out var written) || written != GuidLength)
{
return false;
}
id = new Guid(bytes, bigEndian: true);
return true;
}
public static bool TryDecode(string? cursor, out ChatListCursor? chatListCursor)
{
chatListCursor = null;
if (string.IsNullOrEmpty(cursor))
{
return true;
}
Span<byte> bytes = stackalloc byte[ChatListLength];
if (!Base64Url.TryDecodeFromChars(cursor, bytes, out var written) || written != ChatListLength)
{
return false;
}
var ticks = BinaryPrimitives.ReadInt64BigEndian(bytes);
if (ticks < DateTimeOffset.MinValue.UtcTicks || ticks > DateTimeOffset.MaxValue.UtcTicks)
{
return false;
}
chatListCursor = new ChatListCursor(new DateTimeOffset(ticks, TimeSpan.Zero), new Guid(bytes[sizeof(long)..], bigEndian: true));
return true;
}
}PageDto<T>– те, що повертає кожна кінцева точка списку: елементи й наступний курсор,nullна останній сторінці.Paging.Clampобмежує ліміт, який просить клієнт, діапазоном 1…100, за замовчуванням 50. Клієнт не може попросити мільйон рядків.CursorCodec.Encode(Guid?)записує 16 байтів ідентифікатора в порядку big-endian. Типовий порядок байтівGuidзмішує частини little- і big-endian; байти big-endian збігаються з текстовим записом ідентифікатора, тож кодування однакове на кожній платформі.Encode(ChatListCursor?)пакує два значення у 24 байти: час активності як тіки UTC (long, 8 байтів), а за ним ідентифікатор чату (16 байтів).stackallocстворює буфер у стеку – жодного виділення в купі для тимчасового масиву з 24 байтів, – аSpan<byte>із діапазонами на кшталтbytes[sizeof(long)..]розрізає його без копіювання.TryDecodeдотримується патернуTry…із .NET: для хибних даних він повертаєfalse, а не кидає виняток, бо зіпсований курсор від клієнта – очікувана помилка. Порожній курсор означає «перша сторінка». Тіки перевіряються на належність до припустимого діапазонуDateTimeOffset, бо підроблений курсор може містити будь-які 8 байтів.- Перевантаження відрізняються лише типом параметра
out, тому у виклику треба вказати тип:CursorCodec.TryDecode(cursor, out ChatListCursor? after).
Перевірка
dotnet build проходить успішно. Paging використовує ChatListCursor з Chatex.Data.Models: бізнес-рівень може користуватися типами рівня даних, але ніколи навпаки.