Українська
Результати й помилки
Крок 1. Винятки чи результати
Навіщо. Більшість операцій месенджера може завершитися очікуваною помилкою: пароль хибний, ідентифікатор зайнято, передплатник намагається писати в канал, чату не існує. Це не вади, а відповіді. Звичайний інструмент C# для збоїв – виняток – для них підходить погано:
- Сигнатура їх ховає.
Task<MessageDto> SendAsync(...)нічого не каже про п’ять способів, якими надсилання може не вдатися; викликач дізнається про них із документації або вже в робочому середовищі. - Вони дорогі й галасливі. Виняток збирає трасування стека й потрапляє в журнали та налагоджувачі як проблема, хоча «хибний пароль» трапляється сто разів на день за задумом.
- Відображення їх на HTTP – непряме. API потрібен був би блок catch або проміжне ПЗ (middleware), що знає кожен тип винятку бізнес-рівня.
Тому Chatex ділить збої на два види:
- Очікувані помилки повертаються як
Result, що містить або значення, абоError. СигнатураTask<Result<MessageDto>> SendAsync(...)повідомляє кожному викликачеві: це може не вдатися, обробіть це. - Вади –
nullтам, де його бути не може, порушений інваріант, втрачена база даних – як і раніше кидаються винятками. Їх не слід обробляти по одній; вони завершуються відповіддю 500 і записом у журналі.
Крок 2. Помилка
Навіщо. Помилка має слугувати двом читачам. Програмі – клієнту Angular, тесту – потрібне щось стабільне для порівняння: короткий код на кшталт handle_taken, що ніколи не змінюється. Людині потрібне речення. А API має знати, яким HTTP-статусом відповісти, не знаючи кожної помилки бізнес-рівня. Тому помилка має три частини: грубий вид, сталий код і людське повідомлення, а також необов’язкові подробиці за полями для помилок перевірки.
Що зробити. Створіть папку Common у Chatex.Core (нічого не видаляйте: проєкт порожній ще з теми 2):
cs
namespace Chatex.Core.Common;
/// <summary>What went wrong, coarse enough for the Api to pick an HTTP status from it.</summary>
public enum ErrorKind
{
Validation,
NotFound,
Forbidden,
Conflict,
Unauthorized,
}
/// <summary>An expected failure. <see cref="Code"/> is stable and meant for clients; <see cref="Message"/> is for people.</summary>
public sealed record Error(ErrorKind Kind, string Code, string Message)
{
/// <summary>Per-field messages for validation errors, keyed by property name.</summary>
public IReadOnlyDictionary<string, string[]>? Details { get; init; }
public static Error Validation(string code, string message) => new(ErrorKind.Validation, code, message);
public static Error Validation(string field, string code, string message) =>
new(ErrorKind.Validation, code, message) { Details = new Dictionary<string, string[]> { [field] = [message] } };
public static Error NotFound(string code, string message) => new(ErrorKind.NotFound, code, message);
public static Error Forbidden(string code, string message) => new(ErrorKind.Forbidden, code, message);
public static Error Conflict(string code, string message) => new(ErrorKind.Conflict, code, message);
public static Error Unauthorized(string code, string message) => new(ErrorKind.Unauthorized, code, message);
}ErrorKindмає п’ять значень, і кожне з них API відображає на один HTTP-статус у темі 12:Validation→ 400,Unauthorized→ 401,Forbidden→ 403,NotFound→ 404,Conflict→ 409.Error– цеrecordіз первинним конструктором: незмінний, порівнюється за значенням, гарно виводиться черезToString()(зручно в повідомленнях про збій тестів).Details– властивість лише зinit: її можна задати в ініціалізаторі об’єкта або у виразіwithі ніколи не змінити потім.- Статичні фабричні методи на кшталт
Error.NotFound(code, message)роблять код схожим на правило:return Error.Conflict("handle_taken", "..."). ПеревантаженняValidation(field, code, message)ще й заповнюєDetailsдля одного поля:[field] = [message]використовує ініціалізатор словника та вираз колекції.
Крок 3. Результат
Навіщо. Результат має бути дешевим (сервіси повертають їх тисячами), таким, що його неможливо прочитати хибно (жодного «значення null, але й помилки немає»), і приємним у записі: сервіс має вміти зробити return chat; або return ChatErrors.NotFound;, не обгортаючи нічого вручну.
Що зробити.
cs
using System.Diagnostics.CodeAnalysis;
namespace Chatex.Core.Common;
/// <summary>Outcome of an operation that returns no value: success, or an expected <see cref="Common.Error"/>.</summary>
public readonly struct Result
{
private Result(Error error) => Error = error;
public Error? Error { get; }
[MemberNotNullWhen(false, nameof(Error))]
public bool IsSuccess => Error is null;
public static Result Success => default;
public static implicit operator Result(Error error) => new(error);
public TOut Match<TOut>(Func<TOut> onSuccess, Func<Error, TOut> onFailure) =>
IsSuccess ? onSuccess() : onFailure(Error);
}
/// <summary>Outcome of an operation: a value, or an expected <see cref="Common.Error"/>. Bugs are still exceptions.</summary>
public readonly struct Result<T>
{
private readonly T? _value;
private Result(T value)
{
_value = value;
Error = null;
}
private Result(Error error)
{
_value = default;
Error = error;
}
public Error? Error { get; }
[MemberNotNullWhen(false, nameof(Error))]
public bool IsSuccess => Error is null;
public T Value => IsSuccess
? _value!
: throw new InvalidOperationException($"Result has no value; it failed with '{Error.Code}'.");
public static Result<T> Success(T value) => new(value);
public static implicit operator Result<T>(T value) => new(value);
public static implicit operator Result<T>(Error error) => new(error);
public TOut Match<TOut>(Func<T, TOut> onSuccess, Func<Error, TOut> onFailure) =>
IsSuccess ? onSuccess(_value!) : onFailure(Error);
}Тип невеликий, але майже кожен рядок у ньому – свідомий вибір:
readonly struct– тип значення, тож повернення результату нічого не виділяє в купі;readonlyгарантує, що після створення він не змінюється.- Закриті конструктори – створити результат можна лише як успіх або як помилку; третього стану немає.
IsSuccess => Error is null– успіх – це просто «немає помилки». Томуdefault(Result)– це успіх, його й повертаєResult.Success.[MemberNotNullWhen(false, nameof(Error))]повідомляє аналіз nullable компілятора: колиIsSuccessдорівнюєfalse,Errorне єnull. Післяif (!result.IsSuccess) return result.Error;попередження немає, і!не потрібен.- Неявні перетворення з
Tі зErrorдозволяють методу з типом результатуResult<ChatDto>просто написатиreturn dto;абоreturn ChatErrors.NotFound;. Обгортання виконують оператори перетворення. Valueкидає виняток у разі збою. Читання значення невдалого результату – вада викликача, тож тут виняток доречний. Повідомлення називає код помилки, і таку ваду легко знайти.Matchприймає дві функції – одну для успіху, одну для збою – і повертає те, що вони повертають: спосіб обробити обидва випадки в одному виразі. Сервіси Chatex здебільшого використовують звичайні перевіркиif (!result.IsSuccess); програма в «пісочниці» наприкінці цієї теми використовуєMatch.
Типи результатів в інших мовах
Ідея походить із функціональних мов: Result<T, E> у Rust, Either у Haskell і Scala. У .NET немає вбудованого типу результату, тому проєкти пишуть власний (як тут) або беруть бібліотеку. .editorconfig із теми 2 вимикає для цього самого файлу два правила аналізатора: CA1000 (статичні члени узагальненого типу) і CA1716 (Error – ключове слово Visual Basic).
Крок 4. Помилки, спільні для кількох функцій
Що зробити. Помилки, що належать одній функції, живуть разом із нею (ChatErrors, AuthErrors, …). Дві помилки спільні для кількох сервісів:
cs
namespace Chatex.Core.Common;
public static class CommonErrors
{
public static Error QueryTooShort { get; } =
Error.Validation("query", "query_too_short", "Type at least 2 characters to search.");
public static Error AvatarNotFound { get; } = Error.NotFound("avatar_not_found", "There is no avatar.");
}Ці помилки – статичні властивості з ініціалізатором ({ get; } = ...): створюються один раз і використовуються вічно. Оскільки Error – незмінний запис, спільне використання одного екземпляра безпечне.
Перевірка
powershell
dotnet buildЗбірка проходить без жодного попередження. У Chatex.Core досі немає власного пакета; Result і Error використовують лише базову бібліотеку.