## 接口开发 & 规范
### 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.kancloud.cn/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笔记 · 看云](https://www.kancloud.cn/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
- 开始
- 微信小程序
- 获取用户信息
- 记录
- HTML
- HTML5
- 文档根节点
- 你真的了解script标签吗？
- 文档结构
- 已经落后的技术
- form表单
- html实体
- CSS
- css优先级 & 设计模式
- 如何编写高效的 CSS 选择符
- 笔记
- 小计
- flex布局
- 细节体验
- Flex
- Grid
- tailwindcss
- JavaScript
- javascript物语
- js函数定义
- js中的数组对象
- js的json解析
- js中数组的操作
- js事件冒泡
- js中的判断
- js语句声明会提前
- cookie操作
- 关于javascript你要知道的
- 关于innerHTML的试验
- js引擎与GUI引擎是互斥的
- 如何安全的修改对象
- 当渲染引擎遇上强迫症
- 不要使用连相等
- 修改数组-对象
- 算法-函数
- 事件探析
- 事件循环
- js事件循环中的上下文和作用域的经典问题
- Promise
- 最佳实践
- 页面遮罩加载效果
- 网站静态文件之思考
- 图片加载问题
- 路由及转场解决方案
- web app
- 写一个页面路由转场的管理工具
- 谈编程
- 技术/思想的斗争
- 前端技术选型分析
- 我想放点html模板代码
- 开发自适应网页
- 后台前端项目的开发
- 网站PC版和移动版的模板方案
- 前后端分离
- 淘宝前后端分离
- 前后端分离的思考与实践（一）
- 前后端分离的思考与实践（二）
- 前后端分离的思考与实践（三）
- 前后端分离的思考与实践（四）
- 前后端分离的思考与实践（五）
- 前后端分离的思考与实践（六）
- 动画
- 开发小技巧
- Axios
- 屏幕适配
- 理论基础
- 思考
- flexible.js原理
- 实验
- rem的坑，为什么要设置成百分比，为什么又是62.5%
- 为什么以一个标准适配的，其它宽度也能同等适配
- 自适应、响应式、弹性布局、屏幕适配
- 适配：都用百分比？
- 番外篇
- 给你看看0.5px长什么样？
- 用事实证明viewport scale缩放不会改变rem元素的大小
- 为什么PC端页面缩放不会影响rem元素
- 究竟以哪个为设备独立像素
- PC到移动端初试
- 深入理解px
- 响应式之栅格系统
- 深入理解px（二）
- 一篇搞定移动端适配
- flex版栅格布局
- 其他
- 浏览器加载初探
- 警惕你的开发工具
- JS模块化
- webpack
- 打包原理
- 异步加载
- gulp
- 命名规范
- 接口开发
- sea.js学习
- require.js学习
- react学习
- react笔记
- vue学习
- vue3
- 工具、技巧
- 临时笔记
- 怎么维护好开源项目
- 待办
- 对前端MVV*C框架的思考
- jquery问题
- 临时
- 好文
- 节流防抖