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

案例1

1. 需求背景

1. SRM系統(tǒng)的用戶，需要在SRM查看自己提供的商品的質(zhì)檢情況；
2. 但是質(zhì)檢的數(shù)據(jù)在商品管理系統(tǒng)中，故需要SRM從商品管理系統(tǒng)獲取對應(yīng)的數(shù)據(jù)

2. 需求設(shè)計

需求關(guān)鍵點是SRM需要從商品管理系統(tǒng)獲取數(shù)據(jù)并展示給自己用戶，實現(xiàn)這一點有兩種方式：

（1）SRM固定頻次從商品管理系統(tǒng)獲取

選擇這種方式，有一個繞不開的問題：什么時候去取數(shù)據(jù)合適？普遍的自然就想到按固定的頻率，那么這個頻率應(yīng)該是什么？

考慮到用戶隨時都會點擊查看，半小時、一小時的頻率肯定不行；實時性應(yīng)該越高越好，那半分鐘或者1分鐘取一次呢？

這樣做相比半小時實時性高了很多，但考慮到數(shù)據(jù)量的因素，雖然每分鐘會去獲取，但是獲取到數(shù)據(jù)后進(jìn)行合法性校驗、完了組裝存儲，整個周期就遠(yuǎn)不是1分鐘了，有可能用戶點擊的時候，數(shù)據(jù)剛獲取到，還沒處理完存儲到表中，故也無法展示；

同時，隨著數(shù)據(jù)量增大，此種情況下很容易出現(xiàn)漏數(shù)據(jù)和數(shù)據(jù)重復(fù)的情況，數(shù)據(jù)量太大，程序執(zhí)行時間過長而自動停止，導(dǎo)致數(shù)據(jù)遺漏，第一次還沒處理完，第二次已經(jīng)開始了，結(jié)果相同的數(shù)據(jù)多次寫入，導(dǎo)致數(shù)據(jù)重復(fù)。

故此種方式不可行。

（2）商品管理系統(tǒng)主動同步

既然自己取不可行，那么商品管理系統(tǒng)主動將數(shù)據(jù)同步到SRM呢？

當(dāng)商品管理系統(tǒng)的質(zhì)檢信息有變更時，主動將數(shù)據(jù)同步給SRM，用戶在SRM查看的時候，SRM從自己的表中獲取數(shù)據(jù)并展示，這樣看這種方案是完全能夠滿足要求的。

我一開始做的時候，也是選擇的這種方案，但是在與開發(fā)溝通的時候（一般做接口更偏向技術(shù)，所以我都事先會跟開發(fā)私下討論一下），發(fā)現(xiàn)有一個問題：相同的信息有沒有必要在兩個系統(tǒng)存儲兩份？因為質(zhì)檢信息中存在附件文件，文件很占存儲空間。是否有更好的方案來避免這個缺陷？

結(jié)合上面這兩個分析，我們知道這個接口有兩個點很重要：

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

基于實時性要求高這個點，為什么不做成用戶查看的時候，實時去商品管理系統(tǒng)獲取數(shù)據(jù)并展示出來呢？這樣也解決了SRM不用存儲冗余信息的問題。

為此此需求最佳的方案是：當(dāng)用戶在SRM點擊查看的時候，SRM實時去商品管理系統(tǒng)獲取質(zhì)檢信息并展示，無需本地保存：

PS：實時獲取有一個隱形的問題是：并發(fā)。若并發(fā)量高，實時獲取的方式不可取。但此業(yè)務(wù)中，并發(fā)可能性低，所以此方案可行最優(yōu)。

案例2

1. 需求背景

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

2. 需求設(shè)計

1. 因為采購量每天算一次，所以在計算前將數(shù)據(jù)同步過去即可，實時性要求不高；
2. 因為整個預(yù)測過程需要大量的計算，預(yù)測系統(tǒng)必須存儲數(shù)據(jù)方便計算，不可能計算到的時候再來取數(shù)據(jù)，并且不是文件數(shù)據(jù)，占用存儲空間小，所以此數(shù)據(jù)預(yù)測系統(tǒng)必須存儲；
3. 因預(yù)測服務(wù)需要的是全量的數(shù)據(jù)，不用一個個帶著參數(shù)來獲取數(shù)據(jù)。

