iT邦幫忙

第 12 屆 iThome 鐵人賽

DAY 8
0
Modern Web

我與 ASP.NET Core 的 30天系列 第 8

[Day08] Restful API - 我與 ASP.NET Core 3 的 30天

Rest/Resful簡介

REST是目前最常見的API設計規範

REST 全名為 REpresentationalStateTransfer(表現層狀態移轉),主要是提供一堆軟體架構設計上的限制

例如:無狀態 (Stateless)、主從式架構 (Client-Server)、一致性的介面 (Uniform Interface) ....等等

一個軟體架構符合REST風格,就可以稱作是RESTful

RESTful API 有以下幾個建議的設計方式

  • 回傳格式使用 JSON
  • 善用HTTP 動詞(Verbs)
  • 善用HTTP 狀態碼(Status Code)
  • 盡量使用 SSL 加密連線
  • 擁有良好的 APIs 文件
  • 限制回傳的欄位 (不要回傳用不到的資料)

常見HTTP 動詞(Verbs)

  • GET 讀取資源
  • PUT 替換資源
  • PATCH 更換資源部分內容
  • DELETE 刪除資源
  • POST 新增資源

常用HTTP 狀態碼(Status Code)
2XX 成功:
這類型狀態碼,代表請求已成功被伺服器接收、理解、並接受。

  • 200 OK
    請求已成功,請求所希望的回應head或資料將隨此回應返回。

3xx 重新導向:
這類狀態碼代表需要客戶端採取進一步的操作才能完成請求。

  • 302 Found
    要求客戶端執行臨時重新導向。

4xx 客戶端錯誤:
這類的狀態碼代表了客戶端看起來可能發生了錯誤,妨礙了伺服器的處理。

  • 400 Bad Request
    由於明顯的客戶端錯誤,伺服器不能或不會處理該請求。(例如,格式錯誤的請求語法,太大的大小,無效的請求訊息或欺騙性路由請求)
  • 401 Unauthorized
    未認證 (簡單一點可以理解成未登入)
  • 403 Forbidden
    伺服器已經理解請求,但是拒絕執行它。(簡單一點可理解成已登入,但是存取權限不足)
  • 404 Not Found
    請求失敗,找不到資源。
  • 405 Method Not Allowed
    請求行中指定的請求方法不能被用於請求相應的資源。(例如,原本需要POST的方法,改用GET呼叫,使用了錯誤的Http Mehod而導致的錯誤)

5xx伺服器錯誤
表示伺服器無法完成明顯有效的請求。

  • 500 Internal Server Error
    通用錯誤訊息,伺服器遇到了一個未曾預料的狀況,導致了它無法完成對請求的處理。沒有給出具體錯誤資訊。

更多Status Code

使用dotnet cli搭配EF Core模型來產生API Controllers

在Windows上開發,有著地表最強開發工具Visaul Studio來做為開發的輔助利器,非常容易的就能透過EF Core的Model產生Controller。

在macOS沒有VS可以使用,但又想利用程式自動化產出相對應的內容,這時候就需要使用dotnet aspnet-codegenerator

dotnet aspnet-codegenerator 微軟提供的dotnet cli全域工具,提供生成程式碼的功能,透過cli就能有使用VS快速產生程式碼的體驗

首先先透過 dotnet cli 來安裝 dotnet aspnet-codegenerator

dotnet tool install -g dotnet-aspnet-codegenerator

接著我們首先要準備我們首先要準備好專案以及建立Model,請參照前面的文章建立[Day06]EF Core CodeFirst
建立完畢之後我們需要在專案下安裝Nuget 套件

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
(需要安裝才能在專案中使用CodeGeneration)
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
(Microsoft.VisualStudio.Web.CodeGeneration.Design 需要搭配此套件才能進行code generation)

安裝完畢之後就可以在專案目錄底下使用dotnet cli 建立我們的controller
dotnet-aspnet-codegenerator controller --controllerName PostController -async -api -actions -m Post -dc BlogContext -outDir Controllers

