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

第 1 章 REST 簡介

1.1 API 與 REST

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

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

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

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

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

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

1.2 HTTP 協(xié)議

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

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

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

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

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

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

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

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

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

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

常用的 MIME 類型如下：

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

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

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

請求起始行包括：

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

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

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

常見的 HTTP 請求方法有：GET、POST、PUT、DELETE、PATCH（部分更新）、HEAD、OPTIONS

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

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

• 1xx：信息，服務(wù)器收到請求，需要請求方繼續(xù)執(zhí)行操作
• 2xx：成功：服務(wù)器成功執(zhí)行客戶端所請求的操作
• 3xx：重定向：需要進(jìn)一步的操作以完成請求
• 4xx：客戶端錯(cuò)誤：請求包含語法錯(cuò)誤或請求內(nèi)容不正確
• 5xx：服務(wù)端錯(cuò)誤：服務(wù)器在處理請求的過程中發(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è)資源集合
• 使用斜線 ”/“ 用來表示資源之間的層次關(guān)系
• 對資源的增刪改查等操作名稱不應(yīng)該包含在 URL 中
• 如果一個(gè)操作無法對應(yīng)到資源的某個(gè)操作上，此時(shí)可以適當(dāng)?shù)卦?URI 中包含動(dòng)詞，但仍然應(yīng)該基于一個(gè)資源的標(biāo)識符
• 查詢字符串可以用來對資源進(jìn)行篩選、搜索或分頁查詢
• URI 應(yīng)使用小寫字母
• URI 中可以使用中劃線 ”-“ 來增加其可讀性
• URI 中不應(yīng)使用下劃線 ”_“ ，因?yàn)闀沟?URI 點(diǎn)擊時(shí)下劃線不可見
• URL 末尾不應(yīng)包含斜線 ”/“ ，因?yàn)闆]意義而且可能造成歧義

1.4 其他問題

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

JSON 是一種輕量級的數(shù)據(jù)交換格式，數(shù)據(jù)使用名稱/值來表示，中間用冒號隔開

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

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

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

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

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

JSON 比 XML 更簡潔，容易解析，但是不支持注釋，擴(kuò)展性不如 XML

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

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

?
?