ASP.NET Core 2 學習筆記（十二）REST-Like API

来源:https://www.cnblogs.com/snaildev/archive/2018/06/06/9143619.html
-Advertisement-
Play Games

Restful幾乎已算是API設計的標準，通過HTTP Method區分新增(Create)、查詢(Read)、修改(Update)和刪除(Delete)，簡稱CRUD四種數據存取方式，簡約又直接的風格，讓人用的愛不釋手。本篇將介紹如何通過ASP.NET Core實踐REST-Like API。 為 ...


Restful幾乎已算是API設計的標準，通過HTTP Method區分新增(Create)、查詢(Read)、修改(Update)和刪除(Delete)，簡稱CRUD四種數據存取方式，簡約又直接的風格，讓人用的愛不釋手。
本篇將介紹如何通過ASP.NET Core實踐REST-Like API。

為什麼是REST-Like 而不是 REST?

本文API設計未符合HATEOAS(Hypermedia As The Engine Of Application State)原則，所以不得稱為RESTful API。

RESTful API 有四個重要的原則要遵守：

  1. Level 0
    使用HTTP做為資料傳輸的媒介。
  2. Level 1
    不要提供一個包山包海的API，而是要區分資源，每個資源都該有對應的API。
  3. Level 2
    透過HTTP Method區分新增(Create)、查詢(Read)、修改(Update)跟刪除(Delete)。
  4. Level 3
    對同資源可以用鏈結表達的方式，向下延伸查詢或修改。
    參考：HATEOAS

HTTP Method

REST-Like API 對數據的操作行為，通過HTTP Method 分為以下四種方式：

  • 新增(Create)
    用HTTP POST通過Body傳遞JSON或XML格式的數據給Server。例如：

POST http://localhost:5000/api/users
{
   "id": 1,
   "name": "SnailDev"
}

  • 查詢(Read)
    用HTTP GET通過URL帶查詢參數。通常查詢單一資源會用路由參數(Routing Parameter)帶上唯一值(Primary Key)；多筆查詢會用複數，而查詢條件用Query String。例如：

# 單筆查詢
GET http://localhost:5000/api/users/1
# 多筆查詢
GET http://localhost:5000/api/users
# 多筆查詢帶條件
GET http://localhost:5000/api/users?q=SnailDev

  • 修改(Update)
    修改數據如同查詢跟新增的組合，用HTTP PUT通過URL帶路由參數，找到要修改的目標；再通過Body傳遞JSON或XML格式的數據給Server。例如：

PUT http://localhost:5000/api/users/1
{
   "name": "SnailDev"
}

  • 刪除(Delete)
    刪除數據同查詢，用HTTP DELETE通過URL帶路由參數，找到要刪除的目標。例如：

DELETE http://localhost:5000/api/users/1

HTTP Method Attribute

ASP.NET Core 2 學習筆記（六）MVC 有提到，過去ASP.NET MVC把MVC及Web API的套件分開，但在ASP.NET Core中MVC及Web API用的套件是相同的。所以只要裝Microsoft.AspNetCore.Mvc套件就可以用Web API了。路由方式也跟ASP.NET Core 2 學習筆記（七）路由 介紹的RouteAttribute差不多，只是改用HTTP Method Attribute。

HTTP Method Attribute 符合RESTful 原則的路由設定方式如下：

[Route("api/[controller]s")]
public class UserController : Controller
{
    [HttpGet]
    public List<UserModel> Get(string q)
    {
        // ...
    }

    [HttpGet("{id}")]
    public UserModel Get(int id)
    {
        // ...
    }

    [HttpPost]
    public int Post([FromBody]UserModel user)
    {
        // ...
    }

    [HttpPut("{id}")]
    public void Put(int id, [FromBody]UserModel user)
    {
        // ...
    }

    [HttpDelete("{id}")]
    public void Delete(int id)
    {
        // ...
    }
}

目前ASP.NET Core 還沒有像ASP.NET MVC 的MapHttpAttributeRoutes 可以綁Http Method 的全局路由，都要在Action 加上HTTP Method Attribute。

SerializerSettings

 用以下代碼，說明SerializerSettings：

public class UserModel
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }    
    public string PhoneNumber { get; set; }
    public string Address { get; set; }
}