參數 作用
-controllerName 或 -name 設定控制器的名稱
-useAsyncActions 或 -async 產生非同步控制器動作。
-restWithNoViews 或 -api 使用 REST 樣式 API 產生控制器。 假設使用 noViews 且會忽略所有檢視相關選項。
-readWriteActions 或 -actions 在不使用模型的情況下使用讀取/寫入動作產生控制器。
-model 或 -m 要使用的模型類別。
-dataContext 或 -dc 要使用的 DbContext 類別。
-relativeFolderPath 或 -outDir 專案的相對輸出資料夾路徑,其為產生檔案的位置。 若未指定,則會在專案資料夾中產生檔案。

dotnet aspnet-codegenerator 參數使用參考

產生完的範例:
PostController.cs 中的 PutPost()

[HttpPut("{id}")]
public async Task<IActionResult> PutPost(int id, Post post)
{
    if (id != post.Id)
    {
        return BadRequest();
    }

    _context.Entry(post).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!PostExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

範例可以看到產出來的API的程式碼連各種情境的回應都幫我們做好了

接著透過Postman來測試API是否可以正常運作
(記得將BlogContext 註冊到DI容器中)
https://ithelp.ithome.com.tw/upload/images/20200922/20129389MJgB5FJrIV.png

可以看到user這欄是null,而user這欄是我們在建立Model的時候,對於關聯表所做的建立,因此其實是不需要用到的欄位,這時候我們可以通過設定,將值為null的欄位忽略掉。
首先到Startup.cs 中的 ConfigureServices()作下列修改

public void ConfigureServices(IServiceCollection services)
{
   services.AddScoped<BlogContext>();
   services.AddControllers()
           .AddJsonOptions(options => 
               {
                   options.JsonSerializerOptions.IgnoreNullValues = true;
               });
}

在AddControllers()後方加入設定,將null的項目都Ignore掉。
https://ithelp.ithome.com.tw/upload/images/20200922/20129389U9woSuYSRb.png
就可以看到user因為是null,所以回傳的時候就自動被篩掉了。

Web API 分析器

剛才上面的範例我們也能看到Action中有很多種回應方式,為了讓程式更清晰更好閱讀,
這時候我們就需要用到 Web API 分析器

分析器封裝會通知您下列任何控制器動作:

  • 傳回未宣告的狀態碼。
  • 傳回未宣告的成功結果。
  • 記錄未傳回的狀態碼。
  • 包含明確的模型驗證檢查。

備註:Web API 分析器只能在VS 2017+與VS For Mac上才可使用

首先在專案檔(.csproj)中加入

<PropertyGroup>
    <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
</PropertyGroup>

接著我們使用VS for Mac開啟專案,並進到PostController中的PutPost
會看到return的部分底下會有飄底線,接著我們把滑鼠移到return這一行並點選燈泡按鈕
https://ithelp.ithome.com.tw/upload/images/20200922/20129389d8xEQolGck.png

選取Add ProducesResponseType
https://ithelp.ithome.com.tw/upload/images/20200922/20129389ArzEdOvnMr.png

選取完之後就會看到,Web API分析器幫我們產生的ProducesResponseType
https://ithelp.ithome.com.tw/upload/images/20200922/20129389KQhnPcgrsj.png

透過分析器產生的ProducesResponseType可以讓我們一眼就清楚看出這個Action會有哪幾種回應,更容易的閱讀我們的程式。

相關參考
dotnet aspnet-codegenerator
使用 Web API 分析器
使用 Web API 慣例


上一篇
[Day07] Entity Framework Core 的 原始 SQL 查詢(Raw SQL Query) - 我與 ASP.NET Core 3 的 30天
下一篇
[Day09]使用Swagger自動建立清晰明瞭的REST API文件 - 我與 ASP.NET Core 的 30天
系列文
我與 ASP.NET Core 的 30天31

尚未有邦友留言

立即登入留言