接上一篇文章《4個(gè)要點(diǎn)，編寫一份接口需求文檔》，本文對(duì)工作中做過的實(shí)例進(jìn)行分析，希望通過實(shí)例能對(duì)接口設(shè)計(jì)需要考慮的因素有更深的理解。

案例1

1. 需求背景

1. SRM系統(tǒng)的用戶，需要在SRM查看自己提供的商品的質(zhì)檢情況；
2. 但是質(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í)間過長而自動(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)很重要：

1. 實(shí)時(shí)性要求極高；
2. 能共用一份信息就不存兩份。

基于實(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)。

案例2

1. 需求背景

1. 采購系統(tǒng)需要給預(yù)測(cè)服務(wù)同步產(chǎn)品的未成功訂貨的數(shù)量，以方便預(yù)測(cè)服務(wù)預(yù)測(cè)后期的采購量；
2. 采購量的預(yù)測(cè)每天一次，每天凌晨開始。

2. 需求設(shè)計(jì)

1. 因?yàn)椴少徚棵刻焖阋淮?，所以在?jì)算前將數(shù)據(jù)同步過去即可，實(shí)時(shí)性要求不高；
2. 因?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ǔ)；
3. 因預(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。

案例3

1. 需求背景

1. 客服系統(tǒng)需要根據(jù)客戶的要求，向商品的供應(yīng)商索取商品操作指南等輔助信息；
2. 因?yàn)榭头到y(tǒng)沒有供應(yīng)商信息，故需要從SRM系統(tǒng)獲取供應(yīng)商信息；
3. 已停止合作的供應(yīng)商應(yīng)排除掉；
4. 供應(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ì)如下：

案例4

1. 需求背景

1. 需求生成服務(wù)需要告訴采購系統(tǒng)采購需求，以讓采購系統(tǒng)下采購訂單；
2. 采購系統(tǒng)對(duì)數(shù)據(jù)的要求根據(jù)不同的情況而不同，這里假設(shè)：A類需求必須有字段a，B類需求不需要有字段a。

2. 需求設(shè)計(jì)

一開始設(shè)計(jì)的文檔的時(shí)候，我是這樣設(shè)計(jì)校驗(yàn)的：

1. A類需求沒有字段a的時(shí)候，返回報(bào)錯(cuò)信息“A需求字段a不能為空”；
2. 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)少了一層，變得更輕更簡單；不會(huì)因?yàn)橐粋€(gè)用不到的信息影響后面的流程。

所以改一下校驗(yàn)邏輯：

1. A類需求沒有字段a的時(shí)候，返回報(bào)錯(cuò)信息“A需求字段a不能為空”；
2. 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是后面流程必須用到的信息，所以必須采用強(qiáng)校驗(yàn)；相反B類采用弱校驗(yàn)即可。

PS：誠然，除了這些問題以外，還有主明細(xì)方式傳輸、分頁、最大量限制等等的點(diǎn)，最好的方式是在搞清楚業(yè)務(wù)需求后，及時(shí)跟開發(fā)同學(xué)做下探討和溝通，聽聽他們的意見和考量（所以處好關(guān)系很重要呀，哈哈）。

#專欄作家#

果果，人人都是產(chǎn)品經(jīng)理專欄作家。擅長業(yè)務(wù)導(dǎo)向性的產(chǎn)品設(shè)計(jì)，以及對(duì)業(yè)務(wù)流程的梳理和復(fù)雜問題的拆解，希望能找到產(chǎn)品工作的操作指南和方法論，不斷搭建自己的知識(shí)體系

本文原創(chuàng)發(fā)布于人人都是產(chǎn)品經(jīng)理。未經(jīng)許可，禁止轉(zhuǎn)載

題圖來自Unsplash, 基于CC0協(xié)議