《ASP.ENT Core 與 RESTful API 開(kāi)發(fā)實(shí)戰(zhàn)》-- 讀書(shū)筆記（第1章）
2021-10-22 16:42:43

第 1 章 REST 簡(jiǎn)介

1.1 API 與 REST

API 是一個(gè)系統(tǒng)向外暴露或公開(kāi)的一套接口，通過(guò)這些接口，外部應(yīng)用程序能夠訪(fǎng)問(wèn)該系統(tǒng)

REST 是一種基于資源的架構(gòu)風(fēng)格，任何能夠命名的對(duì)象都是一個(gè)資源，如 user，一個(gè)資源具有一個(gè)統(tǒng)一的資源標(biāo)識(shí)符（URI），如 user/1234，通過(guò) URI 能夠標(biāo)識(shí)并訪(fǎng)問(wèn)該資源

REST 定義了6個(gè)架構(gòu)約束：

• 客戶(hù)端-服務(wù)器
• 統(tǒng)一接口
• 分層系統(tǒng)
• 緩存
• 無(wú)狀態(tài)
• 按需編碼

統(tǒng)一接口約束本身又由4個(gè)子約束組成：

• 資源的標(biāo)識(shí)
• 通過(guò)表述操作資源
• 自描述消息
• 超媒體作為應(yīng)用程序狀態(tài)引擎

1.2 HTTP 協(xié)議

基于 TCP/IP 協(xié)議的應(yīng)用層協(xié)議

瀏覽網(wǎng)頁(yè)的過(guò)程，就是通過(guò) HTTP 協(xié)議來(lái)傳遞瀏覽器與服務(wù)器之間的請(qǐng)求與響應(yīng)的

HTTP 協(xié)議采用請(qǐng)求/響應(yīng)模型

HTTP 協(xié)議采用明文傳輸數(shù)據(jù)，這種方式并不安全，所以后來(lái)設(shè)計(jì)了 HTTPS 協(xié)議

統(tǒng)一資源定位符（URL）代表網(wǎng)絡(luò)上一個(gè)特定的資源

對(duì)于一個(gè) URL，如 ??http://www.xxx.com/images/logo.png??

它由以下幾個(gè)部分組成：

• http://，這一部分是 URL 協(xié)議，指明了如何訪(fǎng)問(wèn)一個(gè)特定的資源
• www.xxx.com，這一部分是主機(jī)名，告訴瀏覽器所要訪(fǎng)問(wèn)資源所在的服務(wù)器名稱(chēng)
• /images/logo.png，這一部分是 URL 路徑，它指向服務(wù)器上具體的資源
• 端口號(hào)，在主機(jī)后面，以冒號(hào)隔開(kāi)，這一部分通常省略，服務(wù)器在這個(gè)端口上監(jiān)聽(tīng) HTTP 請(qǐng)求
• 查詢(xún)字符串，URL 中 “?” 后面的參數(shù)部分
• 錨部分，也稱(chēng)片段，在 “#” 后面的內(nèi)容，用于指明一個(gè)資源的特定的位置

當(dāng) HTTP 服務(wù)器對(duì)請(qǐng)求返回響應(yīng)時(shí)，它不僅僅返回資源本身，也會(huì)在響應(yīng)中指明資源的內(nèi)容類(lèi)型（Content Type），也稱(chēng)為媒體類(lèi)型

要指定內(nèi)容類(lèi)型，HTTP 依賴(lài)于 MIME 標(biāo)準(zhǔn)，表示文檔的性質(zhì)和格式

常用的 MIME 類(lèi)型如下：

• text/plain: 純文本
• text/html: HTML
• image/jepg: JEPG 圖片
• image/png: PNG 圖片
• application/json: JSON格式數(shù)據(jù)

HTTP 請(qǐng)求消息和響應(yīng)消息具有相似的結(jié)構(gòu)：

• 起始行：描述執(zhí)行的請(qǐng)求，或者對(duì)應(yīng)的狀態(tài)，成功或失敗
• HTTP 消息頭：請(qǐng)求或響應(yīng)的相關(guān)屬性、配置、對(duì)消息正文的描述等
• 空行：指明消息頭已經(jīng)發(fā)送完畢
• 消息正文：包含請(qǐng)求數(shù)據(jù)，或響應(yīng)中資源的表述

請(qǐng)求起始行包括：

• HTTP 方法
• 請(qǐng)求目標(biāo)
• HTTP 版本

響應(yīng)起始行包括：

