API的設計(1) - 錯誤處理

19 人贊了文章

API的錯誤處理

正常結果 Response

當我們在定義一個函數介面的時候，往往會定義：

• 介面名
• 輸入參數 Reqest
• 返回結果 Response

以java為例，登陸介面定義會是類似：

User login(String username, String password);

異常結果 BizError

上述的介面定義，其實是不妥的，因為它定義了所謂的Happy Path 主流程需要的正常結果 Response；卻沒有定義Sad Path 分支流程所需要的異常結果 Biz Error。

需要注意的是：主流程與分支流程都屬於業務邏輯的一部分，給與分支流程足夠的重視，是軟體成熟度提升的表現。

登陸是完全可能出現分支流程的，比方說，用戶名/密碼錯誤，賬號被屏蔽等等；一個連密碼錯誤處理不了的登陸程序，是非常糟糕的程序。

所以，API的定義可以調整為：

User login(String username, String pass) throw InvalidLoginException, AccountBannedException;

當然，我們也可以把InvalidLoginException跟AccountBannedException都歸為LoginError，然後使用Enum枚舉屬性來區分，那麼介面會變成：

enum ErrorTypes { InvalidLogin = 1; AccountBanned = 2;}Class LoginError { ErrorTypes Error;}User login(String username, String pass) throw LoginError;

常見異常 CommonError

但這依舊不夠，我們實現介面的時候，往往會使用一些框架、中間件，而它們自身又經常帶有一些內置的常見異常 CommonError，比方說：

• APIKeyNotProvided
• InvalidParameter

等等，同樣的，我們也可以把上述歸類為CommonError，那麼API定義會變成：

enum ErrorTypes { InvalidLogin = 1; AccountBanned = 2;}Class LoginException { ErrorTypes Error;}Class FrameworkException { ....}User login(String username, String password) throw LoginError, CommonError;

CommonError與BizError的區別在於後者是針對單一API的，而前者則可能會存在於大部分，甚至所有API。

BizError是由對當前的API提供方的業務代碼返回，需要調用方針對返回的BizError進行處理，然後進入當前業務的分支流程，這樣的流程是需要我們根據業務進行特定編碼；它是與業務邏輯代碼強相關的。

而CommonError被返回時，則可能是跟具體業務無關，它一般是由API提供方使用的框架、中間件直接返回的，調用方收到CommonError時，可能不會進入業務的分支流程，而是進行一些同樣的處理，比方說，提示用戶登錄後操作，或者重新輸入。

它需要被底層綁定的通用代碼，而不是當前的業務代碼處理。

錯誤 Error

程序運行的時候，是可能遇到比異常更加嚴重的Error，比方說：TimeOutError、OutOfMemeryError，甚至SegmentFaultError等等。

API遇到錯誤的時候，無論是提供方還是調用方，幾乎都無法進行任何具體處理，最多由通用代碼打一下日誌，然後提示一下用戶稍後重試。

我們只有把：

• 正常結果
• 異常結果
• 常見異常
• 錯誤

一個成熟的API，需要對這四種四者都考慮進去。

總結

下一節，我會推薦一種通用的API框架/風格 - protoapi，鼓勵按正常結果、異常結果、常見異常、錯誤這四種劃分來定義我們的API。