4個(gè)真實(shí)案例看接口文檔的設(shè)計(jì)要點(diǎn)

4個(gè)真實(shí)案例，看接口文檔的設(shè)計(jì)要點(diǎn)接上一篇文章《4個(gè)要點(diǎn)，編寫一份接口需求文檔》，本文對(duì)工作中做過的實(shí)例進(jìn)行分析，希望通過實(shí)例能對(duì)接口設(shè)計(jì)需要考慮的因素有更深的理解。案例11.需求背景SRM系統(tǒng)的用戶，需要在SRM查看自己提供的商品的質(zhì)檢情況；但是質(zhì)檢的數(shù)據(jù)在商品管理系統(tǒng)中，故需要SRM從商品管理系統(tǒng)獲取對(duì)應(yīng)的數(shù)據(jù)2.需求設(shè)計(jì)需求關(guān)鍵點(diǎn)是SRM需要從商品管理系統(tǒng)獲取數(shù)據(jù)并展示給自己用戶，實(shí)現(xiàn)這一點(diǎn)有兩種方式：（1）SRM固定頻次從商品管理系統(tǒng)獲取選擇這種方式，有一個(gè)繞不開的問題：什么時(shí)候去取數(shù)據(jù)合適？普遍的自然就想到按固定的頻率，那么這個(gè)頻率應(yīng)該是什么？考慮到用戶隨時(shí)都會(huì)點(diǎn)擊查看，半小時(shí)、一小時(shí)的頻率肯定不行；實(shí)時(shí)性應(yīng)該越高越好，那半分鐘或者1分鐘取一次呢？這樣做相比半小時(shí)實(shí)時(shí)性高了很多，但考慮到數(shù)據(jù)量的因素，雖然每分鐘會(huì)去獲取，但是獲取到數(shù)據(jù)后進(jìn)行合法性校驗(yàn)、完了組裝存儲(chǔ)，整個(gè)周期就遠(yuǎn)不是1分鐘了，有可能用戶點(diǎn)擊的時(shí)候，數(shù)據(jù)剛獲取到，還沒處理完存儲(chǔ)到表中，故也無法展示；同時(shí)，隨著數(shù)據(jù)量增大，此種情況下很容易出現(xiàn)漏數(shù)據(jù)和數(shù)據(jù)重復(fù)的情況，數(shù)據(jù)量太大，程序執(zhí)行時(shí)間過長(zhǎng)而自動(dòng)停止，導(dǎo)致數(shù)據(jù)遺漏，第一次還沒處理完，第二次已經(jīng)開始了，結(jié)果相同的數(shù)據(jù)多次寫入，導(dǎo)致數(shù)據(jù)重復(fù)。故此種方式不可行。（2）商品管理系統(tǒng)主動(dòng)同步既然自己取不可行，那么商品管理系統(tǒng)主動(dòng)將數(shù)據(jù)同步到SRM呢？當(dāng)商品管理系統(tǒng)的質(zhì)檢信息有變更時(shí)，主動(dòng)將數(shù)據(jù)同步給SRM，用戶在SRM查看的時(shí)候，SRM從自己的表中獲取數(shù)據(jù)并展示，這樣看這種方案是完全能夠滿足要求的。我一開始做的時(shí)候，也是選擇的這種方案，但是在與開發(fā)溝通的時(shí)候（一般做接口更偏向技術(shù)，所以我都事先會(huì)跟開發(fā)私下討論一下），發(fā)現(xiàn)有一個(gè)問題：相同的信息有沒有必要在兩個(gè)系統(tǒng)存儲(chǔ)兩份？因?yàn)橘|(zhì)檢信息中存在附件文件，文件很占存儲(chǔ)空間。是否有更好的方案來避免這個(gè)缺陷？結(jié)合上面這兩個(gè)分析，我們知道這個(gè)接口有兩個(gè)點(diǎn)很重要：實(shí)時(shí)性要求極高；能共用一份信息就不存兩份。基于實(shí)時(shí)性要求高這個(gè)點(diǎn)，為什么不做成用戶查看的時(shí)候，實(shí)時(shí)去商品管理系統(tǒng)獲取數(shù)據(jù)并展示出來呢？這樣也解決了SRM不用存儲(chǔ)冗余信息的問題。為此此需求最佳的方案是：當(dāng)用戶在SRM點(diǎn)擊查看的時(shí)候，SRM實(shí)時(shí)去商品管理系統(tǒng)獲取質(zhì)檢信息并展示，無需本地保存：PS：實(shí)時(shí)獲取有一個(gè)隱形的問題是：并發(fā)。若并發(fā)量高，實(shí)時(shí)獲取的方式不可取。但此業(yè)務(wù)中，并發(fā)可能性低，所以此方案可行最優(yōu)。案例21.需求背景采購(gòu)系統(tǒng)需要給預(yù)測(cè)服務(wù)同步產(chǎn)品的未成功訂貨的數(shù)量，以方便預(yù)測(cè)服務(wù)預(yù)測(cè)后期的采購(gòu)量；采購(gòu)量的預(yù)測(cè)每天一次，每天凌晨開始。2.需求設(shè)計(jì)因?yàn)椴少?gòu)量每天算一次，所以在計(jì)算前將數(shù)據(jù)同步過去即可，實(shí)時(shí)性要求不高；因?yàn)檎麄€(gè)預(yù)測(cè)過程需要大量的計(jì)算，預(yù)測(cè)系統(tǒng)必須存儲(chǔ)數(shù)據(jù)方便計(jì)算，不可能計(jì)算到的時(shí)候再來取數(shù)據(jù)，并且不是文件數(shù)據(jù)，占用存儲(chǔ)空間小，所以此數(shù)據(jù)預(yù)測(cè)系統(tǒng)必須存儲(chǔ)；因預(yù)測(cè)服務(wù)需要的是全量的數(shù)據(jù)，不用一個(gè)個(gè)帶著參數(shù)來獲取數(shù)據(jù)。因此接口可設(shè)計(jì)如下：從表面上看，這個(gè)接口設(shè)計(jì)沒有問題，完全滿足需要。但是忽略的一個(gè)問題是：因?yàn)殡p方?jīng)]有明確約定數(shù)據(jù)更新方式，導(dǎo)致兩邊數(shù)據(jù)對(duì)不上出了bug。很明顯，同步方是以全量的方式同步數(shù)據(jù)的，但是接收方在接收數(shù)據(jù)的時(shí)候，卻是以增量的方式更新的。當(dāng)一個(gè)產(chǎn)品前一天同步的未訂數(shù)量是34，第二天這個(gè)數(shù)量更新成了0的時(shí)候，接收方?jīng)]有將34更新成0，存的還是34。案例31.需求背景客服系統(tǒng)需要根據(jù)客戶的要求，向商品的供應(yīng)商索取商品操作指南等輔助信息；因?yàn)榭头到y(tǒng)沒有供應(yīng)商信息，故需要從SRM系統(tǒng)獲取供應(yīng)商信息；已停止合作的供應(yīng)商應(yīng)排除掉；供應(yīng)商需要產(chǎn)品對(duì)應(yīng)。2.需求設(shè)計(jì)（1）考慮到客服系統(tǒng)對(duì)狀態(tài)有要求，為了更加靈活，我將接口設(shè)計(jì)如下：這樣的設(shè)計(jì)有個(gè)很大的問題是，供應(yīng)商的狀態(tài)客服系統(tǒng)并沒有。假如在預(yù)先實(shí)現(xiàn)時(shí)，根據(jù)現(xiàn)有狀態(tài)值雙方約定好，但隨著SRM系統(tǒng)的發(fā)展，當(dāng)供應(yīng)商的狀態(tài)值變更或新增時(shí)，存在兩邊數(shù)據(jù)不一致和獲取不到數(shù)據(jù)的隱患，所以這樣的設(shè)計(jì)不能不說容錯(cuò)性是很低的。（2）既然客服系統(tǒng)沒有狀態(tài)值，那它只根據(jù)商品編碼來獲取，我將供應(yīng)商及其狀態(tài)都返回給它不就可以了，為此我的第二版設(shè)計(jì)是這樣的：這樣的設(shè)計(jì)其實(shí)跟第一版有同樣的問題，即使將狀態(tài)返回給它，它因?yàn)椴恢肋@些狀態(tài)的業(yè)務(wù)意義，也就無法過濾掉那些沒用的數(shù)據(jù)只給客服人員展示有效的信息。（3）經(jīng)過兩版分析，我的第三版設(shè)計(jì)如下：此次的設(shè)計(jì)解決了前兩次的問題，但是沒有考慮異常情況：沒有滿足條件的數(shù)據(jù)時(shí)，要返回什么來告訴對(duì)方為什么沒有數(shù)據(jù)？所以接口還需要一個(gè)錯(cuò)誤信息。（4）結(jié)合以上，最后的設(shè)計(jì)如下：案例41.需求背景需求生成服務(wù)需要告訴采購(gòu)系統(tǒng)采購(gòu)需求，以讓采購(gòu)系統(tǒng)下采購(gòu)訂單；采購(gòu)系統(tǒng)對(duì)數(shù)據(jù)的要求根據(jù)不同的情況而不同，這里假設(shè)：A類需求必須有字段a，B類需求不需要有字段a。2.需求設(shè)計(jì)一開始設(shè)計(jì)的文檔的時(shí)候，我是這樣設(shè)計(jì)校驗(yàn)的：A類需求沒有字段a的時(shí)候，返回報(bào)錯(cuò)信息“A需求字段a不能為空”；B類需求有字段a的時(shí)候，返回報(bào)錯(cuò)信息“B需求字段a應(yīng)該為空”。在與開發(fā)溝通的過程中，他們提出：如果B類需求給了字段a，會(huì)不會(huì)影響后面的流程？我的回答是：不會(huì)，只是這個(gè)信息后面流程用不到。那么當(dāng)B類需求給了字段a的時(shí)候，還是正常接收數(shù)據(jù)，只是不接收字段a。這樣做的好處是：接口校驗(yàn)少了一層，變得更輕更簡(jiǎn)單；不會(huì)因?yàn)橐粋€(gè)用不到的信息影響后面的流程。所以改一下校驗(yàn)邏輯：A類需求沒有字段a的時(shí)候，返回報(bào)錯(cuò)信息“A需求字段a不能為空”；B類需求有字段a的時(shí)候，不接收字段a，但正常接收需要的其他字段。這里涉及到接口設(shè)計(jì)中的校驗(yàn)，增加校驗(yàn)的目的是，保證相互通訊的數(shù)據(jù)是正確的，對(duì)接收方而言保證自己受到的信息不是垃圾數(shù)據(jù)或因?yàn)殄e(cuò)誤而影響后面流程。但是在設(shè)計(jì)校驗(yàn)規(guī)則時(shí)，應(yīng)該有一個(gè)強(qiáng)校驗(yàn)還是弱校驗(yàn)更合適的考量。正如上文的接口，A類需求的字段a是后