2. 程式人生 > >我們必須要知道的RESTful服務最佳實踐

我們必須要知道的RESTful服務最佳實踐

阿新 • • 發佈：2018-06-08
客戶 存儲 附加 頁面 set 總結 nth 多表查詢 xamarin

看過很多RESTful相關的文章總結，參齊不齊，結合工作中的使用，非常有必要歸納一下關於RESTful架構方式了，RESTful只是一種架構方式的約束，給出一種約定的標準，完全嚴格遵守RESTful標準並不是很多，也沒有必要。但是在實際運用中，有RESTful標準可以參考，是十分有必要的。
實際上在工作中對api接口規範、命名規則、返回值、授權驗證等進行一定的約束，一般的項目api只要易測試、足夠安全、風格一致可讀性強、沒有歧義調用方便我覺得已經足夠了，接口是給開發人員看的，也不是給普通用戶去調用。

回想剛進公司的時候，非常慚愧，並沒仔細地了解接口的一些約束，給自己挖坑，給別人挖坑。第一次聽說RESTful還是剛工作那會，差不多也有兩年了，雖然項目中並沒有嚴格遵守RESTful規範，還是要自我總結反思一下。

我們必須要知道的RESTful服務最佳實踐

本章導讀：

  • REST來源
  • REST是什麽，應該知道的6大原則
  1. C-S架構
  2. 無狀態
  3. 統一的接口
  4. 一致的數據格式
  5. 自我描述的信息
  6. 超媒體即應用狀態引擎（HATEOAS）
  • RESTful使用應該註意的問題
  1. 版本（Versioning）
  2. 參數命名規範
  3. url命名規範
  4. 統一返回數據格式
  5. http狀態碼
  6. 合理使用query parameter
  7. 多表、多參數連接查詢如何設計URL
  8. API請求授權

1.REST的來源

REST：Representational State Transfer（表象層狀態轉變），如果沒聽說過REST，你一定以為是rest這個單詞，剛開始我也是這樣認為的，後來發現是這三個單詞的縮寫，即使知道了這三個單詞理解起來仍然非常晦澀難懂。如何理解RESTful架構，最好的辦法就是深刻理解消化Representational State Transfer這三個單詞到底意味著什麽。

  1. 每一個URI代表一種資源；
  2. 客戶端和服務器之間，傳遞這種資源的某種表現層；
  3. 客戶端通過四個HTTP動詞（get、post、put、delete），對服務器端資源進行操作，實現”表現層狀態轉化”。

是由美國計算機科學家Roy Fielding（百度百科沒有介紹，真是尷尬了）。Adobe首席科學家、Http協議的首要作者之一、Apache項目聯合創始人。

這位大神牛逼的地方在於2000年那時候發表的論文，應該沒被廣泛關註，那時候的網頁前端後端都是融合在一起，接口服務這些東西即使存在這種概念，都沒地方發揮作用，好的東西經得起時間的考驗，就像唐詩宋詞幾千年都會有人讀，而什麽郭敬明的什麽小說我估計00後都不知道什麽玩意（我猜的）

隨著近幾年的移動互聯網的爆發、前後端分離的思想，RESTful架構被廣泛應用，如

  • 博客園的開發平臺：https://developers.douban.com/wiki/?title=api_v2
  • 豆瓣API： https://developers.douban.com/wiki/?title=api_v2
  • GitHub開放平臺： https://developer.github.com/v3/

Roy Fielding的原中英文論文地址如下，可以收藏下載看看，論文一般都比較晦澀難懂。
架構風格與基於網絡的軟件架構設計.pdf
Architectural_Styles_and_the_Design_of_Network-based_Software_Architectures.pdf
前人栽樹，後人乘涼。關於RESTful服務最佳實踐 總結的一篇非常好的文章也是外國人寫的，原英文下載：RESTful Best Practices-v1 2.pdf
有園友翻譯總結後的中文：https://www.cnblogs.com/jaxu/p/7908111.html

2. REST是什麽，應該知道的6大原則

