.Net MinimalApis響應返回值

前言

文本主要講 MinimalApis 中的使用自訂 IResultModel 和系統內建 IResult 做響應返回值。
MinimalApis 支持以下型別的返回值：

string 返回值

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

Hello World


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

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

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 = "[email protected]", Age = 18 })
.WithSummary("測試類")
.Produces<User>();


返回值

{
"name": "Ruipeng",
"email": "[email protected]",
"age": 18
}


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

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

統一響應格式程式碼


publicinterfaceIResultModel
{
///<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>
publicinterfaceIResultModel<outT> : IResultModel
{
///<summary>
/// 返回數據
///</summary>
T? Data { get; }
}





實作

public classResultModel<T> : IResultModel<T>
{
publicResultModel()
{
Timestamp = DateTimeOffset.Now.ToUnixTimeSeconds();
}
///<summary>
/// 處理是否成功
///</summary>
publicbool? IsSuccess { get; set; }
///<summary>
/// 錯誤資訊
///</summary>
publicstring? Message { get; set; }
///<summary>
/// 業務碼
///</summary>
publicint? StatusCode { get; set; }
///<summary>
/// 時間戳
///</summary>
publiclong? 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;
returnthis;
}
///<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;
returnthis;
}
}
///<summary>
/// 返回結果
///</summary>
publicstatic classResultModel
{
///<summary>
/// 數據已存在
///</summary>
///<returns></returns>
publicstatic IResultModel<string> HasExists => Failed("data already exists");
///<summary>
/// 數據不存在
///</summary>
publicstatic IResultModel<string> NotExists => Failed("data doesn't exist");
///<summary>
/// 成功
///</summary>
///<param name="data">返回數據</param>
///<returns></returns>
publicstatic IResultModel<T> Success<T>(T? data = default)
{
returnnew ResultModel<T>().Success(data);
}
///<summary>
/// 成功
///</summary>
///<param name="task">任務</param>
///<returns></returns>
publicstaticasync 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>
publicstatic IResultModel<string> Success()
{
return Success<string>();
}

///<summary>
/// 失敗
///</summary>
///<param name="error">錯誤資訊</param>
///<returns></returns>
publicstatic IResultModel<T> Failed<T>(string? error = null)
{
returnnew ResultModel<T>().Failed(error ?? "failed");
}
///<summary>
/// 失敗
///</summary>
///<returns></returns>
publicstatic IResultModel<string> Failed(string? error = null)
{
return Failed<string>(error);
}
///<summary>
/// 根據布爾值返回結果
///</summary>
///<param name="success"></param>
///<returns></returns>
publicstatic IResultModel<T> Result<T>(bool success)
{
return success ? Success<T>() : Failed<T>();
}
///<summary>
/// 根據布爾值返回結果
///</summary>
///<param name="success"></param>
///<returns></returns>
publicstaticasync Task<IResultModel> Result(Task<bool> success)
{
returnawait success ? Success() : Failed();
}
///<summary>
/// 根據布爾值返回結果
///</summary>
///<param name="success"></param>
///<returns></returns>
publicstatic IResultModel<string> Result(bool success)
{
return success ? Success() : Failed();
}
///<summary>
/// 時間戳起始日期
///</summary>
publicstaticreadonly DateTime TimestampStart = new(1970, 1, 1, 0, 0, 0, 0);

}



















定義介面

app.MapGet("/TestResultModel", IResultModel (int age) =>
{
List<User> users = [new User() { Name = "Ruipeng", Email = "[email protected]", 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": "[email protected]",
"age": 18
}


自訂類的自動包裝實作

建立一個 Attribute

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


建立中介軟體自動包裝

public class ResponseWrapperMiddleware(RequestDelegate next)
{
publicasync Task InvokeAsync(HttpContext context)
{
if (context.GetEndpoint()?.Metadata.GetMetadata<EnableResponseWrapperAttribute>() is not null)
{
// 儲存原始響應體流
var originalResponseBodyStream = context.Response.Body;
try
{
// 建立記憶體流以捕獲響應
usingvar memoryStream = new MemoryStream();
context.Response.Body = memoryStream;
// 呼叫管道中的下一個中介軟體
await next(context);
// 恢復原始響應體流並寫入格式化結果
context.Response.Body = originalResponseBodyStream;
// 重設記憶體流位置並讀取響應內容
memoryStream.Seek(0, SeekOrigin.Begin);
var readToEnd = awaitnew 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 asobject);
}
finally
{
// 確保在出現異常時恢復原始響應體流
context.Response.Body = originalResponseBodyStream;
}
}
else
{
await next(context);
}
}
}





套用中介軟體

app.UseMiddleware<ResponseWrapperMiddleware>();


建立測試介面

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


返回值

{
"isSuccess": true,
"statusCode": 200,
"timestamp": 1711005201,
"data": {
"name": "Ruipeng",
"email": "[email protected]",
"age": 18
}
}


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

IResult 返回值

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

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

//Return IResult
app.MapGet("/IResult/TestResult", IResult () => Results.Ok(new User() { Name = "Ruipeng", Email = "[email protected]", Age = 18 }));


沒有呼叫擴充套件方法 Produces

app.MapGet("/IResult/TestTypedResult", IResult () => TypedResults.Ok(new User() { Name = "Ruipeng", Email = "[email protected]", Age = 18 }));


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

返回多個 IResult 實作型別

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


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

IResult 自訂響應

添加 Html 擴充套件


publicstatic classResultsExtensions
{
publicstatic IResult Html(this IResultExtensions resultExtensions, string html)
{
ArgumentNullException.ThrowIfNull(resultExtensions);
returnnew HtmlResult(html);
}
}

classHtmlResult(stringhtml) : IResult
{
privatereadonlystring _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 = "[email protected]", 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#p-15.6.1",
"title": "內部錯誤",
"status": 500
}


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

最後

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

官網文件 如何在最小 API 套用中建立響應 ^[2]

以下是本文的完整 原始碼 ^[3]

希望本文對你有幫助！

參考資料

[1]

Microsoft.AspNetCore.Http.HttpResults: https://learn.microsoft.com/zh-cn/dotnet/api/microsoft.aspnetcore.http.httpresults