Українська
Від результатів до HTTP
Крок 1. Minimal API
Навіщо. ASP.NET Core пропонує два стилі кінцевих точок HTTP: контролери (класи з методами дій і атрибутами) та Minimal API (маршрут, зіставлений безпосередньо з делегатом). Chatex використовує Minimal API: кінцева точка – це маршрут плюс невеликий статичний метод, параметри якого ASP.NET Core заповнює з маршруту, рядка запиту, тіла JSON, сервісів і самого запиту:
cs
group.MapGet("/{id:guid}", GetAsync);
static async Task<Results<Ok<ChatDto>, ProblemHttpResult>> GetAsync(
Guid id, ClaimsPrincipal user, IChatService chats, CancellationToken cancellationToken) => ...id береться з маршруту, user – це користувач, що виконав вхід, chats розв’язується з упровадження залежностей, cancellationToken скасовується, коли клієнт розриває з’єднання. Оскільки всю роботу вже виконує бізнес-рівень, кожна кінцева точка займає один-два рядки: викликати сервіс і перетворити результат на HTTP. Обидва стилі вводить курс C# у темі REST API.
Крок 2. Коди стану та Problem Details
Навіщо. Кожна відмова API має виглядати для клієнта однаково, щоб застосунок Angular обробляв їх усі в одному місці. Для цього в HTTP є стандарт: Problem Details (RFC 9457) – тіло JSON з типом носія application/problem+json:
json
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
"title": "Conflict",
"status": 409,
"detail": "This public handle is already taken.",
"code": "handle_taken"
}status, title, detail і type стандартні; code – це розширення, що несе стабільний код помилки з теми 7. Помилка перевірки додає errors – словник імен полів і повідомлень.
Що зробити. Створіть у Chatex.Api папку Infrastructure:
cs
using Chatex.Core.Common;
using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Mvc;
namespace Chatex.Api.Infrastructure;
/// <summary>Turns business <see cref="Result"/>s into HTTP results; failures become RFC 9457 problem details.</summary>
internal static class ResultHttpExtensions
{
/// <summary>The problem details extension that carries <see cref="Error.Code"/>.</summary>
public const string CodeExtension = "code";
public static int ToStatusCode(this ErrorKind kind) => kind switch
{
ErrorKind.Validation => StatusCodes.Status400BadRequest,
ErrorKind.NotFound => StatusCodes.Status404NotFound,
ErrorKind.Forbidden => StatusCodes.Status403Forbidden,
ErrorKind.Conflict => StatusCodes.Status409Conflict,
ErrorKind.Unauthorized => StatusCodes.Status401Unauthorized,
_ => throw new ArgumentOutOfRangeException(nameof(kind), kind, null),
};
public static ProblemHttpResult ToProblem(this Error error)
{
ProblemDetails problem = error.Details is { Count: > 0 } details
? new HttpValidationProblemDetails(details.ToDictionary()) { Title = "One or more fields are invalid." }
: new ProblemDetails();
problem.Status = error.Kind.ToStatusCode();
problem.Detail = error.Message;
problem.Extensions[CodeExtension] = error.Code;
return TypedResults.Problem(problem);
}
public static Results<Ok<T>, ProblemHttpResult> ToOk<T>(this Result<T> result) =>
result.IsSuccess ? TypedResults.Ok(result.Value) : result.Error.ToProblem();
/// <param name="location">The new resource's URL, or null when it has no URL of its own.</param>
public static Results<Created<T>, ProblemHttpResult> ToCreated<T>(this Result<T> result, Func<T, string?> location) =>
result.IsSuccess ? TypedResults.Created(location(result.Value), result.Value) : result.Error.ToProblem();
public static Results<NoContent, ProblemHttpResult> ToNoContent(this Result result) =>
result.IsSuccess ? TypedResults.NoContent() : result.Error.ToProblem();
}ToStatusCodeзіставляє коженErrorKindз його кодом стану виразом switch; невідомий вид – це помилка в коді, і метод генерує виняток.ToProblemбудуєHttpValidationProblemDetails(зerrors), якщо в помилки є подробиці, і звичайнийProblemDetailsв іншому разі, а також додає розширенняcode.ToOk,ToCreated,ToNoContentперетворюютьResultна один із двох результатів. Тип, що повертається,Results<Ok<T>, ProblemHttpResult>– це типізоване об’єднання: кінцева точка точно оголошує, які відповіді може створити, а OpenAPI читає їх із сигнатури (крок 4 сторінки Корінь композиції).
Крок 3. Хто викликає і звідки
Навіщо. Майже кожній кінцевій точці потрібен ідентифікатор користувача, що виконав вхід. Це твердження (claim) sub токена доступу (тема 8); невеликий метод розширення читає його з ClaimsPrincipal, який створює проміжне програмне забезпечення автентифікації. Кінцеві точки автентифікації також записують браузер та IP-адресу нової сесії.
Що зробити.
cs
using System.Security.Claims;
using Microsoft.IdentityModel.JsonWebTokens;
namespace Chatex.Api.Infrastructure;
internal static class ClaimsPrincipalExtensions
{
/// <summary>The signed-in user's id from the access token's <c>sub</c> claim. Only call it on authorized endpoints.</summary>
public static Guid GetUserId(this ClaimsPrincipal user) =>
Guid.TryParse(user.FindFirstValue(JwtRegisteredClaimNames.Sub), out var id)
? id
: throw new InvalidOperationException("The request has no authenticated user id.");
}cs
using Chatex.Core.Auth;
namespace Chatex.Api.Infrastructure;
internal static class HttpContextExtensions
{
/// <summary>Where the request came from. The IP is the client's once forwarded headers are applied.</summary>
public static ClientInfo GetClientInfo(this HttpContext context)
{
var userAgent = context.Request.Headers.UserAgent.ToString();
return new ClientInfo(
string.IsNullOrEmpty(userAgent) ? null : userAgent,
context.Connection.RemoteIpAddress?.ToString());
}
}GetUserId генерує виняток, якщо чинного ідентифікатора немає: метод викликають лише на кінцевих точках, що вимагають авторизації, тож відсутній ідентифікатор означав би помилку в конфігурації, а не помилку клієнта.
Крок 4. Контракти API
Навіщо. Більшість тіл запитів – це команди бізнес-рівня (RegisterCommand, SendMessageCommand тощо), а більшість відповідей – його DTO. Кілька форм існують лише на боці HTTP: відповідь на вхід без токена оновлення (він іде в cookie) і малі тіла для одного значення, як-от { "userId": "…" }.
Що зробити. Створіть папку Contracts:
cs
using Chatex.Core.Auth;
using Chatex.Core.Users;
using Chatex.Data.Entities;
namespace Chatex.Api.Contracts;
/// <summary>
/// A signed-in session as the client sees it. The refresh token is not here: it travels in the
/// <c>chatex_refresh</c> HttpOnly cookie, which only <c>/api/auth</c> receives.
/// </summary>
public sealed record AuthResponse(string AccessToken, DateTimeOffset AccessTokenExpiresAt, MyProfileDto User)
{
public static AuthResponse From(AuthResult auth) => new(auth.AccessToken, auth.AccessTokenExpiresAt, auth.User);
}
public sealed record OpenDirectRequest(Guid UserId);
public sealed record AddMembersRequest(IReadOnlyList<Guid>? UserIds);
/// <param name="Added">How many of the users were not members yet.</param>
public sealed record AddMembersResponse(int Added);
public sealed record ChangeRoleRequest(ChatMemberRole Role);
public sealed record SetMutedRequest(bool Muted);
public sealed record MarkReadRequest(Guid MessageId);Навіщо запис (record) для одного значення? Тіло JSON завжди має бути об’єктом: у { "muted": true } згодом можна додати другу властивість, не зламавши клієнтів, а у «голого» true – ні.
Перевірка
dotnet build проходить успішно. Program.cs досі лишається шаблоном із теми 2; нові класи ще не використовуються.