.Net MinimalApis響應返回值

董瑞鹏發表於2024-03-22

前言

文字主要講 MinimalApis 中的使用自定義IResultModel和系統自帶IResult做響應返回值。
MinimalApis支援以下型別的返回值：

string - 這包括 Task<string> 和 ValueTask<string>
T（任何其他型別）- 這包括 Task<T> 和 ValueTask<T>
基於 IResult - 這包括 Task<IResult> 和 ValueTask<IResult>

本文的完整原始碼在文末

`string` 返回值

行為	Content-Type
框架將字串直接寫入響應。	text/plain

200 狀態程式碼與 text/plain Content-Type 標頭和以下內容一起返回

Hello World

T（任何其他型別）返回值

我們上面說的自定義 IResultModel就是用這種模式處理的

行為	Content-Type
框架 JSON 序列化響應。	application/json

MinimalApis 框架 Json 序列化全域性配置如下

    //透過呼叫 ConfigureHttpJsonOptions 來全域性配置應用的選項
    builder.Services.ConfigureHttpJsonOptions(options =>
    {
        options.SerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles;//忽略迴圈引用
        options.SerializerOptions.WriteIndented = true;
        options.SerializerOptions.IncludeFields = true;
        options.SerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
    });

返回 T


app.MapGet("/TestT", User () => new User() { Name = "Ruipeng", Email = "xxx@163.com", Age = 18 })
   .WithSummary("測試類")
   .Produces<User>();

返回值

{
  "name": "Ruipeng",
  "email": "xxx@163.com",
  "age": 18
}

200 狀態程式碼與 application/json Content-Type 標頭和以下內容一起返回

這個 HttpCode狀態碼只能返回 200，且不支援多種返回形式，比較侷限

統一響應格式程式碼


public interface IResultModel
{
    /// <summary>
    ///     是否成功
    /// </summary>
    bool? IsSuccess { get; }

    /// <summary>
    ///     錯誤資訊
    /// </summary>
    string? Message { get; }

    /// <summary>
    ///     業務碼，用於業務中自定義
    /// </summary>
    int? StatusCode { get; set; }

    /// <summary>
    ///     時間戳
    /// </summary>
    long? Timestamp { get; }
}

/// <summary>
///     返回結果模型泛型介面
/// </summary>
/// <typeparam name="T"></typeparam>
public interface IResultModel<out T> : IResultModel
{
    /// <summary>
    ///     返回資料
    /// </summary>

    T? Data { get; }
}

實現

public class ResultModel<T> : IResultModel<T>
{
    public ResultModel()
    {
        Timestamp = DateTimeOffset.Now.ToUnixTimeSeconds();
    }

    /// <summary>
    ///     處理是否成功
    /// </summary>
    public bool? IsSuccess { get; set; }

    /// <summary>
    ///     錯誤資訊
    /// </summary>
    public string? Message { get; set; }

    /// <summary>
    ///     業務碼
    /// </summary>
    public int? StatusCode { get; set; }

    /// <summary>
    ///     時間戳
    /// </summary>
    public long? Timestamp { get; }

    /// <summary>
    ///     返回資料
    /// </summary>
    public T? Data { get; set; }


    /// <summary>
    ///     成功
    /// </summary>
    /// <param name="Data"></param>
    public ResultModel<T> Success(T? data = default)
    {
        this.IsSuccess = true;
        StatusCode = 200;
        Data = data;
        return this;
    }

    /// <summary>
    ///     失敗
    /// </summary>
    /// <param name="msg">說明</param>
    /// <param name="code"></param>
    public ResultModel<T> Failed(string? msg = "failed", int? code = 500)
    {
        IsSuccess = false;
        Message = msg;
        StatusCode = code;
        return this;
    }
}

/// <summary>
///     返回結果
/// </summary>
public static class ResultModel
{
    /// <summary>
    ///     資料已存在
    /// </summary>
    /// <returns></returns>
    public static IResultModel<string> HasExists => Failed("data already exists");

    /// <summary>
    ///     資料不存在
    /// </summary>
    public static IResultModel<string> NotExists => Failed("data doesn't exist");