// ...

[Route("api/[controller]s")]
public class UserController : Controller
{
  [HttpGet("{id}")]
  public UserModel Get(int id)
  {
      return new UserModel {
          Id = 1,
          Name = "SnailDev"
      };
  }
}

camel Case

過去ASP.NET Web API 2預設是Pascal Case；而ASP.NET Core預設是使用camel Case。
若想要指定用ContractResolver，可以在Startup.cs的ConfigureServices加入MVC服務時，使用AddJsonOptions設定如下：

// ...
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {        
        services.AddMvc()
                .AddJsonOptions(options => 
                {
                    options.SerializerSettings.ContractResolver 
                        = new CamelCasePropertyNamesContractResolver();
                });
        // 同以下寫法：
        // services.AddMvc();
    }
}

訪問http://localhost:5000/api/users/1會返回JSON如下：

{
    "id": 1,
    "name": "SnailDev",
    "email": null,
    "phoneNumber": null,
    "address": null
}

Pascal Case

若想保持跟ASP.NET Web API 2一樣使用Pascal Case，ContractResolver則改用DefaultContractResolver。

// ...
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {        
        services.AddMvc()
                .AddJsonOptions(options => 
                {
                    options.SerializerSettings.ContractResolver 
                        = new DefaultContractResolver();
                });
    }
}

DefaultContractResolver名稱是延續ASP.NET，雖然名稱叫Default，但在ASP.NET Core它不是Default。CamelCasePropertyNamesContractResolver才是ASP.NET Core的Default ContractResolver。

訪問http://localhost:5000/api/users/1會返回JSON如下：

{
    "Id": 1,
    "Name": "SnailDev",
    "Email": null,
    "PhoneNumber": null,
    "Address": null
}

Ignore Null

上述兩個JSON 回傳，都帶有null 的欄位。在序列化的過程，找不到欄位會自動轉成null，傳送的過程忽略掉也沒錯，反而可以節省到一點流量。

// ...
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {        
        services.AddMvc()
                .AddJsonOptions(options => 
                {
                    options.SerializerSettings.NullValueHandling 
                        = Newtonsoft.Json.NullValueHandling.Ignore;
                });
    }
}

訪問http://localhost:5000/api/users/1會返回JSON如下：

{
    "id": 1,
    "name": "SnailDev"
}

示常式序

Startup.cs

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
                .AddJsonOptions(options => {
                    options.SerializerSettings.NullValueHandling
                        = Newtonsoft.Json.NullValueHandling.Ignore;
                });
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseMvc();
    }
}

Models\ResultModel.cs

namespace MyWebsite.Models
{
    public class ResultModel
    {
        public bool IsSuccess { get; set; }
        public string Message { get; set; }
        public object Data { get; set; }
    }
}

用一個ResultModel 來包裝每個API 回傳的內容，不論調用Web API 成功失敗都用此對象包裝，避免直接throw exception 到Client，產生HTTP Status 200 以外的狀態。　

Controllers/UserController.cs

using System.Collections.Generic;
using System.Linq;
using System.Text.RegularExpressions;
using Microsoft.AspNetCore.Mvc;
using MyWebsite.Models;

namespace MyWebsite.Controllers
{
    [Route("api/[controller]s")]
    public class UserController : Controller
    {
        private static List<UserModel> _users = new List<UserModel>();

        [HttpGet]
        public ResultModel Get(string q)
        {
            var result = new ResultModel();
            result.Data = _users.Where(c => string.IsNullOrEmpty(q) 
                                         || Regex.IsMatch(c.Name, q, RegexOptions.IgnoreCase));
            result.IsSuccess = true;
            return result;
        }

        [HttpGet("{id}")]
        public ResultModel Get(int id)
        {
            var result = new ResultModel();
            result.Data = _users.SingleOrDefault(c => c.Id == id);
            result.IsSuccess = true;
            return result;
        }

        [HttpPost]
        public ResultModel Post([FromBody]UserModel user)
        {
            var result = new ResultModel();
            user.Id = _users.Count() == 0 ? 1 : _users.Max(c => c.Id) + 1;
            _users.Add(user);
            result.Data = user.Id;
            result.IsSuccess = true;
            return result;
        }

