多終端Restful API框架設(shè)計(jì)研究及圖書(shū)漂流系統(tǒng)應(yīng)用

付敏峰 于林海

摘要：隨著圖書(shū)漂流活動(dòng)思潮傳人國(guó)內(nèi)，不同客戶端平臺(tái)上的圖書(shū)漂流系統(tǒng)層出不窮，缺少一套統(tǒng)一的適用于多終端的解決方案。在移動(dòng)互聯(lián)網(wǎng)應(yīng)用中，WEB API開(kāi)發(fā)是前后端分離WEB應(yīng)用開(kāi)發(fā)的重要方面，結(jié)合MVC設(shè)計(jì)模式，構(gòu)建一套基于REST風(fēng)格的Restful接口應(yīng)用框架，統(tǒng)一接口數(shù)據(jù)呈現(xiàn)格式，開(kāi)發(fā)適用于各種客戶端使用的標(biāo)準(zhǔn)化接口。利用Flask框架定制實(shí)現(xiàn)圖書(shū)漂流系統(tǒng)的Restful API接口，提供網(wǎng)頁(yè)端和小程序端等多終端調(diào)用，提升用戶在不同終端的使用體驗(yàn)。

關(guān)鍵詞：REST風(fēng)格;API接口;RestfulAPI框架;flask框架;圖書(shū)漂流系統(tǒng);多終端

中圖分類號(hào)：TP311 文獻(xiàn)標(biāo)識(shí)碼：A

文章編號(hào)：1009-3044（2020）15-0004-04

1背景

“圖書(shū)漂流”起源于20世紀(jì)60年代的西方國(guó)家，近年來(lái)傳人到中國(guó)，這種不同于圖書(shū)館借閱和書(shū)店購(gòu)買的新方式吸引了許多的年輕用戶群體，并作為一種新的閱讀方式傳人到校園。該活動(dòng)以“分享、信任、傳播”為主旨，有助于培養(yǎng)學(xué)生的共享理念、誠(chéng)信素質(zhì)、奉獻(xiàn)精神等品質(zhì)，是高校校園文化建設(shè)、圖書(shū)館閱讀推廣活動(dòng)的有機(jī)組成部分。高校師生特別是畢業(yè)生擁有豐富的藏書(shū)和閑置圖書(shū)資源，共享經(jīng)濟(jì)下實(shí)現(xiàn)圖書(shū)循環(huán)利用，不僅提高圖書(shū)利用率，提升圖書(shū)的使用價(jià)值，減少資源浪費(fèi)，降低閱讀成本，也能彌補(bǔ)圖書(shū)館館藏圖書(shū)不足。

2圖書(shū)漂流現(xiàn)狀

圖書(shū)館的圖書(shū)共享服務(wù)主要指文獻(xiàn)借閱傳遞、館際互借等方式實(shí)現(xiàn)本館館藏圖書(shū)資源在不同高校圖書(shū)館之間的共享，本文是基于共享理念將個(gè)人閑置的圖書(shū)捐贈(zèng)給需要的師生校友。目前，圖書(shū)漂流作為高校圖書(shū)傳遞共享的另一種方式，圖書(shū)館是圖書(shū)漂流組織者，為教師、學(xué)生捐贈(zèng)的圖書(shū)放置在漂流站，用戶按照漂流規(guī)則取閱。圖書(shū)漂流活動(dòng)能促進(jìn)師生閑置圖書(shū)的共享，激發(fā)學(xué)生的讀書(shū)熱情，增進(jìn)學(xué)生之間的友誼嘲。