REST之父Roy Fielding在論文中闡述REST架構的6大原則。

1. C-S架構
數據的存儲在Server端，Client端只需使用就行。兩端徹底分離的好處使client端代碼的可移植性變強，Server端的拓展性變強。兩端單獨開發，互不幹擾。
2. 無狀態
http請求本身就是無狀態的，基於C-S架構，客戶端的每一次請求帶有充分的信息能夠讓服務端識別。請求所需的一些信息都包含在URL的查詢參數、header、body，服務端能夠根據請求的各種參數，無需保存客戶端的狀態，將響應正確返回給客戶端。無狀態的特征大大提高的服務端的健壯性和可拓展性。
當然這總無狀態性的約束也是有缺點的，客戶端的每一次請求都必須帶上相同重復的信息確定自己的身份和狀態（這也是必須的），造成傳輸數據的冗余性，但這種確定對於性能和使用來說，幾乎是忽略不計的。
3.統一的接口
這個才是REST架構的核心，統一的接口對於RESTful服務非常重要。客戶端只需要關註實現接口就可以，接口的可讀性加強，使用人員方便調用。
4.一致的數據格式
服務端返回的數據格式要麽是XML、要麽是Json（獲取數據），或者直接返回狀態碼，有興趣的可以看看博客園的開放平臺的操作數據的api，post、put、patch都是返回的一個狀態碼
自我描述的信息
每項數據應該是可以自我描述的，方便代碼去處理和解析其中的內容。比如通過HTTP返回的數據裏面有 [MIME type ]信息，我們從MIME type裏面可以知道數據的具體格式，是圖片，視頻還是JSON
* 超媒體即應用狀態引擎（HATEOAS）*
　客戶端通過body內容、查詢串參數、請求頭和URI（資源名稱）來傳送狀態。服務端通過body內容，響應碼和響應頭傳送狀態給客戶端。這項技術被稱為超媒體（或超文本鏈接）。
　　除了上述內容外，HATEOS也意味著，必要的時候鏈接也可被包含在返回的body（或頭部）中，以提供URI來檢索對象本身或關聯對象。下文將對此進行更詳細的闡述。
　　如請求一條微博信息，服務端響應信息應該包含這條微博相關的其他URL，客戶端可以進一步利用這些URL發起請求獲取感興趣的信息，再如分頁可以從第一頁的返回數據中獲取下一頁的URT也是基於這個原理
4.系統分層
客戶端通常無法表明自己是直接還是間接與端服務器進行連接，分層時同樣要考慮安全策略。
5.可緩存
　　在萬維網上，客戶端可以緩存頁面的響應內容。因此響應都應隱式或顯式的定義為可緩存的，若不可緩存則要避免客戶端在多次請求後用舊數據或臟數據來響應。管理得當的緩存會部分地或完全地除去客戶端和服務端之間的交互，進一步改善性能和延展性。
6.按需編碼、可定制代碼（可選）
服務端可選擇臨時給客戶端下發一些功能代碼讓客戶端來執行，從而定制和擴展客戶端的某些功能。比如服務端可以返回一些 Javascript 代碼讓客戶端執行，去實現某些特定的功能。
提示：REST架構中的設計準則中，只有按需編碼為可選項。如果某個服務違反了其他任意一項準則，嚴格意思上不能稱之為RESTful風格。

3.RESTful使用應該註意的問題

1. 版本（Versioning）
如github開放平臺 https://developer.github.com/v3/ ，就是講版本放在url，簡潔明了，這個只有用了才知道，一般的項目加版本v1，v2，v3?好吧，這個加版本估計只有大公司大項目才會去使用，說出來不怕尷尬，我真沒用過。有的會將版本號放在header裏面，但是不如url直接了當。

https://example.com/api/v1/

2. 參數命名規範

query parameter可以采用駝峰命名法，也可以采用下劃線命名的方式，推薦采用下劃線命名的方式，據說後者比前者的識別度要高，可能是用的人多了吧，因人而異，因團隊規範而異吧。