        [HttpPut("{id}")]
        public ResultModel Put(int id, [FromBody]UserModel user)
        {
            var result = new ResultModel();
            int index;
            if ((index = _users.FindIndex(c => c.Id == id)) != -1)
            {
                _users[index] = user;
                result.IsSuccess = true;
            }
            return result;
        }

        [HttpDelete("{id}")]
        public ResultModel Delete(int id)
        {
            var result = new ResultModel();
            int index;
            if ((index = _users.FindIndex(c => c.Id == id)) != -1)
            {
                _users.RemoveAt(index);
                result.IsSuccess = true;
            }
            return result;
        }
    }
}

執行結果

通過Postman 測試API。

  • 新增(Create)

  • 查詢(Read)

  • 修改(Update)

  • 刪除(Delete)

參考

Routing in ASP.NET Core 
Attribute Routing in ASP.NET Core 
Richardson Maturity Model 
HATEOAS

 

老司機發車啦：https://github.com/SnailDev/SnailDev.NETCore2Learning


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • 在GridControl控制項上綁定圖片的幾種操作方式
    我們知道，基於DevExpress的開發Winform的項目界面的時候，GridControl控制項是經常用來綁定數據的，一般以常規的字元內容為主，有時候也會有圖片的顯示需要，那麼如果顯示圖片，我們應該如何實現呢？本篇隨筆介紹基於原生GridControl控制項的圖片綁定顯示操作和基於我封裝的分頁控制項（... ...
  • 基於Windows 機器學習(Machine Learning)的圖像分類(Image classification)實現
    今天看到一篇文章 Google’s Image Classification Model is now Free to Learn 說是狗狗的機器學習速成課程（Machine Learning Crash Course）現在可以免費學習啦，因為一開始年初的時候是內部使用的，後來開放給大眾了。大家有誰 ...
  • 紙殼CMS 3.0升級.Net Core 2.1性能大提升
    微軟發佈了.Net Core 2.1正式版，紙殼CMS也在第一時間做了升級，並做了一系列的優化和調整，性能大幅提升，並解決了一些歷史遺留問題，添加了一些新功能。 ...
  • 非同步編程基礎
    本質上適合非同步的操作有：HTTP請求，資料庫指令，Web服務調用等。 1、暫停一段時間(以非同步方式)。 以非同步的方式暫停一段時間，這在進行單元測試或者重試延遲時非常有用。 Task類有一個返回Task對象的靜態函數Delay,下麵是其中的一個 一個簡單的指數退避。指數退避是一種重試策略，重試的延遲時 ...
  • SVN 安裝後右鍵出現點擊滑鼠右鍵彈出錯誤提示：CrashHandler initialization error
    SVN 安裝後右鍵出現點擊滑鼠右鍵彈出錯誤提示：CrashHandler initialization error 原因是目標文件夾中缺少SendRpt.exe文件 解決方案：找svn是好的的同事將bin目錄複製替換本地的bin就可以解決 由於沒有找到上傳附件的地方，就沒有上鄙人的bin目錄了，實屬 ...
  • C# Argument 'picture' must be a picture that can be used as an Icon
    Scenario: 創建了一個WinForm的小程式，希望將它顯示在任務欄，所以在工具欄中的“公共控制項”里，拖入NotifyIcon控制項—notifyIcon1，這個是程式運行任務欄右側通知區域圖標顯示控制項，為控制項notifyIcon的屬性Icon添加一個icon圖標，或從代碼中加入。 Issue: ...
  • 使用後臺線程BackgroundWorker處理任務的總結
    在一些耗時的操作過程中，在長時間運行時可能會導致用戶界面 (UI) 處於停止響應狀態，用戶在這操作期間無法進行其他的操作，為了不使UI層處於停止響應狀態，我們傾向推薦用戶使用BackgroundWorker來進行處理，這個後臺的線程處理，可以很好的實現常規操作的同時，還可以及時通知UI，包括當前處理... ...
  • Linq中的Select與Select many
    Select與Select Many 之前在項目中查詢資料庫中的數據，都是通過sql語句來查詢的，但是隨著時代的發展，微軟在.Net Framework 4.5版中推出的一個主要的特性——LINQ。 LINQ是Language Integrate Query的縮寫，意為語言集成查詢。其中有兩種查詢方 ...
