TypedResults vs. Results nelle Minimal API di ASP.NET Core

Le Minimal API di ASP.NET Core offrono un modo snello per costruire endpoint HTTP. Sia la classe statica Results che TypedResults sono helper per creare le risposte, ma c’è una differenza fondamentale che rende TypedResults l’opzione preferita per un codice più robusto e ben documentato.

Che cosa fa la classe Results?

La classe Results fornisce metodi helper (ad esempio, Results.Ok(), Results.NotFound()) che restituiscono tutti l’interfaccia generica IResult.

• Tipo di Ritorno: IResult (interfaccia non tipizzata).
• Vantaggio: È flessibile. Quando un endpoint può restituire diversi tipi di risposte (ad esempio, un successo 200 o un errore 404), il compilatore inferisce automaticamente IResult come tipo di ritorno, senza richiedere dichiarazioni esplicite.
• Svantaggio: Perde l’informazione sul tipo specifico a compile-time. Questo rende più difficile il unit testing (potrebbe essere necessaria una conversione) e non fornisce automaticamente i metadati completi per OpenAPI/Swagger, spesso richiedendo l’uso esplicito di .Produces(...).

// Risultato è IResult
app.MapGet("/users/{id}", (int id, UserService service) =>
{
    var user = service.GetUser(id);
    return user is null ? Results.NotFound() : Results.Ok(user);
}); 

Che cosa fa la classe TypedResults?

La classe TypedResults fornisce equivalenti tipizzati degli helper di Results. Ad esempio, TypedResults.Ok() non restituisce IResult, ma un tipo specifico come Ok<TValue>.

• Tipo di Ritorno: Tipi concreti che implementano IResult (ad esempio, Ok<TValue>, NotFound, BadRequest).
• Vantaggio:
  • Strongly Typed: Migliora la leggibilità del codice e facilita lo unit testing, poiché si lavora con oggetti fortemente tipizzati.
  • OpenAPI Automatico: Il tipo di ritorno specifico fornisce automaticamente i metadati della risposta per OpenAPI/Swagger, documentando correttamente i codici di stato e gli schemi di risposta senza bisogno di .Produces(...).
• Svantaggio: Per gli endpoint che possono restituire risposte multiple diverse (ad esempio, 200 Ok o 404 Not Found), non puoi usare solo IResult. Devi dichiarare esplicitamente il set di tipi di risultato possibili usando il tipo generico Results<T1, T2, ...>.

// Risultato è Results<Ok<User>, NotFound>
app.MapGet("/users/{id}", (int id, UserService service) => 
{
    var user = service.GetUser(id);
    return user is null ? TypedResults.NotFound() : TypedResults.Ok(user);
});

Quale Dovresti Usare?

Si raccomanda vivamente l’uso di TypedResults.

Sebbene Results sia più semplice da usare in endpoint con risposte multiple non tipizzate, i benefici di TypedResults in termini di sicurezza del tipo, testabilità e documentazione automatica di OpenAPI superano ampiamente il piccolo sforzo aggiuntivo di dichiarare il tipo di ritorno come Results<T1, T2, ...>.

Scegli TypedResults per:

1. Migliorare l’esperienza di sviluppo (DX): Codice più pulito e meno probabilità di errori a runtime.
2. Documentazione API coerente: Generazione automatica di metadati per OpenAPI.
3. Unit Testing semplificato: Lavora con tipi concreti invece di interfacce generiche.