ASP.NET Core與RESTful API 開發實戰（一）
簡介
這是一篇《ASP.NET Core與RESTful API 開發實戰》的個人讀書筆記，如有需要推薦購買正版書籍，詳細閱讀學習。
REST與HTTP簡介
什么是REST
REST 是一種基於資源的架構風格，在REST 中，資源是最基本的概念。任何能夠命名的對象都是一個資源，如docuent,user,order等，通常情況下，它表示Web服務中要操作的一個實體。一個資源具有一個統一的資源標識符，如users/1234，通過資源標識符能夠表示並訪問該資源。
除了單個的資源外，資源集合表示多個相同類型的資源，如uesrs。在系統設計時，不同的實體之間往往存在某種關聯關系，如一個用戶有多個訂單。同樣在REST中，這種關聯關系也能夠由資源之間的層次關系體現出來，如users/1234/orders/1
由於REST以資源為中心，因此REST接口的端點均以資源或資源集合結尾，它不像其他形式的web服務一樣以動詞結尾，如api/GetUserInfo/或api/UpdateUserInfo.在REST中，對資源的動作或操作時通過HTTP方法來完成的。
REST約束
REST定義了6個架構約束，遵循這些約束的Web服務是真正的RESTful服務，即REST風格的服務。如果一個系統違反了其中的約束，則不能稱其為RESTful，這些約束包括如下：
- 客戶端-服務器
客戶端-服務器約束體現了關注點分離原則。 - 統一接口
統一接口是設計任何RESTful服務的基礎，也是區別REST架構風格與其他Web服務風格的最主要約束。系統中的多個組件（包括服務端，客戶端，以及可能存在的代理服務器等）都依賴於統一接口。統一接口本身又由4個子約束組成，分別如下：
1. 資源的標識
2. 通過表述操作資源
當請求一個資源時，服務器返回該資源的一個表述。該表述表示資源當前的狀態，它由表述正文和表述元數據組成，格式通常為JSON,XML,和HTML等。
3. 自描述信息
客戶端與服務器之間傳遞的每一條消息都應包含足夠的信息，這些信息不僅包含了資源的表述，也包含了資源表述的相關信息。（如資源表述的格式與內容長度等），甚至包含了與該資源相關的其他操作信息。
4. 超媒體作為應用程序狀態引擎
服務器返回的資源的資源表述中不僅要包含資源的表述，也應包含與之相關的鏈接，這些鏈接能夠對資源執行其他操作，比如當獲取資源時，返回的鏈接中包含更新該資源，刪除該資源等來鏈接。 - 分層系統
分層系統約束能夠使網絡中介（如代理或網關等）透明地部署到客戶端與服務器之間，只要它們遵循並且使用前面提到的同意接口約束即可；而客戶端和服務器則都不知道網絡中介的存在，中間服務器主要用於增強安全，負責均衡和相應緩存等目的。 - 緩存
緩存是Web架構中最重構的特性之一。客戶端或網絡中介均能夠緩存服務器返回的響應，因此當服務器返回響應時，應知名該相應的緩存特ing。對相應進行緩存將有助於減少數據獲取延遲以及對服務器的請求，從而提高系統的性能。 - 無狀態
無狀態約束將知名服務器不會記錄或儲存客戶端的狀態信息，反之，這些狀態信息應由客戶端來保存並維護，因此客戶端對服務器的請求不能依賴於已發生過的其他請求，當客戶端請求服務器時，必須在請求消息中包含所有與之相關的信息（如認證信息等） - 按需編碼
按需編碼約束允許服務器臨時向客戶端返回可執行的程序代碼（如腳本等,返回這些代碼主要用於為客戶端提供擴展性或自定義的功能。由於客戶端必須理解並能夠執行服務器返回的代碼，因此這一約束增加了客戶端與服務器之間耦合，同時這一約束時可選的。
REST與RPC風格的區別如下：
- 在關注點方面，REST 面向資源，RPC面向功能。
- 在API 端點方面，REST的端點是名詞，是資源或資源集合，而RPC的斷電時動詞，是方法名。
- 在執行特點方面REST對象資源執行操作，RPC執行服務器上的方法
- 在返回結果方面，REST返回請求的資源，而RPC則返回調用方法的執行結果。
HTTP協議
HTTP協議采用了請求/響應模式。當客戶端（通常是瀏覽器）發起一個HTTP請求時，它首先會建立起到HTTP服務器指定端口（HTTP協議默認使用80端口）的TCP連接，而HTTP服務器則負責在該端口監聽來自客戶端的請求。當TCP連接成功建立后，瀏覽器就會向HTTP服務器發送請求命令，如GET/indexs.html.HTTP/1.1.一旦收到請求，服務器會根據請求向客戶端返回響應，其響應內容通常包括一個狀態行（如HTTP/1.1 200 OK）和若干個消息頭，以及詳細正文。消息正文則是資源、請求的文件、錯誤或其他信息等。
統一資源定位符
統一資源定位符，即通常所說的URL代表網絡上一個特定的資源。URL作為URI的子集，一個URL就是一個URI，用於標識並定位資源。
HTTP://,這一部分時URL協議，URL協議指明了如何訪問一個特定的資源，如上例中的http://會告訴瀏覽器要使用HTTP協議，即超文本傳輸協議；除了http：//外，較為常見的協議還有https:(加密的HTTP協議)、ftp://(文件傳輸協議)和mailto:(電子郵件協議）等。
WWW.```.COM,這一部分是主機名，主機名會告訴瀏覽器要訪問的資源所在的服務器名稱。DNS服務器會將這個名稱解析為一個具體的IP地址，通過這個IP地址可以找到資源所在的計算機。
images/logo.png,這一部分是URL路徑，它只想服務器上具體的資源。更具要獲取資源的不同，其值也會不同，可以說這一部分的變化性最大。他有可能是再服務器中的一個真實存在的文件，比如這里的images/logo.png，也有可能是由常見的Web框架生成的動態資源，如http://www.```.com/account/index.通常請開給你下，當訪問某個網頁瀏覽器時，瀏覽器會下載其他與此相關的資源，如文本信息，圖片，js文件，css等，所有這些資源構成了我們再瀏覽器中看到的頁面。
除了上述3個主要 部分外，URL還常常包括以下幾個可選的部分
端口號，再主機名后面，以冒號隔開，這一部分通常省略。服務器在這個端口上監聽HTTP氣你去，因此再請求的URL中必須指定相同的端口，HTTP協議默認使用80端口，80默認省略，非80則需要再URL中知名端口號，如：8080等，但這種情況比較少見，一般只有再開發或者調試Web應用時才會使用其他端口。
查詢字符串，URL中“？”后面的參數部分，對於http://www.```com/search?q=helo這樣一個URL，“q=hello”即為查詢字符串，其中“q”是參數名，“hello”是參數值，參數名和參數用“=”分隔。如果要傳遞多個參數，則使用&來分割。查詢的字符串會發送給HTTP服務器，並由服務器上的Web應用程序決定如何處理這一部分的內容。
錨部分，也稱片段，即在“#”后面的內容，它用於指明一個資源的特定位置，例如，http:.//www.```com/index.html#contact，該URL將定位到HTML頁面中指定的元素。這一部分內容與上述的其他部分都不一樣，它不會由服務器處理，只會由瀏覽器處理，也就是說，若更改這一部分的內容，並不會向服務器再次發起請求，瀏覽器就會定位到當前資源的不同位置。
由此可見，一個完整的URL形式如下所示：
😕/ [:port]/[path][?query][#fragment]
媒體類型
如：text/plain、image/gif、audio/midi、video/ogg、application/pdf
HTTP消息
客戶端發出請求，服務器響應，請求與響應過程如同“對話”一樣，兩者使用HTTP協議規定對話格式的消息。HTTP消息證實兩者交換數據的方式，它由兩種類型：請求消息和響應消息
HTTP請求消息和響應消息具有相似的結構，他們都包括一下4部分的內容。
- 起始行：即第一行，用於描述要執行的請求，或者是對應的轉台，即成功或失敗，這個起始行總是單行的。
- HTTP消息頭:這些消息頭描述了請求或響應的相關屬性、配置、對消息正文的描述等。
- 空行：指明消息頭已經發送完畢
- 消息正文：包含請求數據（如要創建的資源、HTML表單內容等），或響應中資源的表述，這一部分可空。
GET /search?hl=zh-CN&source=hp&q=domety&aq=f&oq= HTTP/1.1
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/vnd.ms-excel, application/vnd.ms-powerpoint,
application/msword, application/x-silverlight, application/x-shockwave-flash, */*
Referer: <a href=“http://www.google.cn/”>http://www.google.cn/</a>
Accept-Language: zh-cn
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 2.0.50727; TheWorld)
Host: <a href=“http://www.google.cn”>www.google.cn</a>
Connection: Keep-Alive
Cookie: PREF=ID=80a06da87be9ae3c:U=f7167333e2c3b714:NW=1:TM=1261551909:LM=1261551917:S=ybYcq2wpfefs4V9g;
NID=31=ojj8d-IygaEtSxLgaJmqSjVhCspkviJrB6omjamNrSm8lZhKy_yMfO2M4QMRKcH1g0iQv9u-2hfBW7bUFwVh7pGaRUb0RnHcJU37y-
FxlRugatx63JLv7CWMD6UB_O_r
其中，HTTP請求是由客戶端發出的消息，用於請求服務器執行某個操作，它的起始行包括以下3項：
- HTTP方法：也稱HTTP動詞，如GET、PUT、POST等，它們描述 要執行的動作
- 請求目標：通常是一個URL，它代表所要訪問的資源。
- HTTP版本：通常是HTTP/1.1
而HTTP響應的起始行被稱作狀態行，包含以下三項。
- 協議版本：通常為HTTP/1.1
- 狀態碼（Status Code）:它表明請求是否成功，常見的狀態碼是200、404、500等。
- 狀態文本（Status ）:一個簡短的文本信息，用於描述狀態碼。
HTTP方法
- GET 獲取指定的資源，它並不會修改資源，以因此GET方法是安全的。所謂安全方法，是指不會修改資源的方法。此外GET方法也是冪等的。所謂冪等是指多次對同一個URL調用同一個HTTP方法，其效果總是一樣的。
- POST 創建資源，POST方法不是安全方法，因為它會修改服務器上的資源，並且也不是冪等方法，多次請求同一個POST操作會產生多個不同的資源
- PUT方法的作用是更新資源，因為PUT會修改資源，所以也不是安全方法，與POST方法不同的是，PUT方法是冪等的，多次更新同一個資源，其返回結果都是一樣的。PUT方法除了更新資源外，當資源不存在時，它還可以創建資源``需要注意的是，盡管POST與PUT方法都可以創建資源，但他們請求的URI是有區別的POST請求的URI是資源集合，而PUT則是請求單個不存在的資源，例如：
- DELETE方法的作用是刪除資源，它不是安全的，但它是冪等的，這意味着對同一資源請求多次DELETE方法，效果都是一樣的。當第一次對資源調用DELETE方法時，返回表示操作成功的200 OK狀態碼，后續再調用DELETE方法，由於資源已經不存在，則應返回404 NotFound狀態碼。
- PATCH方法與GET方法相同，但它並不返回消息正文，在響應消息中僅包含響應狀態碼與消息頭，該方法常用來檢測資源是否存在以及獲取資源的元數據。
- OPTIONS方法用於獲取資源支持的操作，服務器在返回的響應中會包含Allow消息頭，它的值為HTTP方法列表，例如：
Allow:GET,POST
綜上所述，常見的HTTP方法總結下：
| 方法名稱 | 作用 | 安全 | 冪等 |
|---|---|---|---|
| GET | 獲取資源 | Y | Y |
| POST | 創建資源 | N | N |
| PUT | 更新指定的資源 | N | Y |
| DELETE | 刪除指定的資源 | N | Y |
| PATCH | 對資源進行部分更新 | N | N |
| HEAD | 與GET方法作用完全一樣，但在響應中沒有消息正文 | Y | Y |
| OPTION | 獲取指定資源所支持的操作 | Y | Y |
HTTP消息頭
客戶端和服務器之間的請求消息與響應消息中均包含消息頭，用來傳遞附加消息。一個消息頭由消息名稱和它的值組成，中間用冒號“：”隔開，比如Content-Type:text/plain.
每個消息頭都有特定的意義，比如上例的消息頭用來指明請求或響應消息中正文的內容類型。HTTP請求與響應均可包含多個消息頭。
除了標准的HTTP消息頭外，一些Web應用程序還會增加自定義消息頭，用於返回一些描述或備注類的消息。自定義的名稱一般以“X-”開頭，以此指明它並不是一個標准的HTTP消息頭，例如 X-AspNet-Version用於指明當前服務器運行的ASP.NET 的版本。
| Header | 解釋 | 示例 |
|---|---|---|
| Accept | 指定客戶端能夠接收的內容類型 | Accept: text/plain, text/html |
| Accept-Charset | 瀏覽器可以接受的字符編碼集。 | Accept-Charset: iso-8859-5 |
| Accept-Encoding | 指定瀏覽器可以支持的web服務器返回內容壓縮編碼類型。 | Accept-Encoding: compress, gzip |
| Accept-Language | 瀏覽器可接受的語言 | Accept-Language: en,zh |
| Accept-Ranges | 可以請求網頁實體的一個或者多個子范圍字段 | Accept-Ranges: bytes |
| Authorization | HTTP授權的授權證書 | Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== |
| Cache-Control | 指定請求和響應遵循的緩存機制 | Cache-Control: no-cache |
| Connection | 表示是否需要持久連接。（HTTP 1.1默認進行持久連接） | Connection: close |
| Cookie | HTTP請求發送時，會把保存在該請求域名下的所有cookie值一起發送給web服務器。 | Cookie: $Version=1; Skin=new; |
| Content-Length | 請求的內容長度 | Content-Length: 348 |
| Content-Type | 請求的與實體對應的MIME信息 | Content-Type: application/x-www-form-urlencoded |
| Date | 請求發送的日期和時間 | Date: Tue, 15 Nov 2010 08:12:31 GMT |
| Expect | 請求的特定的服務器行為 | Expect: 100-continue |
| From | 發出請求的用戶的Email | From: user@email.com |
| Host | 指定請求的服務器的域名和端口號 | Host: www.zcmhi.com |
| If-Match | 只有請求內容與實體相匹配才有效 | If-Match: “737060cd8c284d8af7ad3082f209582d” |
| If-Modified-Since | 如果請求的部分在指定時間之后被修改則請求成功，未被修改則返回304代碼 | If-Modified-Since: Sat, 29 Oct 2010 19:43:31 GMT |
| If-None-Match | 如果內容未改變返回304代碼，參數為服務器先前發送的Etag，與服務器回應的Etag比較判斷是否改變 | If-None-Match: “737060cd8c284d8af7ad3082f209582d” |
| If-Range | 如果實體未改變，服務器發送客戶端丟失的部分，否則發送整個實體。參數也為Etag | If-Range: “737060cd8c284d8af7ad3082f209582d” |
| If-Unmodified-Since | 只在實體在指定時間之后未被修改才請求成功 | If-Unmodified-Since: Sat, 29 Oct 2010 19:43:31 GMT |
| Max-Forwards | 限制信息通過代理和網關傳送的時間 | Max-Forwards: 10 |
| Pragma | 用來包含實現特定的指令 | Pragma: no-cache |
| Proxy-Authorization | 連接到代理的授權證書 | Proxy-Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== |
| Range | 只請求實體的一部分，指定范圍 | Range: bytes=500-999 |
| Referer | 先前網頁的地址，當前請求網頁緊隨其后,即來路 | Referer: http://www.zcmhi.com/archives/71.html |
| TE | 客戶端願意接受的傳輸編碼，並通知服務器接受接受尾加頭信息 | TE: trailers,deflate;q=0.5 |
| Upgrade | 向服務器指定某種傳輸協議以便服務器進行轉換（如果支持） | Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11 |
| User-Agent | User-Agent的內容包含發出請求的用戶信息 | User-Agent: Mozilla/5.0 (Linux; X11) |
| Via | 通知中間網關或代理服務器地址，通信協議 | Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1) |
| Warning | 關於消息實體的警告信息 | Warn: 199 Miscellaneous warning |
HTTP Responses Header 響應頭
| Header | 解釋 | 示例 |
|---|---|---|
| Accept-Ranges | 表明服務器是否支持指定范圍請求及哪種類型的分段請求 | Accept-Ranges: bytes |
| Age | 從原始服務器到代理緩存形成的估算時間（以秒計，非負） | Age: 12 |
| Allow | 對某網絡資源的有效的請求行為，不允許則返回405 | Allow: GET, HEAD |
| Cache-Control | 告訴所有的緩存機制是否可以緩存及哪種類型 | Cache-Control: no-cache |
| Content-Encoding | web服務器支持的返回內容壓縮編碼類型。 | Content-Encoding: gzip |
| Content-Language | 響應體的語言 | Content-Language: en,zh |
| Content-Length | 響應體的長度 | Content-Length: 348 |
| Content-Location | 請求資源可替代的備用的另一地址 | Content-Location: /index.htm |
| Content-MD5 | 返回資源的MD5校驗值 | Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ== |
| Content-Range | 在整個返回體中本部分的字節位置 | Content-Range: bytes 21010-47021/47022 |
| Content-Type | 返回內容的MIME類型 | Content-Type: text/html; charset=utf-8 |
| Date | 原始服務器消息發出的時間 | Date: Tue, 15 Nov 2010 08:12:31 GMT |
| ETag | 請求變量的實體標簽的當前值 | ETag: “737060cd8c284d8af7ad3082f209582d” |
| Expires | 響應過期的日期和時間 | Expires: Thu, 01 Dec 2010 16:00:00 GMT |
| Last-Modified | 請求資源的最后修改時間 | Last-Modified: Tue, 15 Nov 2010 12:45:26 GMT |
| Location | 用來重定向接收方到非請求URL的位置來完成請求或標識新的資源 | Location: http://www.zcmhi.com/archives/94.html |
| Pragma | 包括實現特定的指令，它可應用到響應鏈上的任何接收方 | Pragma: no-cache |
| Proxy-Authenticate | 它指出認證方案和可應用到代理的該URL上的參數 | Proxy-Authenticate: Basic |
| refresh | 應用於重定向或一個新的資源被創造，在5秒之后重定向（由網景提出，被大部分瀏覽器支持） | Refresh: 5; url=http://www.zcmhi.com/archives/94.html |
| Retry-After | 如果實體暫時不可取，通知客戶端在指定時間之后再次嘗試 | Retry-After: 120 |
| Server | web服務器軟件名稱 | Server: Apache/1.3.27 (Unix) (Red-Hat/Linux) |
| Set-Cookie | 設置Http Cookie | Set-Cookie: UserID=JohnDoe; Max-Age=3600; Version=1 |
| Trailer | 指出頭域在分塊傳輸編碼的尾部存在 | Trailer: Max-Forwards |
| Transfer-Encoding | 文件傳輸編碼 | Transfer-Encoding:chunked |
| Vary | 告訴下游代理是使用緩存響應還是從原始服務器請求 | Vary: * |
| Via | 告知代理客戶端響應是通過哪里發送的 | Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1) |
| Warning | 警告實體可能存在的問題 | Warning: 199 Miscellaneous warning |
| WWW-Authenticate | 表明客戶端請求實體應該使用的授權方案 | WWW-Authenticate: Basic |
狀態碼
HTTP響應狀態碼由3個數字組成，用於指明HTTP請求的結果。在狀態碼后會有一個狀態文本，它以文本形式簡單描述狀態的信息，如200 OK、404 Not Found 和500 Internal Server Error等。更具其表述意義，狀態碼可分為以下5類：
- 1xx：信息，服務器收到請求，需要請求方繼續執行操作。
- 2xx：成功 ，服務器成功執行客戶端所請求的操作。
- 3xx：重定向，需要進一步的操作已完成請求。
- 4xx：客戶端錯誤，請求包含語法錯誤或請求內容不正確
- 5xx：服務端錯誤，服務器在處理請求的過程中發生了錯誤。
狀態碼以其首位數字表示它所屬的類別，而后兩位則表示在該類型中具體的信息。