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

案例1

1. 需求背景

1. SRM系統的用戶，需要在SRM查看自己提供的商品的質檢情況；
2. 但是質檢的數據在商品管理系統中，故需要SRM從商品管理系統獲取對應的數據

2. 需求設計

需求關鍵點是SRM需要從商品管理系統獲取數據并展示給自己用戶，實現這一點有兩種方式：

（1）SRM固定頻次從商品管理系統獲取

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

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

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

同時，隨著數據量增大，此種情況下很容易出現漏數據和數據重復的情況，數據量太大，程序執行時間過長而自動停止，導致數據遺漏，第一次還沒處理完，第二次已經開始了，結果相同的數據多次寫入，導致數據重復。

故此種方式不可行。

（2）商品管理系統主動同步

既然自己取不可行，那么商品管理系統主動將數據同步到SRM呢？

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

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

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

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

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

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

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

案例2

1. 需求背景

1. 采購系統需要給預測服務同步產品的未成功訂貨的數量，以方便預測服務預測后期的采購量；
2. 采購量的預測每天一次，每天凌晨開始。

2. 需求設計

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

因此接口可設計如下：

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

但是忽略的一個問題是：因為雙方沒有明確約定數據更新方式，導致兩邊數據對不上出了bug。

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

當一個產品前一天同步的未訂數量是34，第二天這個數量更新成了0的時候，接收方沒有將34更新成0，存的還是34。

案例3

1. 需求背景

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

2. 需求設計

（1）考慮到客服系統對狀態有要求，為了更加靈活，我將接口設計如下：

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

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

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

（3）經過兩版分析，我的第三版設計如下：

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

（4）結合以上，最后的設計如下：

案例4

1. 需求背景

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

2. 需求設計

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

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

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

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

那么當B類需求給了字段a的時候，還是正常接收數據，只是不接收字段a。

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

所以改一下校驗邏輯：

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

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

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

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

#專欄作家#

果果，人人都是產品經理專欄作家。擅長業務導向性的產品設計，以及對業務流程的梳理和復雜問題的拆解，希望能找到產品工作的操作指南和方法論，不斷搭建自己的知識體系

本文原創發布于人人都是產品經理。未經許可，禁止轉載

題圖來自Unsplash, 基于CC0協議