https://example.com/api/users/today_login 獲取今天登陸的用戶 
https://example.com/api/users/today_login&sort=login_desc 獲取今天登陸的用戶、登陸時間降序排列

3. url命名規範

API 命名應該采用約定俗成的方式，保持簡潔明了， 在RESTful架構中，每個url代表一種資源所以url中不能有動詞，只能有名詞，並且名詞中也應該使用復數。實現者應使用相應的Http動詞GET、POST、PUT、PATCH、DELETE、HEAD來操作這些資源即可
不規範的的url，冗余沒有意義，形式不固定，不同的開發者還需要了解文檔才能調用

https://example.com/api/getallUsers GET 獲取所有用戶 
https://example.com/api/getuser/1 GET 獲取標識為1用戶信息 
https://example.com/api/user/delete/1 GET/POST 刪除標識為1用戶信息 
https://example.com/api/updateUser/1 POST 更新標識為1用戶信息 
https://example.com/api/User/add POST 添加新的用戶

規範後的RESTful風格的url，形式固定，可讀性強，根據users名詞和http動詞就可以操作這些資源

https://example.com/api/users GET 獲取所有用戶信息 
https://example.com/api/users/1 GET 獲取標識為1用戶信息 
https://example.com/api/users/1 DELETE 刪除標識為1用戶信息 
https://example.com/api/users/1 Patch 更新標識為1用戶部分信息,包含在body中 
https://example.com/api/users POST 添加新的用戶

4. 統一返回數據格式

對於合法的請求應該統一返回數據格式，這裏演示的是json

  1. code——包含一個整數類型的HTTP響應狀態碼。
  2. status——包含文本：”success”，”fail”或”error”。HTTP狀態響應碼在500-599之間為”fail”，在400-499之間為”error”，其它均為”success”（例如：響應狀態碼為1XX、2XX和3XX）。這個根據實際情況其實是可要可不要的。
  3. message——當狀態值為”fail”和”error”時有效，用於顯示錯誤信息。參照國際化（il8n）標準，它可以包含信息號或者編碼，可以只包含其中一個，或者同時包含並用分隔符隔開。
  4. data——包含響應的body。當狀態值為”fail”或”error”時，data僅包含錯誤原因或異常名稱、或者null也是可以的

返回成功的響應json格式

{
  "code": 200,
  "message": "success",
  "data": {
    "userName": "123456",
    "age": 16,
    "address": "beijing"
  }
}

返回失敗的響應json格式

{
  "code": 401,
  "message": "error  message",
  "data": null
}

下面這個ApiResult的泛型類是在項目中用到的，拓展性強，使用方便。返回值使用統一的 ApiResult 或 ApiResult
錯誤返回 使用 ApiResultV2<OfT>.Error 進行返回； 成功返回，要求使用 ApiResultV2.Ok 進行返回

    public class ApiResult: ApiResult
    {
        public new static ApiResult<T> Error(string message)
        {
            return new ApiResult<T>
            {
                Code = 1,
                Message = message,
            };
        }
        [JsonProperty("data")]
        public T Data { get; set; }
    }
    public class ApiResult
    {
        public static ApiResult Error(string message)
        {
            return new ApiResult
            {
                Code = 1,
                Message = message,
            };
        }

        public static ApiResult<T> Ok<T>(T data)
        {
            return new ApiResult<T>()
            {
                Code = 0,
                Message = "",
                Data = data
            };
        }
        /// <summary>
        /// 0 是 正常 1 是有錯誤
        /// </summary>
        [JsonProperty("code")]
        public int Code { get; set; }
        [JsonProperty("msg")]
        public string Message { get; set; }

        [JsonIgnore]
        public bool IsSuccess => Code == 0;
    }