一周排行
    -Advertisement-
    Play Games
  • WPF 已知問題 監聽 WMI 事件導致觸摸失效
    示例項目結構 在 Visual Studio 中創建一個 WinForms 應用程式後，項目結構如下所示： MyWinFormsApp/ │ ├───Properties/ │ └───Settings.settings │ ├───bin/ │ ├───Debug/ │ └───Release/ ...
  • [STAThread]特性
    [STAThread] 特性用於需要與 COM 組件交互的應用程式，尤其是依賴單線程模型（如 Windows Forms 應用程式）的組件。在 STA 模式下，線程擁有自己的消息迴圈，這對於處理用戶界面和某些 COM 組件是必要的。 [STAThread] static void Main(stri ...
  • UWP WinUI3 傳入 AddHandler 的 RoutedEventHandler 類型與事件所需不匹配將拋出參數異常
    在WinForm中使用全局異常捕獲處理 在WinForm應用程式中，全局異常捕獲是確保程式穩定性的關鍵。通過在Program類的Main方法中設置全局異常處理，可以有效地捕獲並處理未預見的異常，從而避免程式崩潰。 註冊全局異常事件 [STAThread] static void Main() { / ...
  • .NET 多版本 WinForm 開源控制項庫 SunnyUI
    前言 給大家推薦一款開源的 Winform 控制項庫，可以幫助我們開發更加美觀、漂亮的 WinForm 界面。 項目介紹 SunnyUI.NET 是一個基於 .NET Framework 4.0+、.NET 6、.NET 7 和 .NET 8 的 WinForm 開源控制項庫，同時也提供了工具類庫、擴展 ...
  • .net core8 使用Swagger（附當前源碼）
    說明 該文章是屬於OverallAuth2.0系列文章，每周更新一篇該系列文章（從0到1完成系統開發）。 該系統文章，我會儘量說的非常詳細，做到不管新手、老手都能看懂。 說明：OverallAuth2.0 是一個簡單、易懂、功能強大的許可權+可視化流程管理系統。 有興趣的朋友，請關註我吧(*^▽^*) ...
  • WPF 什麼時候 VisualTreeHelper.GetDescendantBounds 將返回無窮大
    一、下載安裝 1.下載git 必須先下載並安裝git，再TortoiseGit下載安裝 git安裝參考教程：https://blog.csdn.net/mukes/article/details/115693833 2.TortoiseGit下載與安裝 TortoiseGit，Git客戶端，32/6 ...
  • C# 開源教程帶你輕鬆掌握數據結構與演算法
    前言 在項目開發過程中，理解數據結構和演算法如同掌握蓋房子的秘訣。演算法不僅能幫助我們編寫高效、優質的代碼，還能解決項目中遇到的各種難題。 給大家推薦一個支持C#的開源免費、新手友好的數據結構與演算法入門教程：Hello演算法。 項目介紹 《Hello Algo》是一本開源免費、新手友好的數據結構與演算法入門 ...
  • 第22篇 生成proto文件bat腳本
    1.生成單個Proto.bat內容 @rem Copyright 2016, Google Inc. @rem All rights reserved. @rem @rem Redistribution and use in source and binary forms, with or with ...
  • 記一次 .NET某上位機視覺程式 卡死分析
    一：背景 1. 講故事 前段時間有位朋友找到我，說他的窗體程式在客戶這邊出現了卡死，讓我幫忙看下怎麼回事？dump也生成了，既然有dump了那就上 windbg 分析吧。 二：WinDbg 分析 1. 為什麼會卡死 窗體程式的卡死，入口門檻很低，後續往下分析就不一定了，不管怎麼說先用 !clrsta ...
  • 醫學DICOM文件與PACS系統進行數據傳輸
    前言 人工智慧時代，人臉識別技術已成為安全驗證、身份識別和用戶交互的關鍵工具。 給大家推薦一款.NET 開源提供了強大的人臉識別 API，工具不僅易於集成，還具備高效處理能力。 本文將介紹一款如何利用這些API，為我們的項目添加智能識別的亮點。 項目介紹 GitHub 上擁有 1.2k 星標的 C# ...
所有分類