Как освоить веб-API .NET 8: от настройки до безопасности — 50 лучших советов

Изучите каждый шаг создания надежного API — от первоначальной настройки проекта с использованием .NET CLI до настройки промежуточного программного обеспечения, контроллеров и служб. Ознакомьтесь с лучшими практиками внедрения зависимостей, асинхронных действий и обработки исключений для создания масштабируемых и эффективных веб-приложений. 1. Настройка проекта веб-API .NET 8. Концепция Используйте .NET CLI для создания нового проекта веб-API. Это устанавливает базовую структуру проекта, включая Program.cs для запуска и контроллер WeatherForecast в качестве примера. Пример кода dotnet new webapi -n MyWebApi 2. Program.cs — минимальная конфигурация API Концепция .NET 8 продолжает тенденцию к минимизации API, позволяя настраивать службы и конечные точки упрощенным и кратким образом непосредственно в файле Program.cs. Пример кода var builder = WebApplication.CreateBuilder(args); var app = builder.Build(); app.MapGet("/", () => "Hello, World!"); app.Run(); 3. Определение контроллера Концепция Контроллеры обрабатывают входящие HTTP-запросы и отвечают клиенту. Они определяются путем наследования от ControllerBase и аннотации с помощью [ApiController]. Пример кода [ApiController] [Route("[controller]")] public class MyController : ControllerBase { [HttpGet] public IActionResult Get() => Ok("Hello from MyController"); } 4. Внедрение зависимостей в контроллеры Концепция Встроенная функция внедрения зависимостей (DI) .NET Core упрощает управление зависимостями. Вы можете внедрять сервисы в свои контроллеры через их конструкторы. Пример кода public class MyService { public string GetMessage() => "Injected message"; } public class MyController : ControllerBase { private readonly MyService _myService; public MyController(MyService myService) { _myService = myService; } [HttpGet] public IActionResult Get() => Ok(_myService.GetMessage()); } 5. Настройка служб Концепция Службы (такие как контексты базы данных, пользовательские службы и т. д.) настраиваются в файле Program.cs, что делает их доступными для внедрения зависимостей во всем приложении. Пример кода builder.Services.AddScoped (); 6. Конфигурация на основе среды Концепция .NET поддерживает файлы конфигурации, зависящие от среды (appsettings.json, appsettings.Development.json и т. д.), что позволяет использовать различные настройки в зависимости от среды приложения. Пример кода // appsettings.Development.json { "Logging": { "LogLevel": { "Default": "Debug" } } } 7. Промежуточное ПО Концепция Компоненты промежуточного программного обеспечения образуют конвейер, обрабатывающий запросы и ответы. Можно создать собственное промежуточное программное обеспечение для решения сквозных задач, таких как ведение журнала или обработка ошибок. Пример кода app.Use(async (context, next) => { // Custom logic before passing to the next middleware await next(); // Custom logic after executing the next middleware }); 8. Маршрутизация Концепция Маршрутизация в веб-API .NET осуществляется посредством маршрутизации атрибутов на контроллерах и методах действий. Это позволяет сопоставлять URL-адреса непосредственно с действиями контроллера. Пример кода [HttpGet("myaction/{id}")] public IActionResult GetAction(int id) => Ok($"Action with ID = {id}"); 9. Привязка модели Концепция Привязка модели автоматически сопоставляет данные из HTTP-запросов с параметрами метода действия. Он поддерживает сложные типы, включая тела JSON и параметры строки запроса. Пример кода public class MyModel { public int Id { get; set; } public string Name { get; set; } } [HttpPost] public IActionResult PostAction([FromBody] MyModel model) => Ok(model); 10. Проверка данных Концепция Аннотации данных можно использовать для проверки данных модели. Атрибут [ApiController] автоматически обеспечивает проверку, отвечая 400, если модель недействительна. Пример кода public class MyModel { [Required] public int Id { get; set; } [StringLength(100)] public string Name { get; set; } } 11. Асинхронные действия Концепция Асинхронные действия улучшают масштабируемость, освобождая потоки во время ожидания завершения операций ввода-вывода. Используйте ключевое слово async и верните Task или Task . Пример кода [HttpGet("{id}")] public async Task GetAsync(int id) { var result = await _service.GetByIdAsync(id); return Ok(result); } 12. Глобальная обработка исключений Концепция Глобальная обработка исключений позволяет централизованно обрабатывать ошибки, вести журналы и стандартизировать ответы API на необработанные исключения. Пример кода app.UseExceptionHandler(a => a.Run(async context => { var exceptionHandlerPathFeature = context.Features.Get (); var exception = exceptionHandlerPathFeature.Error; // Log the exception, generate a custom response, etc. context.Response.StatusCode = 500; await context.Response.WriteAsJsonAsync(new { Error = "An unexpected error occurred" }); })); 13. Управление версиями API Концепция Управление версиями API помогает управлять изменениями API с течением времени. Платформа .NET поддерживает управление версиями посредством строки запроса, URL-адреса или заголовка запроса. Пример кода builder.Services.AddApiVersioning(options => { options.AssumeDefaultVersionWhenUnspecified = true; options.DefaultApiVersion = new ApiVersion(1, 0); options.ReportApiVersions = true; }); 14. Согласование содержания Концепция Согласование контента позволяет API обслуживать различные форматы ответа на основе заголовка Accept в запросе, обеспечивая поддержку таких форматов, как JSON, XML и т. д. Пример кода builder.Services.AddControllers() .AddXmlDataContractSerializerFormatters(); 15. Пользовательские настройки сериализации JSON Концепция Настройте форматирование ответа JSON, например именование в CamelCase или игнорирование нулевых значений, настроив параметры сериализатора JSON. Пример кода builder.Services.AddControllers() .AddJsonOptions(options => { options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase; options.JsonSerializerOptions.IgnoreNullValues = true; }); 16. Настройка CORS Концепция Совместное использование ресурсов между источниками (CORS) позволяет вызывать ваш API из веб-приложений, размещенных в разных доменах. Настройте политику CORS в соответствии с вашими требованиями. Пример кода builder.Services.AddCors(options => { options.AddPolicy("AllowSpecificOrigin", builder => builder.WithOrigins("http://example.com")); }); app.UseCors("AllowSpecificOrigin"); 17. Аутентификация Концепция Защитите свой API, включив аутентификацию, которая проверяет личность пользователей или служб, отправляющих запросы. Пример кода builder.Services.AddAuthentication("Bearer") .AddJwtBearer(options => { options.Authority = "https://your-auth-server"; options.Audience = "your-api"; }); 18. Авторизация Концепция После аутентификации авторизация определяет, имеет ли аутентифицированный пользователь разрешение на выполнение действия или доступ к ресурсу. Пример кода [Authorize] public class SecureController : ControllerBase { // Action methods here } 19. Интеграция Swagger/OpenAPI Концепция Swagger (OpenAPI) предоставляет интерактивную документацию для вашего API, что позволяет разработчикам легко понимать и использовать его. Пример кода builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(); app.UseSwagger(); app.UseSwaggerUI(); 20. Ведение журнала Концепция .NET Core предоставляет встроенную платформу ведения журналов, которая может регистрировать сообщения на различных выходах (консоль, окно отладки, внешние службы и т. д.). Пример кода logger.LogInformation("This is an informational message"); app.Use(async (context, next) => { logger.LogError("This is an error message before the next middleware"); await next.Invoke(); // Log after calling the next middleware }); 21. Использование ядра Entity Framework Концепция Entity Framework Core — это ORM, используемый для доступа к данным в приложениях .NET. Он позволяет запрашивать данные и манипулировать ими с использованием строго типизированных объектов. Пример кода public class MyDbContext : DbContext { public MyDbContext(DbContextOptions options) : base(options) {} public DbSet MyModels { get; set; } } 22. Миграции в Entity Framework Core Концепция Миграции позволяют вам применять контроль версий к схеме вашей базы данных, отслеживая изменения в ваших моделях данных. Пример кода dotnet ef migrations add InitialCreate dotnet ef database update 23. Шаблон репозитория Концепция Шаблон «Репозиторий» абстрагирует уровень данных, делая ваше приложение более модульным и простым в обслуживании. Пример кода public interface IRepository { Task > GetAllAsync(); Task GetByIdAsync(int id); // Other methods... } public class MyRepository : IRepository where T : class { private readonly MyDbContext _context; public MyRepository(MyDbContext context) { _context = context; } // Implement methods... } 24. Модульное тестирование Концепция Модульное тестирование обеспечивает правильную работу вашего веб-API путем изолированного тестирования отдельных единиц кода. Пример кода public class MyControllerTests { [Fact] public async Task Get_ReturnsExpectedValue() { // Arrange var serviceMock = new Mock (); serviceMock.Setup(service => service.GetAsync()).ReturnsAsync("test"); var controller = new MyController(serviceMock.Object); // Act var result = await controller.Get(); // Assert Assert.Equal("test", result.Value); } } 25. Интеграция с фронтендом Концепция Веб-API .NET может служить серверной частью внешнего приложения, предоставляя службы RESTful. Пример кода fetch('https://localhost:5001/mycontroller') .then(response => response.json()) .then(data => console.log(data)); 26. Проверка работоспособности Концепция Проверки работоспособности позволяют отслеживать состояние вашего приложения и его зависимостей, что полезно для архитектур микросервисов. Пример кода builder.Services.AddHealthChecks(); app.MapHealthChecks("/health"); 27. Использование SignalR для связи в реальном времени Концепция SignalR обеспечивает веб-функциональность в режиме реального времени, позволяя серверному коду отправлять асинхронные уведомления клиентским веб-приложениям. Пример кода public class MyHub : Hub { public async Task SendMessage(string user, string message) { await Clients.All.SendAsync("ReceiveMessage", user, message); } } 28. Настройка кэширования ответов Концепция Кэширование ответов уменьшает количество запросов, которые сервер должен обрабатывать, сохраняя копии ранее запрошенных ресурсов. Пример кода [HttpGet("{id}")] [ResponseCache(Duration = 60)] public IActionResult GetById(int id) { // Retrieve and return your resource } 29. Статические файлы Концепция Обслуживание статических файлов (HTML, CSS, JavaScript и т. д.) необходимо для поддержки интерфейсных приложений с помощью веб-API .NET. Пример кода app.UseStaticFiles(); // Enable static file serving 30. Расширенная конфигурация и шаблон опций Концепция Шаблон параметров использует классы для представления групп связанных настроек. Используя IOptions , вы можете получить доступ к этим настройкам в любом месте вашего приложения. Пример кода public class MySettings { public string Setting1 { get; set; } // Other settings } builder.Services.Configure (builder.Configuration.GetSection("MySettings")); public class MyService { private readonly MySettings _settings; public MyService(IOptions settings) { _settings = settings.Value; } // Use _settings.Setting1 } 31. Пользовательское промежуточное ПО Концепция Промежуточное программное обеспечение — это программное обеспечение, встроенное в конвейер приложений для обработки запросов и ответов. Для выполнения конкретных задач можно создать собственное промежуточное программное обеспечение. Пример кода public class MyCustomMiddleware { private readonly RequestDelegate _next; public MyCustomMiddleware(RequestDelegate next) { _next = next; } public async Task Invoke(HttpContext httpContext) { // Pre-processing logic here await _next(httpContext); // Call the next middleware in the pipeline // Post-processing logic here } } // Extension method for easy middleware registration public static class MyCustomMiddlewareExtensions { public static IApplicationBuilder UseMyCustomMiddleware(this IApplicationBuilder builder) { return builder.UseMiddleware (); } } 32. Ограничение скорости Концепция Ограничение скорости защищает ваш API от чрезмерного использования, ограничивая частоту, с которой пользователь может делать запросы в течение определенного периода времени. Пример кода // Assume using a third-party library like AspNetCoreRateLimit builder.Services.AddInMemoryRateLimiting(); builder.Services.Configure (options => { options.GeneralRules = new List { new RateLimitRule { Endpoint = "*", Limit = 100, Period = "1h" } }; }); 33. Аутентификация ключей API Концепция Ключи API — это простой способ аутентификации и авторизации вызовов API. Они передаются от клиента к серверу либо в строке запроса, либо в заголовке. Пример кода public class ApiKeyMiddleware { private readonly RequestDelegate _next; private const string APIKEYNAME = "x-api-key"; public ApiKeyMiddleware(RequestDelegate next) { _next = next; } public async Task Invoke(HttpContext context) { if (!context.Request.Headers.TryGetValue(APIKEYNAME, out var extractedApiKey)) { context.Response.StatusCode = 401; await context.Response.WriteAsync("API Key was not provided."); return; } // Validate the extracted API Key here... await _next(context); } } 34. Кэширование вывода Концепция Кэширование вывода позволяет хранить ответ на запрос. Последующие запросы могут обслуживаться из кеша, что значительно повышает производительность. Пример кода [HttpGet] [ResponseCache(Duration = 120, Location = ResponseCacheLocation.Client, NoStore = false)] public IActionResult Get() { // Your logic here } 35. Фоновые задачи Концепция Фоновые задачи позволяют выполнять операции в фоновом режиме независимо от запросов пользователя, например отправку электронных писем или обработку длительных заданий. Пример кода public class MyBackgroundService : BackgroundService { protected override async Task ExecuteAsync(CancellationToken stoppingToken) { while (!stoppingToken.IsCancellationRequested) { // Your background task logic here await Task.Delay(TimeSpan.FromHours(1), stoppingToken); } } } 36. Вебсокеты Концепция WebSockets обеспечивают полнодуплексный канал связи через одно долговременное соединение, идеально подходящее для приложений реального времени. Пример кода app.UseWebSockets(); app.Use(async (context, next) => { if (context.WebSockets.IsWebSocketRequest) { WebSocket webSocket = await context.WebSockets.AcceptWebSocketAsync(); // Handle the WebSocket request here } else { await next(); } }); 37. Запросить локализацию Концепция Локализация запроса позволяет локализовать контент для разных культур и языков на основе информации запроса. Пример кода var supportedCultures = new[] { "en-US", "fr-FR" }; var localizationOptions = new RequestLocalizationOptions() .SetDefaultCulture(supportedCultures[0]) .AddSupportedCultures(supportedCultures) .AddSupportedUICultures(supportedCultures); app.UseRequestLocalization(localizationOptions); 38. Интеграция с GraphQL Концепция GraphQL — это язык запросов для API. Интеграция веб-API .NET с GraphQL позволяет более эффективно извлекать данные. Пример кода // Assume using a library like HotChocolate builder.Services .AddGraphQLServer() .AddQueryType (); app.MapGraphQL(); 39. Мониторинг и телеметрия Концепция Мониторинг и телеметрия включают сбор, анализ и обработку данных о производительности и использовании вашего приложения. Пример кода // Assume using Application Insights builder.Services.AddApplicationInsightsTelemetry("YOUR_INSTRUMENTATION_KEY"); 40. Концентраторы SignalR и связь в реальном времени Концепция SignalR — это библиотека, которая упрощает добавление веб-функций в реальном времени в приложения. Веб-функциональность в режиме реального времени — это возможность мгновенно передавать контент серверному коду подключенным клиентам, не требуя от сервера ждать, пока клиент запросит новые данные. SignalR идеально подходит для разработки приложений чата, информационных панелей реального времени и других интерактивных веб-приложений. Пример кода public class ChatHub : Hub { public async Task SendMessage(string user, string message) { // Call the broadcastMessage method to update clients. await Clients.All.SendAsync("broadcastMessage", user, message); } } // Startup or Program.cs app.MapHub ("/chathub"); Интеграция в Program.cs: public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { // Other configurations... app.UseEndpoints(endpoints => { endpoints.MapHub ("/chathub"); }); } 41. Расширенное ядро Entity Framework — отношения Концепция Entity Framework Core позволяет отображать сложные отношения между сущностями, например «один-к-одному», «один-ко-многим» и «многие-ко-многим». Пример кода public class Author { public int AuthorId { get; set; } public string Name { get; set; } public ICollection Books { get; set; } } public class Book { public int BookId { get; set; } public string Title { get; set; } public int AuthorId { get; set; } public Author Author { get; set; } } 42. Пользовательские атрибуты проверки Концепция Пользовательские атрибуты проверки позволяют определить логику проверки для моделей данных, расширяя встроенные атрибуты проверки. Пример кода public class MyCustomValidationAttribute : ValidationAttribute { protected override ValidationResult IsValid(object value, ValidationContext validationContext) { // Your custom validation logic here if (value is int intValue && intValue > 0) { return ValidationResult.Success; } return new ValidationResult("Value must be positive"); } } public class MyModel { [MyCustomValidationAttribute] public int MyProperty { get; set; } } 43. Сценарии расширенной конфигурации Концепция Шаблон параметров .NET поддерживает сложные сценарии настройки, включая вложенные объекты, списки и проверку. Пример кода public class MyOptions { public MyNestedOptions Nested { get; set; } public List Items { get; set; } } public class MyNestedOptions { public string Key { get; set; } } // In Program.cs or Startup.cs builder.Services.Configure (builder.Configuration.GetSection("MyOptions")); 44. Мониторинг производительности и профилирование Концепция Мониторинг и профилирование приложения могут выявить узкие места и неэффективность, необходимые для оптимизации производительности. Пример кода app.UseMiniProfiler(); 45. Документация API с Swagger и XML-комментариями Концепция Улучшите документацию по API, интегрировав XML-комментарии в пользовательский интерфейс Swagger, предоставляя более широкие возможности разработчикам, использующим ваш API. Пример кода builder.Services.AddSwaggerGen(c => { var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); c.IncludeXmlComments(xmlPath); }); 46. Глобализация и локализация Концепция Глобализация и локализация позволяют вашему приложению поддерживать несколько языков и культур, что делает его доступным для глобальной аудитории. Пример кода builder.Services.AddLocalization(options => options.ResourcesPath = "Resources"); app.UseRequestLocalization(app.Services.GetRequiredService >().Value); 47. Заголовки безопасности Концепция Повышение безопасности вашего веб-приложения путем добавления различных заголовков HTTP может защитить от распространенных атак и уязвимостей. Пример кода app.UseHsts(); app.UseXContentTypeOptions(); app.UseReferrerPolicy(opts => opts.NoReferrer()); app.UseXXssProtection(options => options.EnabledWithBlockMode()); app.UseXfo(options => options.Deny()); 48. Флаги функций Концепция Флаги функций позволяют включать и отключать функции вашего приложения без развертывания нового кода, что упрощает тестирование и развертывание. Пример кода // Using a library like Microsoft.FeatureManagement builder.Services.AddFeatureManagement(); 49. Интеграция Blazor Концепция Blazor позволяет создавать интерактивные веб-интерфейсы, используя C# вместо JavaScript. Интеграция Blazor с веб-API обеспечивает удобство комплексной разработки. Пример кода // In a Blazor Server app @code { private IEnumerable forecasts; protected override async Task OnInitializedAsync() { forecasts = await Http.GetFromJsonAsync ("WeatherForecast"); } } 50. Расширенное промежуточное программное обеспечение для сжатия ответов Концепция Сжатие ответов может уменьшить размер ответов API, сокращая время загрузки для клиентов в медленных сетях. Пример кода builder.Services.AddResponseCompression(options => { options.Providers.Add (); options.EnableForHttps = true; }); app.UseResponseCompression(); Программирование на C#🚀 Благодарим вас за то, что вы являетесь частью сообщества C#! Прежде чем ты уйдешь: Если вы зашли так далеко, пожалуйста, выразите свою признательность аплодисментами и подпишитесь на автора! 👏️️ Следуйте за нами: | | | | | X LinkedIn Dev.to Хашнод Информационный бюллетень Тамблер Посетите другие наши платформы: | | | | GitHub Инстаграм Тикток Кора Daily.dev Также опубликовано здесь