用產品思維設計API（四）——版本控制，沒有你想的這麼簡單

前言

最近公司內部在重構專案程式碼，包括API方向的重構，期間遇到了很多的問題，不由得讓我重新思考了下。
- 一個優雅的API該如何設計？
- 前後端分離之後，API真的解耦分離了嗎？
- 不斷的版本迭代，API的相容性該如何做？

ps.這裡所說的API僅為Web API，提供APP\WEB開發使用。

年前，我司內部的介面已經進入了一個完全的重構階段，參考了市面上各大平臺的API和文件，自己也總結出了很多的心得。這裡向大家分享一下，接下來一個月，我們向從下面幾個方面向大家介紹一個優雅的API（至少我認為挺優雅）該如何設計。

ps. 打一個廣告，公司內部現在在招聘各種技術崗位，Java、Android、前端等，待遇保證能讓你漲30%，有興趣的朋友可以加韜哥的微信（微訊號：stchou_zst），二維碼在文章最後。

為什麼API要定義錯誤碼？

這還用廢話，基本就是定義一下在API請求的時候使用是否錯誤的提示唄。

先看看我們現有的錯誤碼：

有什麼不妥嗎？乍一看並不覺得啊。

ok，開發完後使用的時候，就會發現。

提示語，居然是後端給我們直接返回回來的，“userid是啥？”、“userid is lost~我改如何操作？”，給使用者的體驗特別不好。很多時候我們的提示語句需要賣賣萌，或者欲蓋彌彰。需要提示的語句並不是伺服器返回的語句。

那這個登入過期例子來說，服務端返回：

{
    "request" : "/getUserInfo",
    "error_code" : "-10015"
 
,
    "error" : "userid is expire"
}

APP進行操作：
- 提示登入過期，重新登入
- 清空儲存的使用者資訊
- 跳轉到登入介面

我們就會發現，對於不同的錯誤碼，我們有些需要將服務端返回的資訊進行彈窗提示，有些有不需要提示。有些錯誤不僅僅需要提示，還需要在提示後做一些相應的操作，如清空本地快取等內容。

這裡我們做了一個簡單的總結，對於錯誤碼的功能來說，分為以下幾種情況

1. 做對應的操作
2. 做對應的提示
3. 遮蔽性的僅提示

沒錯，除了方便開發人員進行後臺查詢以外，客戶端研發就只關心這麼多。

重新設計錯誤碼

根據之前的經驗來說，這麼我們就可以很好得設計了。

• 定義錯誤提示級別，1為服務端返回提示、2為不提示、3隱藏性賣萌提示。
• 定義具體的錯誤模組，登入相關/訂單相關/產品相關
• 具體錯誤編號，自增即可，一個專案9999種錯誤應該夠用；

如，對於錯誤碼20502 來說

返回的資訊是：

{
    "request" : "/statuses/homeTimeline",
    "error_code" : "20502",
    "error" : "Need you follow uid."
}

這個介面返回的錯誤資訊，就是使用上的錯誤，不應該提示。

寫在後面，最近剛過完年了，公司業務繁忙，重構任務重大，更新部落格也慢了。希望大家多多包涵。

@author zhoushengtao(周聖韜)
@since 2017年1月31日 19：36
@weixin stchou_zst
@blog http://blog.csdn.net/yzzst