使用 ASP.NET Core MVC 建立 Web API（四）

使用 ASP.NET Core MVC 建立 Web API

使用 ASP.NET Core MVC 建立 Web API（一）

使用 ASP.NET Core MVC 建立 Web API（二）

 使用 ASP.NET Core MVC 建立 Web API（三）

十3、返回值

      在上一篇文章（使用 ASP.NET Core MVC 建立 Web API（二））中咱們建立了GetBookItems和 GetBookItem兩個方法，這兩個方法的返回類型是 ActionResult<T> 類型。 ASP.NET Core 自動將對象序列化爲 JSON，並將 JSON 寫入響應消息的正文中。 GetBookItems和 GetBookItem方法正確執行，沒有未經處理的異常的狀況下，返回類型的響應代碼爲200。若是有未經處理的異常返回的響應代碼爲5xx。

    一些操做方法的結果返回類型會是特殊格式，例如 JsonResult 和 ContentResult。操做能夠返回始終以特定方式進行格式設置的特定結果。 例如，返回 JsonResult 將返回 JSON 格式的數據，而不考慮客戶端首選項。 一樣，返回 ContentResult 將返回純文本格式的字符串數據（僅返回字符串也是如此）。

    ActionResult 返回類型能夠表示大範圍的 HTTP狀態代碼。例如，   在上一篇文章（使用 ASP.NET Core MVC 建立 Web API（二））咱們建立的GetBookItem方法能夠返回兩個不一樣的狀態值，以下：

    1) 若是沒有數據庫中沒有存在與請求 ID相匹配的書籍信息，則該方法將返回 404 NotFound 錯誤代碼。以下圖。

 

    2)若是數據庫中存在與請求ID相匹配的書籍信息，則此方法將返回 JSON格式數據的響應正文，而且產生 HTTP 200 響應。  以下圖。

 

一）特定類型

    在應用程序中咱們對於操做方法的返回值最簡單作法是返回.NET簡單類型或複雜數據類型（如 string 或自定義對象類型）。請參考如下代碼，該操做方法返回自定義 Book 對象的集合：

 public  Book GetBook(int id)
        {
            var bookItem =  _context.Book.Find(id);   
            return bookItem;
        }

    1）在執行操做方法期間無需考慮已知條件時，返回特定類型便可知足要求。

     2）當在操做方法執行期間須要考慮已知條件時，可能會有多個結果類型須要返回。在這種狀況下，一般會將返回類型設爲ActionResult或 ActionResult<T>，這樣就能夠返回基本簡單類型或複雜返類型。

    二)IActionResult 類型

    當操做方法存在多個 ActionResult 須要返回時，適合使用 IActionResult 返回類型。 ActionResult 類型表示多種 HTTP 狀態代碼。 屬於此類別的一些常見返回類型包括：BadRequestResult (400)、NotFoundResult (404) 和 OkObjectResult (200)。

    因爲操做中有多個返回類型和路徑，所以可使用 [ProducesResponseType] 特性。 此特性方便 Swagger 等工具生成的 API 幫助頁生成更多描述性響應詳細信息。 [ProducesResponseType] 指示操做將返回的已知類型和 HTTP 狀態代碼。以下面的示例：

