VoluntasProgressus.APICore 2.2.2

VoluntasProgressus.APICore

Многоязычная документация для пакета API Core – централизованная обработка исключений и стандартизированные API-ответы. Includes full documentation in Russian, English, Deutsch, and 中文.

Русский / Russian

Описание

Этот пакет предоставляет механизм централизованной обработки исключений и формирования стандартизированных API-ответов:

• Ошибки возвращаются в формате RFC 7807 Problem Details (application/problem+json)
• Успешные ответы оборачиваются в унифицированный контейнер ApiResponse<T>
• Контроллер HealthController автоматически регистрируется при вызове services.AddApiCore() и доступен по маршруту /health для проверки состояния сервиса
• Поддерживается DI-контейнер Autofac
• Можно исключать определённые маршруты или методы из обработки через атрибут [SkipResponseWrapping] или конфигурацию ResponseHandlingSettings:ExcludedPaths в appsettings.json

Особенности

• Централизованное перехватывание исключений через middleware
• Цепочка IExceptionMapper для сопоставления исключений с ErrorResponse
• Расширяемый builder ExceptionMapperBuilder
• Автоматическая упаковка успешных ответов в ApiResponse<T>
• Поддержка HTTP-статусов и бизнес-ошибок
• Логирование необработанных исключений
• Исключение определённых маршрутов из обработки через [SkipResponseWrapping] или ExcludedPaths в настройках
• Автоматическая регистрация HealthController для мониторинга
• Исправлена проблема с циклическими зависимостями при регистрации IExceptionMapper
• Переименован middleware для обработки ответов: UseErrorHandling → UseResponseHandling

Установка

dotnet add package VoluntasProgressus.APICore --version 2.2.2

Настройка через appsettings.json

{
  "ResponseHandling": {
    "ExcludedPaths": [ "/swagger", "/docs" ]
  }
}

Регистрация в DI (.NET DI или Autofac)

Через стандартный Microsoft DI:

services.AddApiCore(Configuration);

services.AddExceptionMappers(builder =>
{
    builder.Add<CustomExceptionMapper>();
});

app.UseResponseHandling();

Через Autofac:

var builder = new ContainerBuilder();
builder.AddApiCore(Configuration);

// Регистрируем свои ExceptionMapper через Autofac
builder.RegisterType<CustomExceptionMapper>()
       .As<IExceptionMapper>()
       .SingleInstance();

var container = builder.Build();

Пример использования атрибута для исключения метода или контроллера

[SkipResponseWrapping]
[ApiController]
[Route("example")]
public class ExampleController : ControllerBase
{
    [HttpGet("ignored")]
    public IActionResult GetIgnored()
    {
        return Ok(new { message = "Этот ответ не будет обёрнут" });
    }
}

English

Description

Provides centralized exception handling and standardized API responses:

• Errors are returned in RFC 7807 Problem Details format (application/problem+json)
• Successful responses are wrapped in ApiResponse<T>
• HealthController is automatically registered via services.AddApiCore() at /health
• Supports Autofac as a DI container
• Routes or methods can be excluded from wrapping via [SkipResponseWrapping] or ResponseHandlingSettings:ExcludedPaths in configuration
• Circular dependencies when registering IExceptionMapper are fixed
• Middleware renamed for clarity: UseErrorHandling → UseResponseHandling

Features

• Centralized exception interception via middleware
• Chain of IExceptionMapper to map exceptions to ErrorResponse
• Extensible ExceptionMapperBuilder
• Automatic wrapping of successful responses in ApiResponse<T>
• Supports HTTP statuses and business exceptions
• Logging of unhandled exceptions
• Exclude specific endpoints from wrapping via attribute or configuration
• Auto-registration of HealthController for health monitoring

Configuration via appsettings.json

{
  "ResponseHandling": {
    "ExcludedPaths": [ "/swagger", "/docs" ]
  }
}

DI Registration

Standard Microsoft DI:

services.AddApiCore(Configuration);

services.AddExceptionMappers(builder =>
{
    builder.Add<CustomExceptionMapper>();
});

app.UseResponseHandling();

Autofac:

var builder = new ContainerBuilder();
builder.AddApiCore(Configuration);

builder.RegisterType<CustomExceptionMapper>()
       .As<IExceptionMapper>()
       .SingleInstance();

var container = builder.Build();

Skip wrapping for controller/method

[SkipResponseWrapping]
[ApiController]
[Route("example")]
public class ExampleController : ControllerBase
{
    [HttpGet("ignored")]
    public IActionResult GetIgnored()
    {
        return Ok(new { message = "This response will not be wrapped" });
    }
}

Deutsch / German

Beschreibung

Dieses Paket bietet zentrale Ausnahmebehandlung und standardisierte API-Antworten:

• Fehler werden im RFC 7807 Problem Details Format zurückgegeben (application/problem+json)
• Erfolgreiche Antworten werden in ApiResponse<T> verpackt
• HealthController wird automatisch via services.AddApiCore() unter /health registriert
• Unterstützt Autofac als DI-Container
• Bestimmte Routen oder Methoden können über [SkipResponseWrapping] oder ResponseHandlingSettings:ExcludedPaths ausgeschlossen werden
• Middleware für Response Handling wurde umbenannt (UseErrorHandling → UseResponseHandling)
• Zyklische Abhängigkeiten bei der Registrierung von IExceptionMapper wurden behoben

Funktionen

• Zentrale Ausnahmeerfassung über Middleware
• IExceptionMapper-Kette zur Zuordnung von Ausnahmen zu ErrorResponse
• Erweiterbarer Builder ExceptionMapperBuilder
• Automatisches Verpacken erfolgreicher Antworten in ApiResponse<T>
• Unterstützung von HTTP-Statuscodes und Geschäftslogikfehlern
• Logging von nicht behandelten Ausnahmen
• Ausschluss bestimmter Endpunkte über Attribut oder Konfiguration
• Automatische Registrierung von HealthController für Monitoring

中文 / Chinese

描述

提供集中式异常处理和标准化 API 响应：

• 错误以 RFC 7807 Problem Details 格式返回 (application/problem+json)
• 成功响应封装在 ApiResponse<T> 中
• HealthController 通过 services.AddApiCore() 自动注册，可通过 /health 检查服务状态
• 支持 Autofac DI 容器
• 可以通过 [SkipResponseWrapping] 或 ResponseHandlingSettings:ExcludedPaths 配置排除特定路由或方法
• 修复注册 IExceptionMapper 时的循环依赖
• 中间件已重命名：UseErrorHandling → UseResponseHandling

功能

• 通过中间件集中拦截异常
• IExceptionMapper 链将异常映射为 ErrorResponse
• 可扩展的 ExceptionMapperBuilder
• 自动将成功响应包装为 ApiResponse<T>
• 支持 HTTP 状态码和业务异常
• 未处理异常日志记录
• 通过特性或配置排除特定端点
• 自动注册 HealthController 以便监控服务

License / Лицензия / Lizenz / 许可

MIT License – см. LICENSE.txt