因此，業(yè)內(nèi)人士不斷探索圖書(shū)共享活動(dòng)的組織和實(shí)現(xiàn)，結(jié)合移動(dòng)互聯(lián)網(wǎng)平臺(tái)實(shí)現(xiàn)線上線下相結(jié)合的形式。如趙越嘲等設(shè)計(jì)并實(shí)現(xiàn)了高校圖書(shū)共享App，實(shí)現(xiàn)高校全民圖書(shū)隨時(shí)隨地共享。尹明章等借助微信的生態(tài)環(huán)境，利用微信小程序開(kāi)發(fā)高校020圖書(shū)共享平臺(tái)，從控制成本、低投入方面改善用戶體驗(yàn)和使用習(xí)慣。史欣璐基于社交網(wǎng)絡(luò)，采用Web網(wǎng)站和微信公眾平臺(tái)的模式開(kāi)發(fā)了高校的圖書(shū)共享系統(tǒng)，實(shí)現(xiàn)用戶之間的共享、關(guān)注和評(píng)論。趙琰等開(kāi)發(fā)了福建省文獻(xiàn)信息資源共享平臺(tái)“FULink圖書(shū)漂流”移動(dòng)端App，實(shí)現(xiàn)紙質(zhì)圖書(shū)在全省高校之間的漂流共享，諸如此類的應(yīng)用及研究不勝枚舉。隨著移動(dòng)互聯(lián)網(wǎng)應(yīng)用的日益廣泛，移動(dòng)端平臺(tái)層出不窮，微信公眾號(hào)、企業(yè)號(hào)、小程序、釘釘、易班、移動(dòng)圖書(shū)館等平臺(tái)屢見(jiàn)不鮮，這些應(yīng)用都出現(xiàn)在高校信息化發(fā)展歷程的各個(gè)方面，用戶為此需要安裝各類App應(yīng)用，用戶體驗(yàn)不佳。為提升高校信息化水平和適應(yīng)用戶使用習(xí)慣，實(shí)現(xiàn)跨終端平臺(tái)的應(yīng)用，因此，需要研究如何實(shí)現(xiàn)適用于各類客戶端平臺(tái)的跨平臺(tái)圖書(shū)漂移系統(tǒng)，考慮運(yùn)營(yíng)成本等因素，實(shí)現(xiàn)的圖書(shū)漂移系統(tǒng)系狹義的圖書(shū)捐贈(zèng)功能，不再跟蹤圖書(shū)的漂移軌跡。3 Restful API

3.1 REST風(fēng)格

REST（表現(xiàn)層狀態(tài)轉(zhuǎn)換，Representational State Transfer英文縮寫(xiě)）是一種互聯(lián)網(wǎng)應(yīng)用程序的系統(tǒng)架構(gòu)風(fēng)格，它利用URI（universal Resource Identifier，統(tǒng)一資源標(biāo)識(shí)符）定位資源，用HTTP動(dòng)詞描述操作。REST包含資源、表示、狀態(tài)3個(gè)主要內(nèi)容。資源即網(wǎng)絡(luò)世界中一種體現(xiàn)為比特流的實(shí)物或抽象概念，每一個(gè)資源都有唯一的URI標(biāo)識(shí)，通常使用URL表示。表示指資源所呈現(xiàn)出的某種形式，為構(gòu)建松耦合、可擴(kuò)展的Web應(yīng)用提供標(biāo)準(zhǔn)嘲，對(duì)資源的操作是通過(guò)首先獲取該資源的現(xiàn)有表示，然后在內(nèi)部完成從現(xiàn)有狀態(tài)到目標(biāo)狀態(tài)的轉(zhuǎn)變，資源的操作即HTrP動(dòng)詞POST、DELETE、PUT、GET對(duì)應(yīng)的增刪改查四種。狀態(tài)既可以是服務(wù)器端資源狀態(tài)也可以是終端應(yīng)用狀態(tài)，資源的狀態(tài)保存在服務(wù)端，應(yīng)用狀態(tài)由應(yīng)用自身維護(hù)。

REST將客戶端服務(wù)器模式的客戶端用戶界面和服務(wù)器端數(shù)據(jù)存儲(chǔ)所關(guān)心的不同問(wèn)題分離開(kāi)來(lái)，簡(jiǎn)化服務(wù)器部分，改善其可擴(kuò)展性和在不同平臺(tái)上的可移植性。所有交互都是無(wú)狀態(tài)的，每一個(gè)從客戶端到服務(wù)器的調(diào)用請(qǐng)求都要攜帶服務(wù)器處理請(qǐng)求時(shí)所需的全部信息，服務(wù)器端不保留和記憶任何狀態(tài)信息。統(tǒng)一標(biāo)準(zhǔn)交互界面，簡(jiǎn)化架構(gòu)、改善業(yè)務(wù)邏輯之間互動(dòng)關(guān)系的可視性，業(yè)務(wù)邏輯與標(biāo)準(zhǔn)化界面的分離，使客戶端和服務(wù)器各自擴(kuò)展，互不干擾。REST常用簡(jiǎn)單、輕便、易用、可讀性強(qiáng)的JSON數(shù)據(jù)格式作為統(tǒng)一界面標(biāo)準(zhǔn)進(jìn)行交互。

