接口定義備忘錄

接口規(guī)范的意義

接口是用于數(shù)據(jù)的交互壹堰，接口文檔是供需雙方的開(kāi)發(fā)規(guī)范脐瑰。移動(dòng)應(yīng)用接口是移動(dòng)設(shè)備和業(yè)務(wù)之間進(jìn)行通信的途徑霍掺。實(shí)質(zhì)就是以特定的規(guī)則通過(guò)接口直接操作數(shù)據(jù)庫(kù)的增刪改查赌蔑。接口文檔往往是在需求評(píng)審?fù)瓿芍缶托枰_(kāi)始編寫(xiě)的，并盡快文檔定下來(lái)，良好的接口文檔能有效減少開(kāi)發(fā)人員的溝通成本梧喷。

接口分類(lèi)

（一）查詢(xún)類(lèi)接口

查詢(xún)類(lèi)接口是指客戶端傳遞一些參數(shù)固逗，服務(wù)端根據(jù)參數(shù)依據(jù)需求，前往數(shù)據(jù)庫(kù)查詢(xún)需要的結(jié)果返回?cái)?shù)據(jù)的一類(lèi)接口。返回類(lèi)型一般有兩種。第一種是返回一個(gè)對(duì)象，第二種是返回一個(gè)數(shù)組對(duì)象涕蜂。
a.第一種比如登陸，客戶端把用戶名密碼上傳到接口映琳，服務(wù)器返回用戶的個(gè)人信息机隙。
b.第二種比如獲取客戶，客戶端把用戶的身份信息上傳到接口萨西，服務(wù)器返回此身份下的所有客戶數(shù)組集合黍瞧。

（二）操作類(lèi)接口

操作類(lèi)接口是指客戶端通過(guò)接口進(jìn)行一些增刪改的操作。比如新增一個(gè)客戶原杂，修改客戶信息印颤，或者刪除一個(gè)客戶。服務(wù)器一般返回執(zhí)行的狀態(tài)（成功/失敶┮蕖）年局，有的需要返回執(zhí)行結(jié)果的一些信息，比如新增客戶后咸产，返回客戶的ID矢否。

（三）上傳下載類(lèi)接口

上傳下載類(lèi)接口是涉及到文件傳輸?shù)慕涌凇１热缟蟼黝^像脑溢，需要上傳圖片到服務(wù)器僵朗，服務(wù)端根據(jù)需求響應(yīng)保存并返回結(jié)果赖欣。比如客戶端需要顯示用戶頭像，需要讀取網(wǎng)絡(luò)圖片文件验庙，在手機(jī)上進(jìn)行顯示顶吮。定義這類(lèi)接口時(shí)要注意是否有必要限定上傳文件的的大小。

（四）推送類(lèi)接口

除了客戶端主動(dòng)去請(qǐng)求服務(wù)端粪薛，獲取需要信息之外悴了。有時(shí)候，也存在服務(wù)端有消息需要通知客戶端的情況违寿，這時(shí)候就是服務(wù)端向客戶端發(fā)送消息湃交。這類(lèi)需求可以通過(guò)客戶端短時(shí)間內(nèi)循環(huán)請(qǐng)求解決，也可以通過(guò)第三方專(zhuān)業(yè)推送解決藤巢。也可以通過(guò)自己使用socket或者xmpp等協(xié)議進(jìn)行開(kāi)發(fā)搞莺。

接口編寫(xiě)原則

（一）實(shí)用性

1．?dāng)?shù)據(jù)格式：推薦使用JSON格式數(shù)據(jù)，因?yàn)镴SON有較好的跨平臺(tái)性掂咒，以及數(shù)據(jù)格式占用字節(jié)數(shù)較少腮敌，當(dāng)然也可采用XML、TEXT作為程序開(kāi)發(fā)輔助俏扩。

2．接口響應(yīng)時(shí)間：APP有別于WEB服務(wù)，對(duì)服務(wù)器端要求是比較嚴(yán)格的弊添，在移動(dòng)端有限的帶寬條件下录淡，要求接口響應(yīng)速度要快，所有在開(kāi)發(fā)過(guò)程中盡量選擇效率高的框架油坝。

3．?dāng)?shù)據(jù)量：按需分配嫉戚，APP客戶端需要什么數(shù)據(jù)就返回什么數(shù)據(jù)，過(guò)多的數(shù)據(jù)量影響處理速度澈圈，最重要的是影響傳輸效率和浪費(fèi)用戶流量彬檀。