[HttpGet("{id}")]
[ProducesResponseType(typeof(Book), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
    public async IActionResult  GetBookById(int id)
        {
            var bookItem = await _context.Book.FindAsync(id);
            if (bookItem == null)
            {
                return NotFound();
            }
    return Ok(bookItem);
        }

    在上面的代碼中，當與id相匹配的書籍不存在數據庫中時，則返回 404 狀態代碼。 調用 NotFound 幫助程序方法做爲 return new NotFoundResult(); 的快捷方式。 若是書籍信息存在數據庫中，則返回表明有效負載的 bookItem對象和狀態代碼 200。 調用 Ok 幫助程序方法做爲 return new OkObjectResult(bookItem); 的快捷方式。

三）ActionResult<T> 類型

      ASP.NET Core 2.1 引入了面向 Web API 控制器操做的 ActionResult<T> 返回類型。 它支持返回從 ActionResult 派生的類型或返回特定類型。 ActionResult<T> 經過 IActionResult 類型可提供如下優點：

    1)  可排除 [ProducesResponseType] 特性的 Type 屬性。 例如，[ProducesResponseType(200, Type = typeof(Book))] 可簡化爲 [ProducesResponseType(200)]。 此操做的預期返回類型改成根據 ActionResult<T> 中的 T 進行推斷。

    2)  隱式強制轉換運算符支持將 T 和 ActionResult 均轉換爲 ActionResult<T>。 將 T 轉換爲 ObjectResult，也就是將 return new ObjectResult(T); 簡化爲 return T;。

     C# 不支持對接口使用隱式強制轉換運算符。 所以，必須使用 ActionResult<T>，才能將接口轉換爲具體類型。 例如，在下面的示例中，使用 IEnumerable 返回所有書籍信息：

 [HttpGet]
        public async Task<ActionResult<IEnumerable<Book>>> GetBookItems()
        {
            return await _context.Book.ToListAsync();
        }

   

     大多數操做具備特定返回類型。 執行操做期間可能出現意外狀況，不返回特定類型就是其中之一。 例如，操做的輸入參數可能沒法經過模型驗證。 在此狀況下，一般會返回相應的 ActionResult 類型，而不是特定類型。

 

十4、添加新增方法

      接下來咱們來實現一個新增方法，在WEB API中使用什麼來實現新增方法呢？

      特性[HttpPost]指示這個方法接收HTTP POST方法請求傳過來的數據，並從 HTTP 請求正文中獲取書籍信息的值。

       在Visual Studio 2017中打開BookController.cs文件，在文件中添加如下 PostBookItem 方法：

  // POST: api/Book
        [HttpPost]
        public async Task<ActionResult<Book>> PostBookItem(Book item)
        {
            _context.Book.Add(item);
            await _context.SaveChangesAsync();
            return CreatedAtAction(nameof(GetBookItem), new { id = item.ID }, item);
        }

對於CreatedAtAction 方法的說明：

• 若是成功，則返回 HTTP 201 狀態代碼。 HTTP 201 是在服務器上建立新資源的 HTTP POST 方法的標準響應。
• 將 Location 標頭添加到響應。 Location 標頭指定新建的書籍信息的 URI。
• 引用 GetBookItem操做以建立 Location 標頭的 URI。 C# nameof 關鍵字用於避免在 CreatedAtAction 調用中硬編碼操做名稱。

 

一）測試 PostBookItem 方法

    1) 在Visual Studio 2017中按F5，啓動BookApi應用程序。

     2) 打開Firefox瀏覽器，並打開 Rester，在Reseter中，將 HTTP 方法設置爲 POST。

     3) 選擇「Headers」選項卡，選擇「Content-Type」選項，並將值設置爲 JSON (application/json)，以下圖。

 

     4) 而後選擇「BODY」選項卡，在請求正文中，輸入咱們想新增的書籍信息的 JSON，以下圖：

    JSON字符串：

  {"name":"Python編程實踐","releaseDate":"2018-02-12","price":55.49,"author":"馬瑟斯","publishing":"機械工業出版社"}

    5)  使用鼠標左鍵，單擊「SEND」按鈕。成功建立了一條新的書籍信息，返回響應爲201。以下圖。

 

      若是收到 500內部服務器錯誤，則檢查代碼與數據是否符合數據庫要求，405 不容許的方法錯誤，則多是因爲未在添加 PostBookItem 方法以後編譯項目。

二） 測試位置標頭 URI

      6) 在前文咱們對代碼進行過解釋，成功建立新的書籍信息以後，響應返回中的Location 標頭指向新建的書籍信息的 URI。接下來咱們來測試一下，在「Response」窗格中複製「位置」標頭值，以下圖。

 

    7) 在Rester中把方法設置爲「GET」。

    8)  在URL輸入框中，粘貼剛纔複製的 URI（例如，https://localhost:5000/api/Book/24），以下圖。

 

     9)  選擇「SEND」，咱們會獲取ID=24的書籍信息，就是咱們剛纔新增的書籍信息。以下圖。