## 接口開發 & 規范 ### success 無特殊說明時，操作成功時都會返回數據： ```json {"status":1,"msg":""} ``` * * * * * ### error 失敗時都會返回數據： ```json {"errCode":1,"errMsg":""} ``` 所以通過判斷： ```javascript if (typeof res.status != "undefined") { // 成功 alert('status: ' + res.status + ' msg: ' + res.msg); } else { // 失敗 alert('errCode: ' + res.errCode + ' errMsg: ' + res.errMsg); } ``` 就可以知道當前操作是否成功了。 （此外，還可能還會有`data`屬性。） * * * * * ### 注意 切記不要使用： ```javascript if (res.errCode) { # error } if (res.errCode != 0) { # error } ``` 這樣的語句來判斷，因為即使返回失敗結果時，錯誤碼可能也為0，成功狀態碼也可能為0，或者說狀態碼可以使任意值，這個并沒有硬性規定的，**所以只需要記住一個原則，那就是失敗和成功兩種情況，返回的數據字段不一樣。**所以必須嚴格按照上面那種方式判斷。 接口全部采用`JSON`作為數據響應（請求以常規`form data`格式發送即可），系統正確的情況下會保證全部響應以`JSON`返回（`ajax`數據解析格式需要設置為：`dataType: 'json'`），除非系統發生不可控錯誤，請前端開發人員知悉。（請參考下面擴展部分設置監控`ajax`狀態的代碼） >[danger] 以上是常規格式，無特殊情況的話請嚴格遵守規定，如有特殊情況，會另作說明的，具體規則請以實際接口為準。 * * * * * ## 擴展 接口規范很重要，其實數據還有你看不到的部分，你看得到的部分是一個http請求發出去接口有數據回來，其實有你忽略的部分，發送和接受的數據包都是由**包頭和內容**組成的，我們一般只是看到了包數據，其實沒有意識到頭數據的重要性，一般我們感覺不到它的存在，其實前端接觸到了，只不過你沒有意識到而已，比如 `$.ajax(url, {}, function(){}, 'json');` 最后一個參數如果我們省略了，但是如果它檢測到服務端接口返回的是 `Content-Type:application/json; charset=utf-8` 那么也會自動將數據解析成json的，所以此時我們參數省略了程序也能按照期望的運行，但是如果服務端沒有返回這個正確的頭，那么此時你還省略了參數那么就不能按照你期望的自動解析成json了，通過這點我們就能感受到頭信息的威力。所以服務端封裝的接口規范肯定是完善的考慮了這些問題，只有這樣的接口才是符合規范，正確的接口。 * * * * * ### 其它需要理解和注意的問題： **Q：接口只返回失敗和成功兩種結果嗎？** **A：是的，接口每次只會返回這兩種結果之中的一種。** 其實成功和失敗兩種結果并不是說是系統錯誤，或者操作失敗的意思，比如獲取不存在的文章會返回失敗，或者用戶沒有權限查看該文章也會返回失敗，這種失敗和成功實質是一種情景下操作反饋，是由應用業務邏輯決定的，并不是說是系統錯誤或者本次操作失敗的意思的，返回失敗并不是真正的操作失敗，而是業務邏輯反饋出來信息，請仔細理解這點。 ``` 微信支付甚至把這兩種分開了： if ($result->return_code == 'SUCCESS' && $result->result_code == 'SUCCESS') { } else { } 可以理解為，返回代碼和結果代碼，其實返回代碼永遠是 SUCCESS，只要是服務端有返回，而不是500了，所以這樣感覺其實沒什么意義。 ``` **不可控的錯誤需要監控ajax的狀態：** ```javascript // 注冊全局ajax失敗控制 $.ajaxSetup({ error:function(x, e) { layer.open({content: '抱歉，服務忙！'}); return false; } }); ``` * * * * * ### 擴展 - [開發筆記](http://www.hmoore.net/x-web/tv-dingtalk/274769) - [了解大規模網關系統，你需要掌握的來自阿里巴巴、京東、蘑菇街和廣發證券的4個案例](http://mp.weixin.qq.com/s/X9w4s8b_6hYsHrUwJG5CsQ) - [REST 架構該怎么生動地理解？](https://www.zhihu.com/question/27785028) - [如何獲取（GET）一杯咖啡——星巴克REST案例分析](http://www.infoq.com/cn/articles/webber-rest-workflow/) - [理解RESTful架構](http://www.ruanyifeng.com/blog/2011/09/restful.html) - [GraphQL初探:從REST到GraphQL，更完善的數據查詢定義 - 某熊的全棧之路 - SegmentFault](https://segmentfault.com/a/1190000005766732) - [GraphQL 初體驗：GraphQL + Node.js - 簡書](https://www.jianshu.com/p/0343b83e0cbb) - [Facebook 的 GraphQL 為何沒有火起來? - 知乎](https://www.zhihu.com/question/38596306/answer/268893511) - [GraphQL | 一種為你的 API 而生的查詢語言](http://graphql.cn/) - [GitHub 為什么開放了一套 GraphQL 版本的 API？ | Laravel China 社區 - 高品質的 Laravel 開發者社區](https://laravel-china.org/topics/3112/why-did-github-open-a-graphql-version-of-api) - [PHPRAP 1.0.0 發布，打造PHP版API接口管理系統！](https://mp.weixin.qq.com/s/sb5ce2nFzsCVdg9Lme0wDQ) - [使用 React 和 GraphQL 做一個todo list](http://mp.weixin.qq.com/s/ekxOHuyKfXzU_D0nt_Kxcw) - [阻礙你使用 GraphQL 的十個問題](https://mp.weixin.qq.com/s/iUwASaBzDmbKBVtvJTNvCA) - [前端每周清單: GraphQL安全加固，去中心化的Web](http://mp.weixin.qq.com/s/2HNlNuDcHJx99dPLiZRrfA) > GraphQL API 的安全加固: GraphQL 讓前端能夠便捷，乃至隨心所欲地進行數據查詢，這樣保證了 API 的靈活性，但也帶來了一定的安全隱患。除去合法的，有效的查詢，惡意的攻擊者可能會提交很多耗時的、嵌套多層的查詢，從而耗光你的服務器、數據庫、網絡以及其他的計算與存儲資源。本文中，Spectrum CTO 為我們分享了他們在生產環境下是如何對 GraphQL API 進行安全加固的；更多相關資料參考 GraphQL Reference。 [RAP是一個可視化接口管理工具](http://rapapi.org/org/index.do) [RAP2 Delores](http://rap2.taobao.org/) [Easy Mock](https://easy-mock.com/) [Myjson - A simple json storage and hosting service](http://myjson.com/) > 方便好用的在線API json數據服務 [5分鐘了解swagger - CSDN博客](http://blog.csdn.net/i6448038/article/details/77622977) [PHPRAP——打造PHP版RAP接口文檔管理系統](http://www.phprap.com/) [REST架構風格與RESTFUL API設計最佳實踐](http://mp.weixin.qq.com/s/-6lCJ0dEhiHGOzV_1xr0TA) > 無狀態這一約束，即通信過程本質上應該是無狀態的。即客戶端向服務端發起的每個請求都必須包含足夠信息來使客戶端準確地表達請求含義，同時客戶端不能利用儲存在服務器端的任何上下文，會話狀態必須全部保存在客戶端。舉個簡單的例子，你正在瀏覽此文，服務端并不關心你是誰，只關心請求是否能有權限查看此文而已。你有權限，我則給你展示，你沒有，則不展示。**至于你有沒有登錄，服務端針對此次的請求是不關心。** [Laravel 開發 RESTful API 的一些心得](http://mp.weixin.qq.com/s/L4yvMg1or4uuk_1M8loF4g) [我所理解的接口設計](http://mp.weixin.qq.com/s/k6EwYVNadRAX0aJyW5A6LA) [老生常談重放攻擊的概念(必看篇) - CSDN博客](https://blog.csdn.net/heluan123132/article/details/74375304) >[danger] 重放攻擊（Replay Attacks）又稱重播攻擊、回放攻擊或新鮮性攻擊（Freshness Attacks），是指攻擊者發送一個目的主機已接收過的包，來達到欺騙系統的目的。這種攻擊會不斷惡意或欺詐性地重復一個有效的數據傳輸。 > > 解決方案：1. 令牌使用一次就過期； 2. 時間戳：A接收一個消息當且僅當其包含一個對A而言足夠接近當前時刻的時戳（但還不是絕對的安全，如果攻擊者截獲后立馬實施重放，就無法辨別攻擊）；3. 序號：增加一個參數，雙方協定變更方法；4. 提問與應答：類似于防止表單重復提交的`__token__`和解決跨站請求偽造攻擊的`__token__`，這種方式都需要“適用性──用于連接性的對話”，即用戶要先請求服務器獲取這個`隨機因子`；（注意，__token__ 后端這個是驗證一次就失效的，每次獲取都是一個新的。這點很重要，要說出來。） [安全 · php筆記 · 看云](http://www.hmoore.net/xiak/php-node/570226) [語義化版本 2.0.0 | Semantic Versioning](https://semver.org/lang/zh-CN/) ~~~ 版本格式：主版本號.次版本號.修訂號，版本號遞增規則如下： 1. 主版本號：當你做了不兼容的 API 修改； 2. 次版本號：當你做了向下兼容的功能性新增； 3. 修訂號：當你做了向下兼容的問題修正。 4. 先行版本號 & 版本編譯信息：先行版本號及版本編譯信息可以加到“主版本號.次版本號.修訂號”的后面，作為延伸。 **所以 接口版本號 只需要一個主版本號就可以了，因為接口只關注對外的接口嘛，而不需要關心后面的兼容/修訂等等。** 每次commit哈希為修訂版本號: a3510908987c391906c238f2770ac8f062366310 ~~~ [給 Web 開發人員推薦的文檔生成工具](https://mp.weixin.qq.com/s/nPx81RgsBczboNT9__d3Vw) [eoLinker接口管理平臺](https://www.eolinker.com) [這應該是postman最詳細的中文使用教程了 - 簡書](https://www.jianshu.com/p/77f4f9175028) [apiDoc - Inline Documentation for RESTful web APIs](http://apidocjs.com/) [為什么Facebook的API以一個循環作為開頭？](https://mp.weixin.qq.com/s/WHh9v3icCc90PwiLyv0Hng) [Rest相比GraphQL有什么好處？--景安網絡](https://server.zzidc.com/fwqcjwt/2538.html) [為什么RESTful很糟糕？](https://mp.weixin.qq.com/s/lmtcMxyOCGB11syWbG0e_g) [GraphQL-前端開發的利劍與橋梁](https://mp.weixin.qq.com/s/7di8WG9xSc_TAh1zbls4zQ) [你不得不知道的HTTP狀態碼有哪些](https://mp.weixin.qq.com/s/tDJBdI9-cxbbbL0aCkd8Iw) [GraphQL服務器](https://zhangwei.online/fullstack/zh/part8/graph_ql%E6%9C%8D%E5%8A%A1%E5%99%A8) * * * * * update time：2018-7-31 17:41:54