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，需要對這四種四者都考慮進去。

總結

	正常結果	異常結果	常見異常	錯誤
業務	強相關	強相關	弱相關	無關
返回者	業務程式碼	業務程式碼	框架/中間層	其它
處理者	業務程式碼	業務程式碼	通用程式碼	通用程式碼

	Response	BizError	CommonError	Error
Business Relation	Strong	Strong	Weak	N.A.
Returner	Biz Code	Biz Code	Framework/Middleware	Others
Handler	Biz Code	Biz Code	General Code	General Code

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