5. http狀態碼
在之前開發的xamarin android博客園客戶端的時候，patch、delete、post操作時body響應裏面沒有任何信息，僅僅只有http status code。HTTP狀態碼本身就有足夠的含義，根據http status code就可以知道刪除、添加、修改等是否成功。服務段向用戶返回這些狀態碼並不是一個強制性的約束。簡單點說你可以指定這些狀態，但是不是強制的。常用HTTP狀態碼對照表
HTTP狀態碼也是有規律的
1**請求未成功
2**請求成功、表示成功處理了請求的狀態代碼。
3**請求被重定向、表示要完成請求，需要進一步操作。 通常，這些狀態代碼用來重定向。
4** 請求錯誤這些狀態代碼表示請求可能出錯，妨礙了服務器的處理。
5**（服務器錯誤）這些狀態代碼表示服務器在嘗試處理請求時發生內部錯誤。 這些錯誤可能是服務器本身的錯誤，而不是請求出錯。

HTTP Method詳細解釋返回狀態碼
GET 獲取對象或集合 200成功、401沒有授權、403訪問禁止、404沒有資源、參數錯誤、406請求格式不正確、410資源被刪除、500服務器內部錯誤
POST 新增一條數據 201創建成功、422新增數據驗證錯誤、（401、403、404、406、500）
DELETE 刪除一條數據 204刪除成功、（401、403、404、406、500）
PATCH 更新實體部分信息 201更新成功、422驗證數據錯誤（401、403、404、406、500）
PUT 更新實體所有信息除ID外 201更新成功、422（401、403、404、406、500）

6. 合理使用query parameter
在請求數據時，客戶端經常會對數據進行過濾和分頁等要求，而這些參數推薦采用HTTP Query Parameter的方式實現

比如設計一個最近登陸的所有用戶
https://example.com/api/users?recently_login_day=3

搜索用戶，並按照註冊時間降序

https://example.com/api/users?recently_login_day=3

搜索用戶，並按照註冊時間升序、活躍度降序
https://example.com/api/users?q=key&sort=create_title_asc,liveness_desc
關於分頁，看看博客園開放平臺分頁獲取精華區博文列表

https://api.cnblogs.com/api/blogposts/@picked?pageIndex={pageIndex}&pageSize={pageSize} 
返回示例： 
[ 
{ 
“Id”: 1, 
“Title”: “sample string 2”, 
“Url”: “sample string 3”, 
“Description”: “sample string 4”, 
“Author”: “sample string 5”, 
“BlogApp”: “sample string 6”, 
“Avatar”: “sample string 7”, 
“PostDate”: “2017-06-25T20:13:38.892135+08:00”, 
“ViewCount”: 9, 
“CommentCount”: 10, 
“DiggCount”: 11 
}, 
{ 
“Id”: 1, 
“Title”: “sample string 2”, 
“Url”: “sample string 3”, 
“Description”: “sample string 4”, 
“Author”: “sample string 5”, 
“BlogApp”: “sample string 6”, 
“Avatar”: “sample string 7”, 
“PostDate”: “2017-06-25T20:13:38.892135+08:00”, 
“ViewCount”: 9, 
“CommentCount”: 10, 
“DiggCount”: 11 
} 
]

7. 多表、多參數連接查詢如何設計URL

這是一個比較頭痛的問題，在做單個實體的查詢比較容易和規範操作，但是在實際的API並不是這麽簡單而已，這其中常常會設計到多表連接、多條件篩選、排序等。
比如我想查詢一個獲取在6月份的訂單中大於500元的且用戶地址是北京，用戶年齡在22歲到40歲、購買金額降序排列的訂單列表

https://example.com/api/orders?order_month=6&order_amount_greater=500&address_city=北京&sort=order_amount_desc&age_min=22&age_max=40

從這個URL上看，參數眾多、調用起來還得一個一個仔細對著，而且API本身非常不容易維護，命名看起來不是很容易，不能太長，也不能太隨意。

在.net WebAPI總我們可以使用屬性路由，屬性路由就是講路由附加到特定的控制器或操作方法上裝飾Controll及其使用[Route]屬性定義路由的方法稱為屬性路由。
這種好處就是可以精準地控制URL，而不是基於約定的路由，簡直就是為這種多表查詢量身定制似的的。
從webapi 2開發，現在是RESTful API開發中最推薦的路由類型
我們可以在Controll中標記Route
[Route(“api/orders/{address}/{month}”)]
Action中的查詢參數就只有金額、排序、年齡。減少了查詢參數、API的可讀性和可維護行增強了。

