Przejdź do treści

TailoredApps.Shared.WebApi

NuGet License: MIT


Opis

Produkcyjne defaulty dla Web API w ASP.NET Core — jednym wywołaniem podłącza komplet cross-cutting concerns wymaganych w nowoczesnym API, dzięki czemu każdy serwis startuje z tą samą, spójną konfiguracją obserwowalności, health checków i odpornych klientów HTTP.

AddTailoredWebApiDefaults konfiguruje:

  • Metryki, tracing i logi — OpenTelemetry dla ASP.NET Core, HttpClient i runtime'u .NET, eksportowane przez OTLP
  • Health checks — readiness (/health, wszystkie checki) i liveness (/alive, checki oznaczone tagiem live)
  • Klienty HTTP — standardowy handler odporności (retry, circuit breaker, timeouty) oraz service discovery dla każdego klienta tworzonego przez fabrykę

Wszystkie funkcje bindują się z sekcji konfiguracji WebApiDefaults i można je włączać/wyłączać niezależnie. Domyślnym eksporterem jest OTLP (stabilny); dla scrape'owalnego endpointu Prometheus dostępny jest hook ConfigureMetrics.


Instalacja

dotnet add package TailoredApps.Shared.WebApi

Rejestracja w DI

// Program.cs
using TailoredApps.Shared.WebApi;

var builder = WebApplication.CreateBuilder(args);

// Rejestruje OpenTelemetry, health checks oraz odporne klienty HTTP
builder.AddTailoredWebApiDefaults();

var app = builder.Build();

// Mapuje endpointy /health (readiness) i /alive (liveness)
app.MapTailoredWebApiDefaults();

app.Run();

Konfiguracja

Wszystko można wysterować z sekcji WebApiDefaults w appsettings.json:

{
  "WebApiDefaults": {
    "ServiceName": "catalog-api",
    "ServiceVersion": "1.4.0",
    "HealthChecks": {
      "ReadinessPath": "/health",
      "LivenessPath": "/alive",
      "AllowDetailedResponse": false
    },
    "Observability": {
      "EnableMetrics": true,
      "EnableTracing": true,
      "EnableLogging": true,
      "OtlpExporterEndpoint": "http://otel-collector:4317"
    },
    "HttpClient": {
      "EnableStandardResilience": true,
      "EnableServiceDiscovery": true
    }
  }
}

Endpoint OTLP respektuje też standardową zmienną środowiskową OTEL_EXPORTER_OTLP_ENDPOINT. Gdy żaden endpoint nie zostanie ustawiony, telemetria jest zbierana w procesie, ale nie jest nigdzie wysyłana.

Nadpisania w kodzie mają pierwszeństwo przed konfiguracją:

builder.AddTailoredWebApiDefaults(options =>
{
    options.ServiceName = "catalog-api";
    options.HealthChecks.AllowDetailedResponse = builder.Environment.IsDevelopment();
});

Przykład użycia

Sondy Kubernetes

Po zmapowaniu endpointów wystarczy wskazać je w probe'ach:

livenessProbe:
  httpGet:
    path: /alive
    port: 8080
readinessProbe:
  httpGet:
    path: /health
    port: 8080

Endpoint Prometheus /metrics (opcjonalnie)

Domyślnie metryki lecą przez OTLP. Jeśli potrzebujesz lokalnego endpointu scrape'owalnego przez Prometheus, dodaj pakiet OpenTelemetry.Exporter.Prometheus.AspNetCore i użyj hooka:

builder.AddTailoredWebApiDefaults(options =>
{
    options.Observability.ConfigureMetrics = metrics => metrics.AddPrometheusExporter();
});

var app = builder.Build();
app.MapTailoredWebApiDefaults();
app.MapPrometheusScrapingEndpoint(); // /metrics

API Reference

Typ Rodzaj Opis
WebApiDefaultsExtensions.AddTailoredWebApiDefaults Metoda ext. Rejestruje OpenTelemetry, health checks i odporne klienty HTTP
WebApiDefaultsExtensions.MapTailoredWebApiDefaults Metoda ext. Mapuje endpointy /health (readiness) i /alive (liveness)
WebApiDefaultsOptions Options Konfiguracja główna (sekcja WebApiDefaults)
HealthCheckSettings Options Ścieżki i szczegółowość odpowiedzi health checków
ObservabilitySettings Options Metryki, tracing, logi oraz eksporter OTLP
HttpClientSettings Options Resilience i service discovery dla HttpClient

🔒 Bezpieczeństwo

  • Retry tylko dla metod bezpiecznych. Standardowy handler odporności (AddStandardResilienceHandler) domyślnie ponawia każde żądanie. Ponowiony POST /charge, którego pierwsza próba dotarła do serwera, to podwójne obciążenie. Dlatego ponawianie metod zmieniających stan — POST, PUT, PATCH, DELETE, CONNECT — jest wyłączone (HttpClientSettings.RetryUnsafeHttpMethods = false); ponawiane są GET, HEAD, OPTIONS i TRACE. W wersji 1.x PUT i DELETE były jeszcze ponawiane; od 2.0 biblioteka używa wbudowanego DisableForUnsafeHttpMethods() z Microsoft.Extensions.Http.Resilience. Włącz ponawianie tylko wtedy, gdy każdy klient HTTP w hoście używa kluczy idempotencji.
{ "WebApiDefaults": { "HttpClient": { "EnableStandardResilience": true, "RetryUnsafeHttpMethods": false } } }

🤖 AI Agent Prompt

## TailoredApps.Shared.WebApi — Instrukcja dla agenta AI

Używasz biblioteki TailoredApps.Shared.WebApi, aby jednym wywołaniem podłączyć produkcyjne defaulty Web API (OpenTelemetry, health checks, resilience HTTP).

### Rejestracja
```csharp
// Program.cs
builder.AddTailoredWebApiDefaults();
var app = builder.Build();
app.MapTailoredWebApiDefaults(); // /health + /alive
```

### Co zostaje skonfigurowane
- Metryki + tracing + logi (OpenTelemetry) eksportowane przez OTLP
- Health checks: /health (readiness) i /alive (liveness)
- HttpClient: standardowy resilience handler + service discovery

### Konfiguracja (sekcja WebApiDefaults)
- ServiceName / ServiceVersion — atrybuty zasobu OpenTelemetry
- Observability.OtlpExporterEndpoint lub zmienna OTEL_EXPORTER_OTLP_ENDPOINT
- HealthChecks.ReadinessPath / LivenessPath / AllowDetailedResponse
- HttpClient.EnableStandardResilience / EnableServiceDiscovery

### Zasady
- Wywołaj AddTailoredWebApiDefaults na builderze przed Build(), a MapTailoredWebApiDefaults na aplikacji po Build()
- Nie rejestruj OpenTelemetry ani health checków ręcznie — biblioteka robi to za Ciebie
- /alive używaj jako liveness probe, /health jako readiness probe
- Aby wystawić Prometheus /metrics, użyj hooka Observability.ConfigureMetrics
- Nie włączaj `HttpClient:RetryUnsafeHttpMethods` bez kluczy idempotencji — ponowienie POST może zduplikować płatność/zamówienie