Українська
Корінь композиції
Крок 1. Пакети й налаштування
Навіщо. Корінь композиції (composition root) – єдине місце, де збирають увесь застосунок: реєструють сервіси, читають налаштування, упорядковують проміжне програмне забезпечення (middleware), зіставляють кінцеві точки. У Chatex це Program.cs плюс AddApi. Перш ніж його писати, веб-проєкту потрібні три пакети та налаштування для розробки.
Що зробити.
powershell
dotnet add Source/Chatex.Api package Microsoft.AspNetCore.Authentication.JwtBearerpowershell
dotnet add Source/Chatex.Api package Microsoft.AspNetCore.OpenApipowershell
dotnet add Source/Chatex.Api package Scalar.AspNetCorexml
<Project Sdk="Microsoft.NET.Sdk.Web">
<ItemGroup>
<ProjectReference Include="..\Chatex.Core\Chatex.Core.csproj" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" />
<PackageReference Include="Microsoft.AspNetCore.OpenApi" />
<PackageReference Include="Scalar.AspNetCore" />
</ItemGroup>
</Project>- JwtBearer перевіряє токени доступу в кожному запиті.
- OpenApi генерує з коду документ OpenAPI – машиночитний опис кожної кінцевої точки.
- Scalar показує цей документ як інтерактивний довідник, де можна надсилати запити.
Налаштування, які читають нижчі рівні (теми 5, 7, 8), потрапляють у файл налаштувань для розробки; шаблон створив обидва файли в темі 2. Замініть їх:
json
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning",
"Microsoft.EntityFrameworkCore": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}json
{
"ConnectionStrings": {
"Chatex": "Host=localhost;Port=5432;Database=chatex;Username=postgres;Password=postgres"
},
"Jwt": {
"Issuer": "chatex-dev",
"Audience": "chatex-dev",
"SigningKey": "dev-only-signing-key-change-me-in-production-0123456789"
},
"Storage": {
"RootPath": "../../.uploads"
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
}
}ConnectionStrings:Chatexуказує на контейнер PostgreSQL із теми 2.Jwt: видавець, одержувач і ключ підпису щонайменше з 32 символів. Цей ключ лише для розробки; робочий сервер читає свій ключ зі змінної середовища (тема 23), тож справжній ключ ніколи не потрапляє до репозиторію.Storage:RootPathвідраховується від папки проєкту API:../../.uploads– це папка.uploadsу корені репозиторію, яку.gitignoreвиключає.appsettings.jsonдіє всюди й не дає журналу SQL від EF Core шуміти;appsettings.Development.jsonнакладається поверх нього, колиASPNETCORE_ENVIRONMENTдорівнюєDevelopment(профіль запуску з теми 2 це задає).
Крок 2. Схема безпеки OpenAPI
Навіщо. Scalar має знати, що більшість кінцевих точок потребують токена Bearer, щоб показати поле «Authorize» й надсилати токен. Документи OpenAPI коригують трансформерами: один оголошує схему Bearer для документа, другий позначає кожну операцію, що вимагає авторизації.
Що зробити.
cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi;
namespace Chatex.Api.Infrastructure;
/// <summary>
/// Declares the JWT bearer scheme in the OpenAPI document and marks every operation that needs a token,
/// so Scalar can send the access token.
/// </summary>
internal sealed class BearerSecuritySchemeTransformer : IOpenApiDocumentTransformer, IOpenApiOperationTransformer
{
/// <summary>The name of the bearer scheme in the OpenAPI document.</summary>
public const string SchemeName = "Bearer";
public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
{
document.Components ??= new OpenApiComponents();
document.Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>();
document.Components.SecuritySchemes[SchemeName] = new OpenApiSecurityScheme
{
Type = SecuritySchemeType.Http,
Scheme = "bearer",
BearerFormat = "JWT",
In = ParameterLocation.Header,
Description = "The access token returned by /api/auth/login, /register or /refresh.",
};
return Task.CompletedTask;
}
public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken)
{
var metadata = context.Description.ActionDescriptor.EndpointMetadata;
if (metadata.OfType<IAllowAnonymous>().Any() || !metadata.OfType<IAuthorizeData>().Any())
{
return Task.CompletedTask;
}
operation.Security ??= [];
operation.Security.Add(new OpenApiSecurityRequirement
{
[new OpenApiSecuritySchemeReference(SchemeName, context.Document)] = [],
});
return Task.CompletedTask;
}
}Трансформер операцій дивиться на метадані кінцевої точки: кінцеві точки з AllowAnonymous (вхід, реєстрація) або без жодної вимоги авторизації не отримують вимоги безпеки.
Крок 3. AddApi
Навіщо. Як і кожен нижчий рівень, веб-рівень реєструє свої сервіси в одному методі розширення.
Що зробити. Створіть DependencyInjection.cs у корені Chatex.Api:
cs
using System.Text.Json;
using System.Text.Json.Serialization;
using Chatex.Api.Infrastructure;
using Chatex.Core.Auth;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Extensions.Options;
using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;
namespace Chatex.Api;
public static class DependencyInjection
{
public static IServiceCollection AddApi(this IServiceCollection services, IConfiguration configuration)
{
services.ConfigureHttpJsonOptions(o =>
o.SerializerOptions.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase)));
services.AddProblemDetails();
// Malformed bodies answer 400 (turned into problem details by UseStatusCodePages) in every environment,
// instead of throwing to the exception handler in Development.
services.Configure<RouteHandlerOptions>(o => o.ThrowOnBadRequest = false);
services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme).AddJwtBearer();
services.AddOptions<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme)
.Configure<IOptions<JwtOptions>>((bearer, jwtOptions) =>
{
var jwt = jwtOptions.Value;
bearer.MapInboundClaims = false;
bearer.TokenValidationParameters = new TokenValidationParameters
{
ValidIssuer = jwt.Issuer,
ValidAudience = jwt.Audience,
IssuerSigningKey = jwt.CreateSigningKey(),
ValidAlgorithms = [SecurityAlgorithms.HmacSha256],
NameClaimType = JwtRegisteredClaimNames.UniqueName,
ClockSkew = TimeSpan.FromSeconds(30),
};
});
services.AddAuthorization();
services.AddOpenApi(o =>
{
o.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
o.AddOperationTransformer<BearerSecuritySchemeTransformer>();
});
return services;
}
}ConfigureHttpJsonOptionsізJsonStringEnumConverter(JsonNamingPolicy.CamelCase)записує перелічення як рядки в camelCase:"type": "group","myRole": "owner". Числа були б для клієнта беззмістовні й ламалися б, коли перелічення змінюється.AddProblemDetailsробить Problem Details і власні помилки фреймворку (404 для невідомого маршруту, 500 для необробленого винятку).ThrowOnBadRequest = false: тіло JSON із помилками синтаксису в кожному середовищі отримує відповідь400замість винятку в Development.- JWT Bearer:
AddAuthentication(...).AddJwtBearer()реєструє схему; параметри налаштовано зJwtOptionsтеми 8 черезAddOptions<JwtBearerOptions>().Configure<IOptions<JwtOptions>>(...), тож перевірка використовує саме ті налаштування, якими підписано токен:MapInboundClaims = falseзберігає імена тверджень токена (sub,unique_name) замість перетворення на довгі URI від Microsoft;ValidIssuer,ValidAudience,IssuerSigningKeyберуться з тих самих налаштувань, аCreateSigningKey– той самий, що в сервісі токенів;ValidAlgorithms = [HmacSha256]відхиляє токени, підписані будь-яким іншим алгоритмом;ClockSkewу 30 секунд допускає невелику розбіжність годинників між серверами (типово – 5 хвилин).
AddOpenApiіз двома трансформерами.
Крок 4. Program.cs
Що зробити. Замініть Program.cs шаблону:
cs
using Chatex.Api;
using Chatex.Api.Endpoints;
using Chatex.Api.Infrastructure;
using Chatex.Core;
using Scalar.AspNetCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddApi(builder.Configuration);
builder.Services.AddCore(builder.Configuration);
var app = builder.Build();
app.UseExceptionHandler();
app.UseStatusCodePages();
app.UseAuthentication();
app.UseAuthorization();
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
app.MapScalarApiReference(o => o.AddPreferredSecuritySchemes(BearerSecuritySchemeTransformer.SchemeName));
}
var api = app.MapGroup("/api").RequireAuthorization();
api.MapAuthEndpoints();
api.MapProfileEndpoints();
api.MapUserEndpoints();
api.MapChatEndpoints();
api.MapMessageEndpoints();
app.Run();
/// <summary>Visible to <c>WebApplicationFactory</c> in the Api tests.</summary>
public partial class Program;- Інструкції верхнього рівня: файл і є програмою;
builderбудує вузол (host),app– запущений застосунок. AddApi, потімAddCore: порядок має значення, починаючи з теми 14 (сповіщувач SignalR треба зареєструвати першим); дотримуйтеся його від початку.- Конвеєр проміжного програмного забезпечення виконується в записаному порядку для кожного запиту:
UseExceptionHandlerперетворює необроблені винятки на відповідь 500 Problem Details без трасування стека;UseStatusCodePagesнадає порожнім відповідям із помилкою (наприклад, 401 від проміжного ПЗ автентифікації) тіло Problem Details;UseAuthenticationчитає токен Bearer і створюєHttpContext.User;UseAuthorizationзастосовуєRequireAuthorization.
- OpenAPI і Scalar лише в Development: робочий сервер не рекламує поверхню свого API.
MapGroup("/api").RequireAuthorization()– кожна кінцева точка під/apiвимагає чинного токена, якщо не вказаноAllowAnonymous. Безпека за замовчуванням: нова кінцева точка, яку хтось забув захистити, усе одно захищена.public partial class Program;робить згенерований класProgramвидимим дляWebApplicationFactory<Program>тестового проєкту (Тестування через HTTP).
Крок 5. Запустіть API
Що зробити. Запустіть базу даних і застосуйте міграції, потім запустіть API:
powershell
./Run.ps1 dbpowershell
./Run.ps1 apiПеревірка
Відкрийте http://localhost:5214/scalar. Довідник перелічує групи Auth, Profile, Users, Chats і Messages.
Відкрийте Auth → Register і надішліть
json{ "userName": "alice", "email": "[email protected]", "password": "Passw0rd!", "displayName": "Alice" }Відповідь –
200зaccessToken,accessTokenExpiresAtіuser, а також заголовокSet-Cookieзі значеннямchatex_refresh=…; path=/api/auth; secure; samesite=strict; httponly.Скопіюйте
accessToken, вставте його в поле автентифікації Scalar і надішліть Profile → GetMyProfile:200з вашим профілем. Без токена:401із тілом Problem Details.Надішліть Auth → Login з хибним паролем:
401іjson{ "title": "Unauthorized", "status": 401, "detail": "The user name, email or password is wrong.", "code": "invalid_credentials", … }
В еталонному репозиторії є також файл прикладів запитів для Visual Studio, Rider і VS Code (з розширенням REST Client). Скопіюйте його в проєкт API:
powershell
Invoke-WebRequest https://raw.githubusercontent.com/musicvano/Chatex/27c83c6932b902c8d8dcef01e30a3dd32c5be05f/Source/Chatex.Api/Chatex.Api.http -OutFile Source/Chatex.Api/Chatex.Api.httphttp
### Sample requests for the Chatex API.
### Run the API with `dotnet run --project Source/Chatex.Api --launch-profile http`,
### then send "Register" (or "Login"); later requests reuse its access token.
@host = http://localhost:5214
### Register
# @name register
POST {{host}}/api/auth/register
Content-Type: application/json
# ...
### My profile
GET {{host}}/api/me
Authorization: Bearer {{register.response.body.accessToken}}
# ...# @name register дає запиту ім’я, а наступний запит використовує значення з його відповіді через вираз у подвійних фігурних дужках register.response.body.accessToken, який видно у лістингу. Спершу виконайте «Register», потім решту. Запит завантаження наприкінці працює з теми 13.