隨著移動(dòng)互聯(lián)網(wǎng)和云服務(wù)應(yīng)用的發(fā)展，REST以其設(shè)計(jì)簡(jiǎn)單、讀取方便、數(shù)據(jù)包傳輸輕便等特點(diǎn)，被越來(lái)越多的開(kāi)發(fā)者所使用，并逐漸用來(lái)取代復(fù)雜而笨重的SOAP Web Service模式。

3.2RestfulAPI內(nèi)容

基于REST實(shí)現(xiàn)的Web架構(gòu)約束的應(yīng)用程序接口即為Restful AP，為不同客戶端開(kāi)發(fā)者提供解決業(yè)務(wù)開(kāi)發(fā)中接口可擴(kuò)展性和終端異構(gòu)性等問(wèn)題。

互聯(lián)網(wǎng)中的資源是一個(gè)個(gè)實(shí)體，其狀態(tài)是隨著時(shí)間不斷發(fā)生變化的時(shí)間函數(shù)，在不同的時(shí)間節(jié)點(diǎn)其內(nèi)容和狀態(tài)是變化的，在不同的應(yīng)用場(chǎng)景或業(yè)務(wù)系統(tǒng)中，對(duì)同一資源所需的內(nèi)容信息是不同的。因此，對(duì)于一個(gè)API接口而言，它可以是一個(gè)資源特定時(shí)間的某些基本信息，也可以是一個(gè)資源組合，或者是一些資源的狀態(tài)和另一些資源鏈接的組合。例如一個(gè)Web網(wǎng)頁(yè)資源除了包含有網(wǎng)頁(yè)的基本靜態(tài)信息外，還包括若干指向其他資源的鏈接。

API的調(diào)用就是一個(gè)資源組合的狀態(tài)返回，即從一個(gè)狀態(tài)的資源組合轉(zhuǎn)換到另一個(gè)資源組合并發(fā)生狀態(tài)改變的過(guò)程。資源狀態(tài)發(fā)送改變時(shí)，某些資源信息被獲取，還有一些資源信息會(huì)被修改，同時(shí)也會(huì)成為新資源組合中的一個(gè)鏈接或組成部分。

3.3RestfulAPI結(jié)構(gòu)

一個(gè)API能將資源組合中的若干資源從一個(gè)狀態(tài)轉(zhuǎn)換到另一個(gè)狀態(tài)，其內(nèi)部結(jié)構(gòu)如下圖1所示。API結(jié)構(gòu)內(nèi)部分別由訪問(wèn)控制、API定義和業(yè)務(wù)邏輯三部分組成，訪問(wèn)控制約定API的開(kāi)放程度、權(quán)限要求以及性能質(zhì)量的監(jiān)控等，API定義部分規(guī)定API的功能作用、訪問(wèn)方式、URL設(shè)計(jì)、參數(shù)約束、返回結(jié)果等，而業(yè)務(wù)邏輯則是完成整個(gè)API功能，實(shí)現(xiàn)業(yè)務(wù)邏輯的主體，通過(guò)與數(shù)據(jù)庫(kù)、業(yè)務(wù)系統(tǒng)、互聯(lián)網(wǎng)或本地的API等資源的交互，進(jìn)行適當(dāng)?shù)倪壿嬏幚?，返回API功能的資源組合。

在互聯(lián)網(wǎng)環(huán)境下，公開(kāi)的API接口僅需要提供給客戶端有關(guān)資源的詳細(xì)信息及其他有關(guān)聯(lián)的信息，而不考慮客戶端獲取資源的用途和業(yè)務(wù)功能。但作為企業(yè)或校園內(nèi)部的API設(shè)計(jì)，不僅要有獲取資源的接口，更重要的是考慮資源如何利用、接口粒度大小如何設(shè)計(jì)才能方便客戶端使用等內(nèi)部業(yè)務(wù)，以便于讓業(yè)務(wù)系統(tǒng)輕松完成業(yè)務(wù)邏輯，而不需要過(guò)多處理接口數(shù)據(jù)。