https://example.com/api/orders/beijing/6?order_amount_greater=500&sort=order_amount_desc&age_min=22&age_max=40

這種屬性路由比如在博客園開放的API也有這方面的應用，如獲取個人博客隨筆列表

請求方式：GET 
請求地址：https://api.cnblogs.com/api/blogs/{blogApp}/posts?pageIndex={pageIndex} 
blogApp：博客名

7.API請求授權

博客園的開放平臺API也是基於OAuth2.0，參見理解OAuth2.0，留存分析

我們必須要知道的RESTful服務最佳實踐

相關推薦

我們必須要知道的RESTful服務最佳實踐

客戶 存儲 附加 頁面 set 總結 nth 多表查詢 xamarin 看過很多RESTful相關的文章總結，參齊不齊，結合工作中的使用，非常有必要歸納一下關於RESTful架構方式了，RESTful只是一種架構方式的約束，給出一種約定的標準，完全嚴格遵守RESTful

當我們使用Redis的時候，必須要知道什麽？

全部 實的 詳細 www bbs 計算 緩存 redis3 論壇 當我們在開發過程中需要用到分布式緩存Redis的時候，我們首先要明白緩存在系統中用來做什麽？ 少量數據存儲，高速讀寫訪問。通過數據全部in-momery 的方式來保證高速訪問，同時提供數據落地的功能，實際

「從零單排HBase 06」你必須知道的HBase最佳實踐

前面，我們已經打下了很多關於HBase的理論基礎，今天，我們主要聊聊在實際開發使用HBase中，需要關注的一些最佳實踐經驗。 1.Schema設計七大原則 1）每個region的大小應該控制在10G到50G之間； 2）一個表最好保持在 50到100個 region的規模； 3）每個cell最大不應該超過10

想做OTT-TV/IPTV網絡IP電視直播運營商-你必須要知道的事

OTT-TV IPTV 網絡IP電視、直播 廣播電教系統需求： – 整套系統穩定、可靠； – 支持主從設備堆疊部署，單臺設備最大支持127臺從機； – 支持RTSP/RTMP/HLS等標準的流媒體格式； – 可基於標

做SEO必須要知道如何寫好一篇文章?

效果 搜索結果 用戶 提高 還需 搜索引擎 公司 千萬 那是 文章不僅僅是網站更新而已，網站文章質量好壞，影響著網站的質量度。毫無疑問對網站排名有影響。偽原創如何變成原創，有的人特單純，一篇文章拿過來，這裏插一句，那裏加一句就是偽原創了嗎? 如果是這樣那你網站內容質量度非常

RESTful API 最佳實踐

理解 one isp ice any best log style .html RESTful API 最佳實踐http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.htmlRESTful API

Python 你必須要知道的 Flask

Flask介紹 Flask 是一個輕量級的 web 開發框架, 使用 Python 開發, 上手簡單。 安裝 Flask pip install Flask 第一個 Flask 程式 1、編寫 app.py 檔案內容如下: #encoding: utf-8 # 匯入Flas

學習前端，必須要知道的五個學習建議！

在從事這個行業之前，你必須要去了解這個行業是怎麼樣的情況，以及行業的發展趨勢 學習前端，你要有明確的學習方向，而不是毫無目的的學習，這樣會無法提升你的學習效率 在較多的人都是在網上看教程自學，自學有個弊端就是不繫統，不全面，出去工作，自然就會遇到問題 遇到問題，也沒人給你解決，學習沒有找

web前端之響應式佈局，你必須要知道的

一、前言 響應式Web設計可以讓一個網站同時適配多種裝置和多個螢幕，可以讓網站的佈局和功能隨使用者的使用環境（螢幕大小、輸入方式、裝置/瀏覽器能力）而變化。本文主要介紹一些響應式佈局容易忽略但又很重要的知識點。 二、視口 移動前端中常說的 viewport （視口）就是瀏覽器中用於呈現網