    /// <summary>
    ///     成功
    /// </summary>
    /// <param name="data">返回資料</param>
    /// <returns></returns>
    public static IResultModel<T> Success<T>(T? data = default)
    {
        return new ResultModel<T>().Success(data);
    }

    /// <summary>
    ///     成功
    /// </summary>
    /// <param name="task">任務</param>
    /// <returns></returns>
    public static async Task<IResultModel<T>> SuccessAsync<T>(Task<T>? task = default)
    {
        return task is not null && task != default ? new ResultModel<T>().Success(await task) : new ResultModel<T>();
    }

    /// <summary>
    ///     成功
    /// </summary>
    /// <returns></returns>
    public static IResultModel<string> Success()
    {
        return Success<string>();
    }


    /// <summary>
    ///     失敗
    /// </summary>
    /// <param name="error">錯誤資訊</param>
    /// <returns></returns>
    public static IResultModel<T> Failed<T>(string? error = null)
    {
        return new ResultModel<T>().Failed(error ?? "failed");
    }

    /// <summary>
    ///     失敗
    /// </summary>
    /// <returns></returns>
    public static IResultModel<string> Failed(string? error = null)
    {
        return Failed<string>(error);
    }

    /// <summary>
    ///     根據布林值返回結果
    /// </summary>
    /// <param name="success"></param>
    /// <returns></returns>
    public static IResultModel<T> Result<T>(bool success)
    {
        return success ? Success<T>() : Failed<T>();
    }

    /// <summary>
    ///     根據布林值返回結果
    /// </summary>
    /// <param name="success"></param>
    /// <returns></returns>
    public static async Task<IResultModel> Result(Task<bool> success)
    {
        return await success ? Success() : Failed();
    }

    /// <summary>
    ///     根據布林值返回結果
    /// </summary>
    /// <param name="success"></param>
    /// <returns></returns>
    public static IResultModel<string> Result(bool success)
    {
        return success ? Success() : Failed();
    }

    /// <summary>
    /// 時間戳起始日期
    /// </summary>
    public static readonly DateTime TimestampStart = new(1970, 1, 1, 0, 0, 0, 0);


}

定義介面

app.MapGet("/TestResultModel", IResultModel (int age) =>
{
    List<User> users = [new User() { Name = "Ruipeng", Email = "xxx@163.com", Age = 18 }];
    return users.FirstOrDefault(_ => _.Age > age) is User user ? ResultModel.Success(user) : ResultModel.Failed();
})
   .WithSummary("測試自定義IResultModel")
   .Produces<IResultModel<User>>();

封裝了一個靜態類來簡化自定義類的建立，支援多個返回型別

返回值