根據(jù)內(nèi)部業(yè)務(wù)需要和Restful API設(shè)計(jì)原則，將內(nèi)部環(huán)境的API體系結(jié)構(gòu)重新構(gòu)建為多層嵌套的API體系結(jié)構(gòu)。由內(nèi)而外之下而上依次是：面向獨(dú)立的資源數(shù)據(jù)、粒度最小、幾乎不含業(yè)務(wù)的資源API，需要調(diào)用資源API處理相關(guān)邏輯業(yè)務(wù)或功能需求的邏輯功能API，以及直接面向客戶端用戶的，需要對(duì)各終端提供個(gè)性化資源的前端API。結(jié)合MVC設(shè)計(jì)思想，可以將資源API、邏輯API和客戶端API三層演化對(duì)應(yīng)MVC的層級(jí)，如圖2所示。

嵌套關(guān)系的三層API結(jié)構(gòu)是根據(jù)接口的功能和形式進(jìn)行劃分，并非邏輯結(jié)構(gòu)上的分層。各層之間相互串聯(lián)，下層為上層提供服務(wù)、輸出資源，上層從下層取得資源完成自己的使命功能，對(duì)外每層的接口又都作為獨(dú)立的個(gè)體存在，都面向客戶端開(kāi)放，提供接口服務(wù)。

4基于Flask實(shí)現(xiàn)Restfui API框架

4.1 Python Web框架Flask

Flask是目前十分流行的Python語(yǔ)言Web微框架，在GitHub上Flask的Stars數(shù)已上升至49.3K，已超過(guò)同類的Py-thon Web框架Django（47.6K），躍居第一。它是一個(gè)輕量級(jí)的可定制框架，較其他同類型框架更為靈活、輕便、安全且容易上手，可以結(jié)合MVC模式進(jìn)行開(kāi)發(fā)和按需定制。

4.2基于Flask設(shè)計(jì)的Restful API結(jié)構(gòu)

在前后端分離的背景下，現(xiàn)在常用的Web服務(wù)架構(gòu)體系一般根據(jù)結(jié)構(gòu)功能分為數(shù)據(jù)存儲(chǔ)層、業(yè)務(wù)處理層和前端頁(yè)面展示層?；贔lask框架實(shí)現(xiàn)業(yè)務(wù)處理層的所有邏輯功能，從各類應(yīng)用或存儲(chǔ)中獲取資源，建立一個(gè)個(gè)滿足一定功能或設(shè)計(jì)資源的API接口，前端調(diào)用接口實(shí)現(xiàn)其個(gè)性化的業(yè)務(wù)。Flask框架實(shí)現(xiàn)的三層Restful API Web結(jié)構(gòu)體系如下圖3所示。

