用產品思維設計API(四)——隨意定義錯誤碼,你還在這樣幹?
用產品思維設計API(四)——版本控制,沒有你想的這麼簡單
前言
最近公司內部在重構專案程式碼,包括API方向的重構,期間遇到了很多的問題,不由得讓我重新思考了下。
- 一個優雅的API該如何設計?
- 前後端分離之後,API真的解耦分離了嗎?
- 不斷的版本迭代,API的相容性該如何做?ps.這裡所說的API僅為Web API,提供APP\WEB開發使用。
年前,我司內部的介面已經進入了一個完全的重構階段,參考了市面上各大平臺的API和文件,自己也總結出了很多的心得。這裡向大家分享一下,接下來一個月,我們向從下面幾個方面向大家介紹一個優雅的API(至少我認為挺優雅)該如何設計。
ps. 打一個廣告,公司內部現在在招聘各種技術崗位,Java、Android、前端等,待遇保證能讓你漲30%,有興趣的朋友可以加韜哥的微信(微訊號:stchou_zst),二維碼在文章最後。
為什麼API要定義錯誤碼?
這還用廢話,基本就是定義一下在API請求的時候使用是否錯誤的提示唄。
先看看我們現有的錯誤碼:
錯誤碼 | 錯誤描述 | 解決方案 |
---|---|---|
-1 | 系統錯誤 | 系統內部錯誤,請直接聯絡技術支援 |
10001 | userId過期 | 賬號過期 |
10002 | password格式錯誤 | 密碼格式錯誤 |
10003 | password錯誤 | 密碼錯誤 |
10004 | 請求沒有簽名 | 請使用協議規範對請求中的引數進行簽名 |
10005 | 登入次數受限 | 等會兒再登入 |
有什麼不妥嗎?乍一看並不覺得啊。
ok,開發完後使用的時候,就會發現。
提示語,居然是後端給我們直接返回回來的,“userid是啥?”、“userid is lost~我改如何操作?”,給使用者的體驗特別不好。很多時候我們的提示語句需要賣賣萌,或者欲蓋彌彰。需要提示的語句並不是伺服器返回的語句。
那這個登入過期例子來說,服務端返回:
{
"request" : "/getUserInfo",
"error_code" : "-10015" ,
"error" : "userid is expire"
}
APP進行操作:
- 提示登入過期,重新登入
- 清空儲存的使用者資訊
- 跳轉到登入介面
我們就會發現,對於不同的錯誤碼,我們有些需要將服務端返回的資訊進行彈窗提示,有些有不需要提示。有些錯誤不僅僅需要提示,還需要在提示後做一些相應的操作,如清空本地快取等內容。
這裡我們做了一個簡單的總結,對於錯誤碼的功能來說,分為以下幾種情況
- 做對應的操作
- 做對應的提示
- 遮蔽性的僅提示
沒錯,除了方便開發人員進行後臺查詢以外,客戶端研發就只關心這麼多。
重新設計錯誤碼
根據之前的經驗來說,這麼我們就可以很好得設計了。
- 定義錯誤提示級別,1為服務端返回提示、2為不提示、3隱藏性賣萌提示。
- 定義具體的錯誤模組,登入相關/訂單相關/產品相關
- 具體錯誤編號,自增即可,一個專案9999種錯誤應該夠用;
如,對於錯誤碼20502 來說
第1位 | 2~3位 | 4~7位 |
---|---|---|
2 | 05 | 0002 |
錯誤提示級別,不提示 | 服務模組程式碼 | 具體錯誤程式碼 |
返回的資訊是:
{
"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