因此接口可設(shè)計如下：

從表面上看，這個接口設(shè)計沒有問題，完全滿足需要。

但是忽略的一個問題是：因為雙方?jīng)]有明確約定數(shù)據(jù)更新方式，導(dǎo)致兩邊數(shù)據(jù)對不上出了bug。

很明顯，同步方是以全量的方式同步數(shù)據(jù)的，但是接收方在接收數(shù)據(jù)的時候，卻是以增量的方式更新的。

當(dāng)一個產(chǎn)品前一天同步的未訂數(shù)量是34，第二天這個數(shù)量更新成了0的時候，接收方?jīng)]有將34更新成0，存的還是34。

案例3

1. 需求背景

1. 客服系統(tǒng)需要根據(jù)客戶的要求，向商品的供應(yīng)商索取商品操作指南等輔助信息；
2. 因為客服系統(tǒng)沒有供應(yīng)商信息，故需要從SRM系統(tǒng)獲取供應(yīng)商信息；
3. 已停止合作的供應(yīng)商應(yīng)排除掉；
4. 供應(yīng)商需要產(chǎn)品對應(yīng)。

2. 需求設(shè)計

（1）考慮到客服系統(tǒng)對狀態(tài)有要求，為了更加靈活，我將接口設(shè)計如下：

這樣的設(shè)計有個很大的問題是，供應(yīng)商的狀態(tài)客服系統(tǒng)并沒有。假如在預(yù)先實現(xiàn)時，根據(jù)現(xiàn)有狀態(tài)值雙方約定好，但隨著SRM系統(tǒng)的發(fā)展，當(dāng)供應(yīng)商的狀態(tài)值變更或新增時，存在兩邊數(shù)據(jù)不一致和獲取不到數(shù)據(jù)的隱患，所以這樣的設(shè)計不能不說容錯性是很低的。

（2）既然客服系統(tǒng)沒有狀態(tài)值，那它只根據(jù)商品編碼來獲取，我將供應(yīng)商及其狀態(tài)都返回給它不就可以了，為此我的第二版設(shè)計是這樣的：

這樣的設(shè)計其實跟第一版有同樣的問題，即使將狀態(tài)返回給它，它因為不知道這些狀態(tài)的業(yè)務(wù)意義，也就無法過濾掉那些沒用的數(shù)據(jù)只給客服人員展示有效的信息。

（3）經(jīng)過兩版分析，我的第三版設(shè)計如下：

此次的設(shè)計解決了前兩次的問題，但是沒有考慮異常情況：沒有滿足條件的數(shù)據(jù)時，要返回什么來告訴對方為什么沒有數(shù)據(jù)？所以接口還需要一個錯誤信息。

（4）結(jié)合以上，最后的設(shè)計如下：

案例4

1. 需求背景

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

2. 需求設(shè)計

一開始設(shè)計的文檔的時候，我是這樣設(shè)計校驗的：

1. A類需求沒有字段a的時候，返回報錯信息“A需求字段a不能為空”；
2. B類需求有字段a的時候，返回報錯信息“B需求字段a應(yīng)該為空”。

在與開發(fā)溝通的過程中，他們提出：如果B類需求給了字段a，會不會影響后面的流程？

我的回答是：不會，只是這個信息后面流程用不到。

那么當(dāng)B類需求給了字段a的時候，還是正常接收數(shù)據(jù)，只是不接收字段a。

這樣做的好處是：接口校驗少了一層，變得更輕更簡單；不會因為一個用不到的信息影響后面的流程。

所以改一下校驗邏輯：

1. A類需求沒有字段a的時候，返回報錯信息“A需求字段a不能為空”；
2. B類需求有字段a的時候，不接收字段a，但正常接收需要的其他字段。

這里涉及到接口設(shè)計中的校驗，增加校驗的目的是，保證相互通訊的數(shù)據(jù)是正確的，對接收方而言保證自己受到的信息不是垃圾數(shù)據(jù)或因為錯誤而影響后面流程。

但是在設(shè)計校驗規(guī)則時，應(yīng)該有一個強校驗還是弱校驗更合適的考量。正如上文的接口，A類需求的字段a是后面流程必須用到的信息，所以必須采用強校驗；相反B類采用弱校驗即可。

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

#專欄作家#

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

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

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