4．API緩存：這點(diǎn)比較重要，不管是文件緩存還是memcache緩存瞬女。

（二）易用性

1．接口窍帝、參數(shù)命名準(zhǔn)確：論是接口還是參數(shù)，命名都應(yīng)該有意義诽偷，讓人一目了然坤学。

2．接口拆分合理：如果不是復(fù)雜的頁(yè)面，盡可能就使用一個(gè)接口报慕；在很多的APP頁(yè)面都有廣告深浮、焦點(diǎn)圖、文章列表等眠冈，對(duì)于這些不同格式的數(shù)據(jù)飞苇，不可能都分配一個(gè)接口，這樣加大了APP請(qǐng)求接口數(shù)，影響響應(yīng)速度布卡。建議服務(wù)器端盡可能處理好數(shù)據(jù)后通過(guò)一個(gè)接口返回給APP客戶端雨让。

3．接口數(shù)據(jù)、狀態(tài)：接口必須提供明確的數(shù)據(jù)狀態(tài)信息羽利，不管是成功的宫患，還是失敗的，都必須返回給APP客戶端这弧。

4．可擴(kuò)展：方便后期功能性調(diào)整娃闲，接口應(yīng)具備可擴(kuò)展性。

（三）安全性

1．接口安全：目前一般都是在APP客戶端和服務(wù)器通過(guò)約定的算法匾浪，對(duì)傳遞的參數(shù)值進(jìn)行驗(yàn)證匹配皇帮。但是如果APP程序被反編譯，這些約定的算法就會(huì)暴露蛋辈，特別是在安卓APP中属拾，有了算法，完全就可以通過(guò)驗(yàn)證模擬接口請(qǐng)求冷溶。

2．加密規(guī)范：在傳遞用戶名密碼時(shí)渐白，應(yīng)采用規(guī)范的加密算法如MD5、RSA逞频、DES纯衍，進(jìn)行數(shù)據(jù)通信請(qǐng)求。

3．接口版本控制：對(duì)于接口版本控制苗胀，需要應(yīng)對(duì)不斷的APP版本升級(jí)襟诸，新、舊接口的處理基协，因而需要關(guān)注接口版本控制歌亲。

4．時(shí)間戳：接口請(qǐng)求和響應(yīng)都加時(shí)間戳，通過(guò)對(duì)時(shí)間戳的驗(yàn)證澜驮，可以一定程度上防止重放攻擊陷揪。

接口設(shè)計(jì)原則

1．盡量減少參數(shù)傳遞：在客戶端發(fā)起HTTP請(qǐng)求接口操作時(shí)，應(yīng)減少參數(shù)傳遞杂穷，如某些操作只需要ID不需要其他參數(shù)鹅龄，這時(shí)候就應(yīng)該只傳遞ID這個(gè)參數(shù)。

2．盡量避免接口重復(fù)性：在客戶端APP調(diào)用接口時(shí)亭畜，盡量提高接口復(fù)用性扮休，減少HTTP請(qǐng)求，提高程序穩(wěn)定性拴鸵。

3．?dāng)?shù)據(jù)類(lèi)型規(guī)范：客戶端APP調(diào)用接口時(shí)玷坠，應(yīng)標(biāo)注參數(shù)數(shù)據(jù)類(lèi)型蜗搔，以及是否可為空或者默認(rèn)字段，如標(biāo)注了Int型字段八堡，就不能返回“null”的String類(lèi)型字段樟凄，否則容易造成程序APP出現(xiàn)數(shù)據(jù)類(lèi)型解析異常。

4．設(shè)置調(diào)用html頁(yè)面單獨(dú)列表：調(diào)用html頁(yè)面應(yīng)標(biāo)明是否傳遞安全校驗(yàn)參數(shù)兄渺，建議表格中采用是或者否單獨(dú)字段標(biāo)識(shí)缝龄。

5．編碼規(guī)范：整個(gè)API接口開(kāi)發(fā)過(guò)程中，應(yīng)標(biāo)注接口編碼方式挂谍，目前建議采用UTF-8編碼叔壤，UTF-8通用性以及URL請(qǐng)求方面都較規(guī)范。

6．請(qǐng)求方式：編寫(xiě)API接口應(yīng)該標(biāo)注請(qǐng)求方式口叙，請(qǐng)求方式一般有GET和POST方式

7．GET和POST方式：在數(shù)量較小情況下可以使用GET方式炼绘，但數(shù)據(jù)量超過(guò)1024字節(jié)就應(yīng)該采用POST方式，避免出現(xiàn)請(qǐng)求失敗或者請(qǐng)求異常的問(wèn)題妄田。

