#Minimal API #.Net 6

花10秒就可以建置中台API服務! Minimal API開發說明

李億陽 Willie Li 2024/06/27 17:26:48
1674

花10秒就可以建置中台API服務! Minimal API開發說明

只需要一個program.cs就能建立一個網頁

Minimal Api 是.Net6引進的新方法,使用更簡單,更輕量的方法實現功能,使用者甚至能用不到五行程式碼就可以快速建立一個中台API服務。

好處是略過傳統scaffolding並且避免多餘的Controller,將流程簡單化。

(scaffolding : 以標準化的方式建立模組的CRUD,白話文來講就是提供CRUD模板)

相比於以往的.Net core開發方法,每個功能需要建置額外的Controller當成服務的端點,Minimal API只需要一列函數,就可以將Service 和Controller整合並且定義測試用的Swagger介面,這對於開發者是一大好處,減少了Debug找尋端點的時間,讓程式碼更簡單易懂。

今天的章節會帶大家了解Minimal API的使用方式,以下分為:

  • 專案建立設定
  • 四行Code即可建置一個中台API服務
  • 解析 Minimal APIHttp方法
  • 與一般需要Controller的方法差別
  • 進階用法-Swagger 定義
  • 指定的網域
  • Web API 與 Minimal API 差別
  • 總結-對比Web API優缺點

 

專案建立設定

建立專案時,請選擇ASP.NET Core Web API,然後點選下一步。

輸入專案名稱,選擇存放位置,點選下一步。

將使用控制器的打勾取消,點選專案建立。

完成後的畫面,會看到只有Program.cs以及appsetings.json,這兩個主要檔案,點選program.cs,程式會預設幫你寫好範例,若要修改,將多餘程式碼刪除即可。

 

四行Code即可建置一個中台API服務,範例如下:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () => "This is a GET");
app.Run();

//當然除了Get方法還有其餘CRUD會使用到的範例,格式都是一樣的
app.MapPost("/", () => "This is a POST");
app.MapPut("/", () => "This is a PUT");
app.MapDelete("/", () => "This is a DELETE");

圖示

 

解析 Minimal APIHttp方法

app.MapGet("/", () => "This is a GET"); 可以看到”/”這是Url後面的綴詞,你可以在這定義你的方法後綴詞,例如/GetSomething,到時候呼叫這支方法時,會像是http://localhost:5000/GetSomething。 ()的部分是RequestBody,依據請求所需的RequestBody帶入方法內。⇒之後的則為回傳值。

了解這些之後就能快速寫完CRUD的方法,並且建構中台。

 

與一般需要Controller的方法差別

//Controller
[HttpGet("/")]
public string Get()
{
	return "This is a GET";
}
//Minimal Api 
app.MapGet("/", () => "This is a GET");

可以看到整體的寫法精簡很多,將URL的設定也融合在同一行,由此一來當開發的功能越來越多時,就可以一眼便認出所有功能,以及使用的HTTP method,增加程式的可讀性。

 

進階用法-Swagger 定義

Minimal API也支援OpenApi規格以及Swagger介面,我們可以直接定義,省去配置swagger文檔的時間。

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer(); //排除不是api的方法
builder.Services.AddSwaggerGen(); //新增swagger服務


//實作支援Swagger介面Web Api
var app = builder.Build();
app.UseSwagger(); // 使用 Swagger
app.UseSwaggerUI(); // 啟用 Swagger 網頁介面
app.MapGet("/", () => "This is Get").WithOpenApi(op => { 
    op.Summary = "Swagger摘要說明";
    op.Description = "Swagger詳細說明"; 
    return op;
})
.WithTags("Swagger標籤");
.Produces<ApiSuccessModel>((int)HttpStatusCode.OK)
.Produces<ApiErrorModel>((int)HttpStatusCode.BadRequest);

app.Run();

.WithOpenApi()內,可以依據想呈現在swagger上的說明,使用對應的函數,例如 .Summary是Swagger摘要說明,.Description是Swagger詳細說明等。.Produces則是可以顯示出回應200時的sample model以及出錯時的sample model,produces後面的<>是要對應httpStatus的model,最後面的括弧內則是httpStatus 200或400或其他狀態碼。

圖示

 

當然如果今天你有指定的網域,你也可以這麼做

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.Urls.Add(http://localhost:5000);// 將指定網域配置到app.Urls內
app.MapGet("/", () => "This is a GET");
app.Run();
//或者也可以在app.Run時,將指定網域指派到程式啟動時
app.Run(http://localhost:5000);

使用app的屬性 新增指定網域,像是app.Urls.Add(http://localhost:5000),或者也可以在專案啟動時,同時指派,像是app.Run(http://localhost:5000)。當然Minimal API也保留了appsetting.json,可以直接在設定檔中定義環境參數,再以參數的方式,帶進以上兩種方法之中。

 

Web API 與 Minimal API 差別

  Web API Minimal API
架構 需要由Controller去控制多個方法 除去原本的Controller,直接在Program.cs定義URL以及各功能的商業邏輯
配置和設置 通過設定檔案和註釋進行高度客製化 利用最小的配置,讓人快速上手
性能 由於需要較多組件,以及各種文件配置下,所耗資源較多 以最少資源,加速專案啟動,耗費效能較少
URL定義 利用Attribute來配置各個功能的路徑 直接在Program.cs定義
適合場景 大型的企業級應用,尤其需要處理複雜的商業邏輯,和清楚的分層結構 小型專案,不需要過多複雜的架構與配置

 

總結

以上是Minimal API整體的用法,可以加速專案的建置,縮減前期開發成本,若以此為模組,工程師更能同時兼顧多數專案,雖然有這麼多的優點,但畢竟Minimal Api是稱為輕量化Web Api的方法,因此在套件使用上,可能會有套件不相容的問題,或是遇到較複雜的專案架構,例如: 保險公司網頁後台,需要較多流程的規劃時,以筆者自身經驗,使用Minimal Api 就會遇到程式碼太過冗長的問題,因為流程一多,就需要呼叫比較多的service,可能a呼叫b,b又需要去呼叫c,這種有分層式呼叫的service時,會比較難去簡化程式碼,這時候回歸Web API較為適合。因此在取捨上,使用者需要依據專案結構來抉擇。

 

參考

https://learn.microsoft.com/zh-tw/aspnet/core/tutorials/min-web-api?view=aspnetcore-8.0&tabs=visual-studio

https://ithelp.ithome.com.tw/m/articles/10291068

https://blog.darkthread.net/blog/minimal-api/

https://www.cnblogs.com/wucy/p/15611641.html

李億陽 Willie Li