關於Http協議，你必須要知道的

轉自：https://segmentfault.com/a/1190000016751071      引言 HTTP協議是Hyper Text Transfer Protocol（超文字傳輸協議）的縮寫,是用於從全球資訊網伺服器傳輸超文字到本地瀏覽器的傳送協議。HT

學習web前端前你必須要知道這些，讓你少走很多彎路

IT行業是所有行業中能力要求最高的，相應的薪水待遇也是讓人羨慕。想要勝任一份高薪的工作並不那麼容易，新手甚至0基礎的小白想要踏入這一行業需要了解些什麼呢？ 　　在之前的幾年IT行業一度超越了掙錢最多的金融行業，因為如果說在中國所有行業中，給人打工的話，做軟體開發這塊應該是工資提升的最顯著最快的，

入門學習Python必須要知道的知識點

知識點 轉發 如何 psutil 這不 psutil模塊 登陸 大學 本地 Python被譽為全世界高效的編程語言，同時也被稱作是“膠水語言”，那它為何能如此受歡迎，下面我們就來說說Python入門學習的必備知識點，也就是它為何能夠如此受歡迎的原因. 1、Python適用於

【轉載】RESTful API 最佳實踐

作者： 阮一峰 日期： 2018年10月 3日 RESTful 是目前最流行的 API 設計規範，用於 Web 資料介面的設計。 它的大原則容易把握，但是細節不容易做對。本文總結 RESTful 的設計細節，介紹如何設計出易於理解和使用的 API。

手機怎麼錄照片上傳到抖音短視訊，這個必須要知道。

經常玩抖音的朋友可能一直在好奇，有些人上傳的並不是連續的視訊，而是一張一張的照片，並且照片上還有相應的配文，其實原理和上傳的視訊是一樣的，需要提前將這些圖片做成一個圖集的視訊形式，然後在上傳到抖音，那這些圖集是怎樣錄製的呢？ 方法/步驟： 1.首先先在手機設定中找

關於ES模組你必須要知道的一些禁忌(一)

背景 ES Module是JavaScript在ES2015版本開始提供的語言標準級別的模組化方案，在此之前JavaScript一直沒有語言級別的模組化體系。沒有模組化的支援，使用JavaScript開發大型應用將舉步維艱，所以經過大量的實踐，社群制定了一些模組載入方案，最主要的有運行於瀏覽器的AMD方案和

小白怎麼成為全職自媒體人？你必須要知道的幾點！

之前看有大部分學員都是用下班時間或者是課餘時間來操作和運營自媒體，也有學員問到是不是放棄工作來全職做自媒體就能賺到更多錢呢？（在校學生不建議放棄課業來全身心投入。） 首先我們得搞明白一個順序，就是那些全職的自媒體人究竟是先放棄工作再來鑽研操作自媒體的，還是已經鑽

Android基礎篇之Android快速入門--你必須要知道的基礎

1. Activity的理解: 2. Intent的理解 關於IntentFilter 3. Intent的使用:（建立、攜帶資料、讀取資料） 1.建立：      顯式意圖： Intent intent = new Inten

關於響應式佈局必須要知道的

前言 響應式Web設計可以讓一個網站同時適配多種裝置和多個螢幕，可以讓網站的佈局和功能隨使用者的使用環境（螢幕大小、輸入方式、裝置/瀏覽器能力）而變化。本文主要介紹一些響應式佈局容易忽略但又很重要的知識點。 視口 移動前端中常說的 viewport （視口）就是瀏覽器中用於呈現網頁的區域

使用mongoDB必須要知道的備份和恢復資料庫的命令

部分恢復：mongorestore -h 192.168.88.88 -d dris D:MongoDBdataBak88cmlibdris_digital.bson 匯出資料表dris_digital到dris中

雲原生架構下微服務最佳實踐-如何拆分微服務架構