8．返回接口調(diào)用狀態(tài)：所有API接口都應(yīng)該統(tǒng)一標(biāo)識(shí)調(diào)用的成功失敗信息和規(guī)范錯(cuò)誤編碼信息俺亮，以及必要的提示字段信息。

9．安全機(jī)制：接口應(yīng)規(guī)范驗(yàn)證簽名機(jī)制疟呐，用戶登錄后統(tǒng)一調(diào)用KEY對(duì)接口安全驗(yàn)證脚曾。（關(guān)于KEY機(jī)制需由接口開(kāi)發(fā)人員定義），對(duì)于安全系數(shù)要求較高的接口應(yīng)該使用HTTPS請(qǐng)求启具，比如支付接口本讥，訂單接口，用戶信息接口富纸。

10．參數(shù)說(shuō)明：應(yīng)標(biāo)注參數(shù)名稱(chēng)、是否必選旨椒、數(shù)據(jù)類(lèi)型及范圍晓褪、說(shuō)明以及“否（必選）”傳遞默認(rèn)的參數(shù)。

文檔編寫(xiě)規(guī)范

接口文檔應(yīng)該包含的幾大類(lèi)信息：目錄综慎、文檔修訂歷史涣仿、名詞解釋、數(shù)據(jù)類(lèi)型示惊、系統(tǒng)出入?yún)⒑酶邸⒔涌诿枋觥⒓s定參數(shù)米罚、常見(jiàn)響應(yīng)碼說(shuō)明钧汹。接口文檔要清晰、明了录择，包含多少個(gè)接口拔莱，每個(gè)接口的地址碗降、參數(shù)、請(qǐng)求方式塘秦、數(shù)據(jù)交換格式讼渊、返回值等都要寫(xiě)清楚，對(duì)于字段參數(shù)應(yīng)采用表格的形式規(guī)范說(shuō)明尊剔。每一版的接口文檔都應(yīng)該有與需求文檔對(duì)應(yīng)的版本號(hào)爪幻。

1．清晰的目錄：目錄的編寫(xiě)是為了APP開(kāi)發(fā)人員快速定位需要的接口信息，使開(kāi)發(fā)人員在最短的時(shí)間內(nèi)找到需要的接口须误，同時(shí)也會(huì)對(duì)編寫(xiě)API接口人員后期的維護(hù)修改提高效率挨稿。

2．文檔修訂歷史：記錄日期、文檔版本霹期、修改內(nèi)容叶组、修訂人等信息，每一版變更的內(nèi)容應(yīng)該以紅色文字標(biāo)記历造，便于閱讀甩十，如下圖。

3．名詞解釋?zhuān)簩?duì)文檔中一些關(guān)鍵字的解釋?zhuān)奖阍诰帉?xiě)特定業(yè)務(wù)接口時(shí)直接使用吭产，無(wú)需再進(jìn)行說(shuō)明侣监。

4．?dāng)?shù)據(jù)類(lèi)型：基本數(shù)據(jù)類(lèi)型，如下圖臣淤。

5．符號(hào)定義：強(qiáng)制域橄霉、條件域和選用域，如下圖邑蒋。

6．系統(tǒng)請(qǐng)求參數(shù)：操作系統(tǒng)姓蜂、手機(jī)唯一標(biāo)識(shí)碼、當(dāng)前客戶端版本號(hào)医吊、手機(jī)系統(tǒng)版本號(hào)钱慢、手機(jī)型號(hào)、數(shù)字簽名卿堂、接口版本號(hào)束莫，如下圖表。

7．系統(tǒng)響應(yīng)參數(shù)：響應(yīng)碼草描、響應(yīng)消息和業(yè)務(wù)數(shù)據(jù)览绿，如下圖表。

8．業(yè)務(wù)接口描述信息：接口名稱(chēng)穗慕、接口描述饿敲、請(qǐng)求方式、測(cè)試地址逛绵、生產(chǎn)地址诀蓉、備注栗竖。
? ? ? 參數(shù)說(shuō)明：參數(shù)名、含義渠啤、類(lèi)型狐肢、長(zhǎng)度、必填沥曹、備注份名。
? ? ? 參數(shù)格式：請(qǐng)求參數(shù)格式、響應(yīng)參數(shù)格式妓美。

8．常見(jiàn)響應(yīng)碼：約定的常見(jiàn)系統(tǒng)錯(cuò)誤碼僵腺，如下圖。