• 協(xié)議版本
• 狀態(tài)碼
• 狀態(tài)文本

常見(jiàn)的 HTTP 請(qǐng)求方法有：GET、POST、PUT、DELETE、PATCH（部分更新）、HEAD、OPTIONS

HTTP 狀態(tài)碼由3個(gè)數(shù)字組成，用于指明 HTTP 請(qǐng)求的結(jié)果

根據(jù)其表述意義，狀態(tài)碼可以分為以下5類(lèi)：

• 1xx：信息，服務(wù)器收到請(qǐng)求，需要請(qǐng)求方繼續(xù)執(zhí)行操作
• 2xx：成功：服務(wù)器成功執(zhí)行客戶(hù)端所請(qǐng)求的操作
• 3xx：重定向：需要進(jìn)一步的操作以完成請(qǐng)求
• 4xx：客戶(hù)端錯(cuò)誤：請(qǐng)求包含語(yǔ)法錯(cuò)誤或請(qǐng)求內(nèi)容不正確
• 5xx：服務(wù)端錯(cuò)誤：服務(wù)器在處理請(qǐng)求的過(guò)程中發(fā)生了錯(cuò)誤

1.3 REST 最佳實(shí)踐

首先，在實(shí)現(xiàn) RESTful 系統(tǒng)時(shí)，應(yīng)正確地使用 HTTP 方法、HTTP 消息頭和 HTTP 狀態(tài)碼

除了原則以外，在設(shè)計(jì)資源的 URI 時(shí)也應(yīng)該注意以下原則：

• 使用名詞的復(fù)數(shù)表示一個(gè)資源集合
• 使用斜線(xiàn) ”/“ 用來(lái)表示資源之間的層次關(guān)系
• 對(duì)資源的增刪改查等操作名稱(chēng)不應(yīng)該包含在 URL 中
• 如果一個(gè)操作無(wú)法對(duì)應(yīng)到資源的某個(gè)操作上，此時(shí)可以適當(dāng)?shù)卦?URI 中包含動(dòng)詞，但仍然應(yīng)該基于一個(gè)資源的標(biāo)識(shí)符
• 查詢(xún)字符串可以用來(lái)對(duì)資源進(jìn)行篩選、搜索或分頁(yè)查詢(xún)
• URI 應(yīng)使用小寫(xiě)字母
• URI 中可以使用中劃線(xiàn) ”-“ 來(lái)增加其可讀性
• URI 中不應(yīng)使用下劃線(xiàn) ”_“ ，因?yàn)闀?huì)使得 URI 點(diǎn)擊時(shí)下劃線(xiàn)不可見(jiàn)
• URL 末尾不應(yīng)包含斜線(xiàn) ”/“ ，因?yàn)闆](méi)意義而且可能造成歧義

1.4 其他問(wèn)題

在 RESTful API 中，JSON 和 XML 是最常用到的兩種資源表述格式

JSON 是一種輕量級(jí)的數(shù)據(jù)交換格式，數(shù)據(jù)使用名稱(chēng)/值來(lái)表示，中間用冒號(hào)隔開(kāi)

JSON 數(shù)據(jù)項(xiàng)的值的類(lèi)型可以是下列類(lèi)型：

• 數(shù)字
• 字符串
• 邏輯值
• 數(shù)組
• 對(duì)象
• null

XML 與 HTML 語(yǔ)言很相似，包含標(biāo)簽、屬性等元素，而且有非常嚴(yán)格的層次結(jié)構(gòu)，一個(gè)標(biāo)簽必須同時(shí)具有起始標(biāo)簽與結(jié)束標(biāo)簽，允許自定義標(biāo)簽

XML 文檔必須包含根元素，該元素是文檔中其他元素的父元素，文檔中的所有元素形成一棵文檔樹(shù)

XML 每個(gè)標(biāo)簽之間還必須要正確的嵌套，另外，標(biāo)簽名區(qū)分大小寫(xiě)，標(biāo)簽允許包含一個(gè)或多個(gè)屬性，每個(gè)屬性的值必須使用引號(hào)

JSON 比 XML 更簡(jiǎn)潔，容易解析，但是不支持注釋?zhuān)瑪U(kuò)展性不如 XML

RESTful API 添加版本有以下4中方式：

• 使用 URI 路徑，如 api/v1/users
• 使用查詢(xún)字符串，如 api/users?version=1
• 使用自定義消息頭，如 Accept-version:v1
• 使用 Accept 消息頭，如 Accept:application/json;v=2.0

?
?