在RestfulAPI結(jié)構(gòu)體系內(nèi)部，通過(guò)基于JWT的認(rèn)證權(quán)限機(jī)制實(shí)現(xiàn)接口鑒權(quán)管理，包括CMS數(shù)據(jù)管理均統(tǒng)一通過(guò)API進(jìn)行交互?？刂破鲗邮钦麄€(gè)API工作的調(diào)度中心，它將整個(gè)的路由、鑒權(quán)、數(shù)據(jù)的接收和驗(yàn)證、異常處理、業(yè)務(wù)處理、返回結(jié)果等所有工作串聯(lián)起來(lái)。通過(guò)Flask框架的視圖函數(shù)實(shí)現(xiàn)控制器層的工作，裝飾器完成業(yè)務(wù)請(qǐng)求的路由和鑒權(quán)工作，保護(hù)控制器不被惡意調(diào)用和處理額外事務(wù)，使其專注于調(diào)度業(yè)務(wù)處理?？刂破髡{(diào)度的第一項(xiàng)工作就是驗(yàn)證用戶請(qǐng)求參數(shù)，交由統(tǒng)一數(shù)據(jù)驗(yàn)證層實(shí)現(xiàn)參數(shù)的合法性、有效性驗(yàn)證。業(yè)務(wù)模型層完成業(yè)務(wù)相關(guān)的數(shù)據(jù)和邏輯處理，是API業(yè)務(wù)功能實(shí)現(xiàn)的核心。視圖模型層在整個(gè)的框架中不是必不可少的，它根據(jù)客戶端的要求處理業(yè)務(wù)層完成的結(jié)果數(shù)據(jù)，按需將核心數(shù)據(jù)提供給客戶端。JSON序列化即數(shù)據(jù)結(jié)構(gòu)轉(zhuǎn)換，將開(kāi)發(fā)語(yǔ)言中數(shù)據(jù)呈現(xiàn)的結(jié)構(gòu)對(duì)象轉(zhuǎn)換為ison字符串形式返回給客戶端。所有的處理過(guò)程中出現(xiàn)的異常、錯(cuò)誤等統(tǒng)一由AOP統(tǒng)一異常處理層接收并返回。

4.3 Api的Url地址設(shè)計(jì)

使用Url標(biāo)識(shí)網(wǎng)絡(luò)中的唯一資源，一個(gè)Url表示一個(gè)api接口。設(shè)計(jì)一個(gè)Restful Api接口中需要包含REST風(fēng)格中資源標(biāo)識(shí)、接口操作、版本號(hào)、以及結(jié)果識(shí)別等。不同于普通的Web頁(yè)面，接口使用“api”作為Web上下文，使用二級(jí)域名或Api標(biāo)識(shí)，在API的Url中增加版本標(biāo)識(shí)（如v1），資源標(biāo)識(shí)到具體的Api中;形如http：//域名/api/v1/user的接口格式。利用HTTP動(dòng)詞完成API調(diào)用的請(qǐng)求方法操作，REST使用HTYP的狀態(tài)碼識(shí)別API調(diào)用情況。

4.4 HTTP狀態(tài)碼及錯(cuò)誤碼

HTTP狀態(tài)碼常用的如2**表示操作成功，3**表示重定向，4**表示沒(méi)有權(quán)限、無(wú)資源、不被允許等，500一般表示服務(wù)器端出現(xiàn)內(nèi)部錯(cuò)誤，客戶端需要根據(jù)狀態(tài)碼判斷其請(qǐng)求結(jié)果。

對(duì)于API接口調(diào)用結(jié)果除HTTP狀態(tài)碼外，還需要使用JSON統(tǒng)一返回?cái)?shù)據(jù)格式，結(jié)果類型大致可以分成業(yè)務(wù)數(shù)據(jù)信息、操作成功的提示信息、錯(cuò)誤異常信息三類。業(yè)務(wù)數(shù)據(jù)信息反饋接口功能提供的字段信息，有單個(gè)記錄或集合數(shù)據(jù)。錯(cuò)誤異常信息定義的格式需要指明出現(xiàn)錯(cuò)誤的錯(cuò)誤碼、錯(cuò)誤提示以及調(diào)用地址信息。一套完整的接口系統(tǒng)需要有專門(mén)的錯(cuò)誤碼列表，標(biāo)識(shí)每種錯(cuò)誤碼對(duì)應(yīng)出錯(cuò)的原因和相關(guān)解釋說(shuō)明，錯(cuò)誤碼一般是多位的數(shù)字，此處設(shè)為4位。如無(wú)權(quán)限查詢記錄的異常信息：{“errorCode”：1001，“message”：”Forbidden，no permis-sion”，”requestUrl”："GET/vl/used5”}。與錯(cuò)誤異常信息返回格式一致，對(duì)操作成功的提示信息也需要統(tǒng)一定義，如添加一條記錄成功的返回信息：{“errorCode”：O，“message”："success”，”re_questUrl”：“POST/v1/article/add”}。

5圖書(shū)漂流系統(tǒng)

