Restful --- 让JSON回归单纯

时间 2019-12-08

原文原文链接

设计模式才是软件哲学的根本。。git

一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件能够更简洁，更有层次，更易于实现缓存等机制。github

http的api设计艺术一直是个争论不休的命题，话说，api接口本无标准，（确实没有标准）可是正确的设计模式和行业规范可以大大的方便用户和其余开发者，同时开发新项目的时候减小本身思考的时间。我之前也很讨厌学习了解规范，认为它约束了咱们的代码，减小了自由度，可是在工做中你不得不遵循团队的开发模式。就如同material design pattern同样，虽然它给艺术强加了一个‘标准’，可是你们都很喜欢她。json

Restful api，Representational State Transfer，就是api领域的一个规范，也是由http2.0开发者提出的一种通用方法，自从使用这主公规范之后，我发现开发小型网站的效率一会儿上去了。。。设计模式

请求方法的设计

http的经典作法是两个传递方向：请求和回应，请求的request有经典的method之选：api

GET：读取（Read）
POST：新建（Create）
PUT：更新（Update）
PATCH：更新（Update），一般是部分更新
DELETE：删除（Delete）

很遗憾的是，绝大多数人都只用前两个promise

这是个很悲剧的现象，和http的创始人的构想相距甚远，确实，只用post或者get彻底能偶实现大多数应用，可是几乎全部的请求服务都分为增删改查（CRUD），而method就是为这个而设计的，若是不用method，你就得在url路径中制定哪一种服务，好比：缓存

/getAllUsers
/addNewUser
/dropOneUser
/setManyUsers

这简直太丑陋了！！服务器

RESTful 的核心思想就是，客户端发出的数据操做指令都是"动词 + 宾语"的结构。好比，GET /articles这个命令，GET是动词，/articles是宾语。restful

因而可知，充分利用标准才能减小代码量，使得逻辑更通顺，更可扩展架构

面向对象的思想

谈完了request，在谈谈http body体的设计：

这里主要是面向对象，即将body（json对象）中全部零碎的数据封装成一个个对象，若是只有一个对象就不须要引用名

设计公共API响应布局的目的是平衡消费者的易用性和提供者的稳定性承诺。咱们能够依赖各类疯狂的元数据和嵌入式值，咱们会后悔多年后保留它们，好比复杂的分页方案，这些方案不能扩展到不断扩展的域空间，或者当咱们最终成为Web Scale并浪费数百万的额外带宽时从那个表情符号汤咱们认为包装每一个条目将是热闹的。

这个思想和函数参数列表是相通的（多参数封装对象，单参数直接使用）

那些不适合CRUD的行为呢？

假如一个操做既get又set，这种组合是事情变得模糊的地方，既属于set也属于get。有不少例子：

将操做重组为显示为资源字段。若是操做不采用参数，则此方法有效。例如，激活动做能够映射到布尔激活的字段，并经过PATCH更新到资源。
将其视为具备RESTful原则的子资源。例如，GitHub的API让你用PUT / gists /：id / star和unstar与DELETE / gists /：id / star打造一个要点。
有时你真的没法将动做映射到合理的RESTful结构。例如，多资源搜索实际上没有意义应用于特定资源的端点。在这种状况下，即便它不是资源，/ search也会最有意义。这不要紧 - 只需从API使用者的角度作正确的事情，并确保明确记录以免混淆。

状态代码设计艺术

终于谈到response了，http返回包最重要是状态吗，请求只有几种，但返回结果有无数种可能，HTTP 状态码就是一个三位数，分红五个类别。

1xx：相关信息

2xx：操做成功

3xx：重定向

4xx：客户端错误

5xx：服务器错误

这五大类总共包含100多种状态码，覆盖了绝大部分可能遇到的状况。每一种状态码都有标准的（或者约定的）解释，客户端只需查看状态码，就能够判断出发生了什么状况，因此服务器应该返回尽量精确的状态码。

状态码对应请求的method，不少人有一个恶习就是状态通通不考虑，统统200，可是错误信息卸载json中，好比：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "not ok",
    code:1
  "info": {
    "error": "Permission Denied !!"
  }
}

这种习惯是很是恶心的，好好的状态代码你不用，非要自定义，不是有病吗？要知道，fetch获得http第一个分组的时候就解析了response的promise，这时候就能够经过http头部的状态码来识别是否成功，若是非要自定协议就得等到http（流）彻底结束后才能知道是否发生了错误，这是很是低效率的作法，虽然response对象还在试验阶段，可是随着投票人数的增多，很快会成为标准化，大胆地用吧！

骚操做

restful的大体艺术就是如上，可见REST和CRUD仍是很经典的概念，和unix定义的操做系统基本元素同样，几十年内是不会过期的，上米娜说到的规范固然不是所有，咱们还能够在api中添加一些彩蛋，充分利用上面讲到的全部的http元素来实现本身的骚操做，好比api的wiki：

API 的使用者未必知道，URL 是怎么设计的。一个解决方法就是，在回应中，给出相关连接，便于下一步操做。这样的话，用户只要记住一个 URL，就能够发现其余的 URL。这种方法叫作 HATEOAS。

举例来讲，GitHub 的 API 都在 api.github.com 这个域名。访问它，就能够获得其余 URL。不信你能够点击试一试

关于restful风格和rpc风格的api设计和公司同事有过争论，感受是主义之争，不会有什么结果。不过关于rest风格，在实际应用中，也遇到过难处理的问题，好比，client验证用户名或者电话是否存在，就不知如何设计怎么好，最后“强行”设计成：GET /users/checking(validating)?username=xx，反却是，rpc风格，GET /users.check?username=xx是否表达力更强一些。再如，某个操做致使状态更新，总结下，就是对于有很强的“动做”在内的api，restful风格并不彻底适用，只是稍微有点麻烦。

综上所述，合理的restful设计能够知足平常生活中99%的需求，让开发者感到‘ very restful’