{
  "isSuccess": true,
  "statusCode": 200,
  "timestamp": 1711001093,
  "data": {
    "name": "Ruipeng",
    "email": "xxx@163.com",
    "age": 18
  }

自定義類的自動包裝實現

建立一個Attribute

[AttributeUsage(AttributeTargets.Method)]
public class EnableResponseWrapperAttribute : Attribute { }

建立中介軟體自動包裝

public class ResponseWrapperMiddleware(RequestDelegate next)
{
    public async Task InvokeAsync(HttpContext context)
    {

        if (context.GetEndpoint()?.Metadata.GetMetadata<EnableResponseWrapperAttribute>() is not null)
        {
            // 儲存原始響應體流
            var originalResponseBodyStream = context.Response.Body;
            try
            {
                // 建立記憶體流以捕獲響應
                using var memoryStream = new MemoryStream();
                context.Response.Body = memoryStream;

                // 呼叫管道中的下一個中介軟體
                await next(context);

                // 恢復原始響應體流並寫入格式化結果
                context.Response.Body = originalResponseBodyStream;

                // 重置記憶體流位置並讀取響應內容
                memoryStream.Seek(0, SeekOrigin.Begin);
                var readToEnd = await new StreamReader(memoryStream).ReadToEndAsync();
                var objResult = JsonSerializer.Deserialize<dynamic>(readToEnd);
                var result = new ResultModel<object>
                {
                    Data = objResult,
                    IsSuccess = true,
                    StatusCode = context.Response.StatusCode
                };
                await context.Response.WriteAsJsonAsync(result as object);

            }
            finally
            {
                // 確保在出現異常時恢復原始響應體流
                context.Response.Body = originalResponseBodyStream;
            }
        }
        else
        {
            await next(context);
        }
    }
}

應用中介軟體

app.UseMiddleware<ResponseWrapperMiddleware>();

建立測試介面

app.MapGet("/TestTestAutoWarpper", [EnableResponseWrapper] User () => new User() { Name = "Ruipeng", Email = "xxx@163.com", Age = 18 }).WithSummary("測試類")
   .Produces<User>();

返回值

{
  "isSuccess": true,
  "statusCode": 200,
  "timestamp": 1711005201,
  "data": {
    "name": "Ruipeng",
    "email": "xxx@163.com",
    "age": 18
  }
}

為了方便測試在MinimalApis 的介面上如果新增了EnableResponseWrapperAttribute則透過中介軟體自動包裝返回值

IResult 返回值

行為	Content-Type
框架呼叫 IResult.ExecuteAsync	由 IResult 實現決定

在dotNet7 之後多了一個TypedResults類來替代 Results。
IResult 介面定義一個表示 HTTP 終結點結果的協定。靜態 Results 類和靜態 TypedResults 用於建立表示不同型別的響應的各種 IResult 物件。

返回 TypedResults（而不是 Results）有以下優點：

TypedResults 幫助程式返回強型別物件，這可以提高程式碼可讀性、改進單元測試並減少執行時錯誤的可能性。
實現型別會自動為 OpenAPI 提供響應型別後設資料來描述終結點。
實現在Microsoft.AspNetCore.Http.HttpResults

//Return IResult
app.MapGet("/IResult/TestResult", IResult () => Results.Ok(new User() { Name = "Ruipeng", Email = "xxx@163.com", Age = 18 }));

沒有呼叫擴充套件方法 Produces

app.MapGet("/IResult/TestTypedResult", IResult () => TypedResults.Ok(new User() { Name = "Ruipeng", Email = "xxx@163.com", Age = 18 }));

可以看到 TypedResults 預設就會新增路由終結點的後設資料描述

返回多個 IResult 實現型別

app.MapGet("/IResult/ReturnMultipleTypes", Results<Ok<User>, NotFound> (int age) =>
{
    List<User> users = [new User() { Name = "Ruipeng", Email = "xxx@163.com", Age = 18 }];
    return users.FirstOrDefault(_ => _.Age > age) is User user ? TypedResults.Ok(user) : TypedResults.NotFound();
});

圖簡單可以直接用 IResult 返回型別但是，由於 TypedResults 幫助程式自動包含終結點的後設資料，因此可以改為返回 Results<Ok<User>, NotFound> 聯合型別

IResult 自定義響應

新增 Html 擴充套件


public static class ResultsExtensions
{
    public static IResult Html(this IResultExtensions resultExtensions, string html)
    {
        ArgumentNullException.ThrowIfNull(resultExtensions);

        return new HtmlResult(html);
    }
}


class HtmlResult(string html) : IResult
{
    private readonly string _html = html;

    public Task ExecuteAsync(HttpContext httpContext)
    {
        httpContext.Response.ContentType = MediaTypeNames.Text.Html;
        httpContext.Response.ContentLength = Encoding.UTF8.GetByteCount(_html);
        return httpContext.Response.WriteAsync(_html);
    }
}

app.MapGet("/IResult/Html", () => Results.Extensions.Html(@$"<!doctype html>
<html>
    <head><title>miniHTML</title></head>
    <body>
        <h1>Hello World</h1>
        <p>The time on the server is {DateTime.Now:O}</p>
    </body>
</html>"));

返回結果

<!DOCTYPE html>
<html>
  <head>
    <title>miniHTML</title>
  </head>
  <body>
    <h1>Hello World</h1>
    <p>The time on the server is 2024-03-21T17:31:36.2931959+08:00</p>
  </body>
</html>

自定義 Json 格式

上面寫了ConfigureHttpJsonOptions方法來配置全域性請求的 Json 格式，下面則是針對單個路由終結點請求，方便一些個性化介面的處理

var options = new JsonSerializerOptions(JsonSerializerDefaults.Web)
{ WriteIndented = true };

app.MapGet("/IResult/CustomJsonConfig", () =>
    TypedResults.Json(new User() { Name = "Ruipeng", Email = "xxx@163.com", Age = 18 }, options));

返回 ProblemDetail

app.MapGet("/IResult/ProblemDetail", () =>
{
    var problemDetail = new ProblemDetails()
    {
        Status = StatusCodes.Status500InternalServerError,
        Title = "內部錯誤"
    };
    return TypedResults.Problem(problemDetail);
});

返回值

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
  "title": "內部錯誤",
  "status": 500
}

在Microsoft.AspNetCore.Http.Results的擴充套件下，TypedResults 有非常多擴充套件的方法，比如處理檔案，回撥，流以及登入認證等，大家可以根據需求使用.

最後

用那種方式還是取決於專案的實際情況，如果你的系統是業務碼和 httpStateCode要求分離的形式那建議用上面自定義統一響應的形式，要是沒這方面的需求那dotNet自帶的TypedResults使用起來就更合適。

官網文件如何在最小 API 應用中建立響應

以下是本文的完整原始碼

希望本文對你有幫助！

一種處理laravel返回值響應的解決方案
2021-05-18
Laravel
.Net Core HttpClient處理響應壓縮
2020-08-04
HTTPclient
ASP.NET Core中的響應壓縮
2020-07-29
ASP.NET
.net core 雜記：WebAPI的XML請求和響應
2019-07-03
WebAPIXML
Asp.Net Core 統一Api返回值
2024-07-21
ASP.NETAPI
.NET Core授權失敗如何自定義響應資訊？
2021-07-11
使用 ResponseBodyAdvice 攔截Controller方法預設返回引數，統一處理返回值/響應體
2018-11-01
Controller
vb.net 介面POST方式傳引數提交返回值
2021-01-04
【應急響應】Windows應急響應入門手冊
2021-02-08
Windows
asp.net 應用程式中同步方法呼叫非同步方法無響應解決方法
2023-03-28
ASP.NET非同步
Vue響應式—-資料響應式原理
2019-02-28
Vue
HTTP 響應
2020-04-04
HTTP
php響應
2024-10-15
PHP
ASP.NET Core中如何限制響應傳送速率（不是呼叫頻率）
2023-03-08
ASP.NET
windows應急響應(二)
2024-09-21
Windows
應急響應命令（Linux）
2024-07-12
Linux
Linux應急響應排查
2020-11-26
Linux
在ASP.Net和IIS中刪除不必要的HTTP響應頭
2019-05-11
ASP.NETHTTP
【ASP.NET Core】設定 Web API 響應資料的格式——FormatFilter特性篇
2022-02-13
ASP.NETWebAPIORMFilter
【ASP.NET Core】設定Web API 響應的資料格式——Produces 特性篇
2022-02-06
ASP.NETWebAPI
理解響應者和響應鏈如何處理事件
2018-11-05
事件
請求和響應
2018-12-11
npm無響應
2018-05-31
NPM
什麼是應急響應?網路安全應急響應體系的要素！
2021-08-20
Windows應急響應小結
2024-04-27
Windows
Linux應急響應小結
2024-04-27
Linux
應急響應- Linux入侵排查
2024-04-28
Linux
應急響應-webshell查殺
2024-04-28
Webshell
應急響應靶機-3
2024-03-23
應急響應靶機-4
2024-03-25
應急響應:日誌分析
2024-08-13
5.28應急響應思路流程
2024-05-29
什麼是應急響應?網路安全應急響應的物件是什麼?
2021-12-14
物件
為什麼需要應急響應?網路安全應急響應需要做什麼?
2023-02-03
自己實現一個VUE響應式--VUE響應式原理
2020-01-16
Vue
全面解析Js陣列遍歷對原陣列的影響及返回值
2019-04-11
JS陣列
使用 ASP.NET Core MVC 建立 Web API——響應資料的內容協商（七）
2019-05-14
ASP.NETMVCWebAPI
iOS響應者鏈
2018-10-18
iOS