圖書(shū)漂流系統(tǒng)主要利用Flask框架定制開(kāi)發(fā)實(shí)現(xiàn)異構(gòu)終端的RestfulAPI接口，并由微信小程序、Web端調(diào)用實(shí)現(xiàn)的圖書(shū)漂流系統(tǒng)。由用戶管理模塊、圖書(shū)模塊、捐贈(zèng)模塊、索取模塊和圖書(shū)漂移模塊組成，實(shí)現(xiàn)將師生手中閑置的圖書(shū)捐贈(zèng)或共享給需要的用戶，考慮流通等成本因素，平臺(tái)使用用戶實(shí)名認(rèn)證、圖書(shū)線上漂移、線下傳遞的模式。

用戶注冊(cè)要求使用學(xué)校統(tǒng)一身份認(rèn)證實(shí)名認(rèn)證并完善用戶聯(lián)系方式信息，支持不同客戶端的用戶注冊(cè)。圖書(shū)模塊利用網(wǎng)絡(luò)爬蟲(chóng)將用戶搜索到書(shū)籍的封面、介紹等基本信息保存到本地?cái)?shù)據(jù)庫(kù)，禮物清單和索取清單分別存儲(chǔ)有漂移意圖的圖書(shū)ISBN信息和用戶信息。捐贈(zèng)模塊用戶將自己閑置的圖書(shū)作為一個(gè)禮物進(jìn)行上傳，構(gòu)成捐贈(zèng)的禮物清單，相反索取模塊是展示用戶想要的清單。圖4所示為各模塊完成的功能及用戶贈(zèng)送書(shū)籍或索取的路徑。

讀者通過(guò)圖書(shū)模塊搜索圖書(shū)，圖書(shū)詳情展示圖書(shū)外，也列當(dāng)前贈(zèng)送此書(shū)的用戶列表，在詳情頁(yè)讀者根據(jù)需要可將書(shū)籍添加到自己的禮物清單或索取清單，也可以直接向贈(zèng)送此書(shū)的讀者發(fā)送請(qǐng)求。索取清單列出讀者想要的所有書(shū)籍，每本書(shū)后附帶該書(shū)已在禮物清單的所有讀者，并可以向某讀者發(fā)一條請(qǐng)求其贈(zèng)送的通知。禮物清單中的禮物后面列出所有索取該書(shū)籍的讀者，并可以選擇讀者向其發(fā)起贈(zèng)送的圖漂，圖漂建立成功后，通知用戶線下完成。

在圖書(shū)漂移系統(tǒng)中，實(shí)現(xiàn)的若干RestfulAPI如表1列出所示。

6結(jié)束語(yǔ)

標(biāo)準(zhǔn)REST要求將一切資源化，提供標(biāo)準(zhǔn)化的資源屬性返回給用戶，不考慮返回結(jié)果的合理性與實(shí)用性。但在實(shí)際應(yīng)用場(chǎng)景中，除了操作資源外，更多的是利用資源實(shí)現(xiàn)內(nèi)部業(yè)務(wù)功能，REST限制的資源增刪改查操作很難滿足復(fù)雜業(yè)務(wù)的邏輯，為了實(shí)現(xiàn)一個(gè)業(yè)務(wù)邏輯，也許會(huì)多次調(diào)用不同的接口，不僅增加服務(wù)器壓力和前端開(kāi)發(fā)難度，而且資源的粒度也不好掌握。因此為了更好地實(shí)現(xiàn)企業(yè)、學(xué)校等內(nèi)部環(huán)境的REST風(fēng)格API設(shè)計(jì)，吸收其優(yōu)秀的設(shè)計(jì)風(fēng)格和良好的格式約束，但也不拘泥于嚴(yán)格執(zhí)行其不便于實(shí)現(xiàn)功能業(yè)務(wù)邏輯的規(guī)范要求，設(shè)計(jì)的基于FLASK框架的RestfulAPI結(jié)構(gòu)體系，實(shí)現(xiàn)了多終端的圖書(shū)漂流業(yè)務(wù)的接口，適用于各種平臺(tái)調(diào)用數(shù)據(jù)使用，為圖書(shū)漂移輕松擴(kuò)展其他平臺(tái)應(yīng)用提供了API數(shù)據(jù)，為建設(shè)其他移動(dòng)圖書(shū)館、微服務(wù)、輕應(yīng)用等智慧圖書(shū)館應(yīng)用提供了建設(shè)思路。