RESTful接口风格

原文地址

原文链接

前言

互联网开发流程，简单来说，一般都是从立项到产品方案，到界面设计和技术方案，然后是前后端开发/联调/冒烟，接着测试/回归测试/产品走查，最后确定上线方案，包括服务顺序，容灾等

我认为，对于开发人员而言，进入新的环境，最需要适应的可能就是联调步骤，尤其是和不熟悉的前/后端进行联调，其他的不论是技术方案还是上线方案，或者是冒烟/测试支持，都相对有一个可循的统一标准。但是联调的出现的问题很大程度来自于前端和后端对于产品的理解，如果出现偏差对于我这种没什么耐心的人而言，会相对烦躁很多，另一个方面就是对于接口本身的设计而言了，而RESTful此时就可以作为标准（起码保证你在吵架的时候不会落于下风😉）

REST

Representational State Transfer，REST是2000年被Roy Fielding提出，主要是为了松耦合的网络应用程序设计的统一的架构风格，具体可以参考Representational State Transfer。如果需要定义一个RESTful的API我们一般只需要满足以下条件（即REST的6个指导原则）：

• 接口规则统一：一般通过以下约束实现

  • 资源可以被唯一键定位，客户端和服务端交流时，保证交流的资源对象有唯一标识
  • 通过陈述操作资源：陈述/表示（representation）可以理解为接口的一种抽象，我们需要使用这种陈述来操作服务器中的资源信息
  • 资源携带操作：客户端在传递资源的时候需要携带足够信息，表达如何处理资源
  • 使用超媒体触发操作：客户端应该使用超链接的方式获取资源，延申用户操作逻辑

  简单来说，就是你小子接口规则定义地统一一点，别一会创建用POST一会用PUT

• C/S模式：即数据和展示解耦，前后端分离，保证移植复用性

• 无状态：每次请求都是独立的，非业务逻辑上不依赖上下请求

• 可缓存：客户端可以在允许下，存储之前的请求结果以复用，提高性能

• 分层：系统由层级构建，拒绝跨层访问，同样是为了保证移植复用性，当某层修改时候只需要考虑上下层的交互

• 按需编码：允许客户端通过获取/执行服务端脚本代码的方式，简化客户端逻辑

这样看起来，其实REST相对抽象，而且只要我们正常写接口，无论写成什么样，哪怕你全都用POST来表达请求的，也是RESTful风格的API，只要保证接口规则的统一即可

但是这样是不能解决我们在前后端交流中的问题的，我们需要一个大家都认同的严格方案。下面就是我们一般讨论RESTful风格时候会聊的内容，有些地方根据地域不同有细微偏差，毕竟这个东西也确实没有明确统一标准，但如果完全按照这个写法，基本上是谁说你不是严格的RESTful你可以大嘴巴抽他的程度

RESTful API in HTTP

Items

• 资源：一般指可以由URI（Uniform Resource Identifier）标识的主要资源，可以是单个也可以是多个，在URL中通过单复数形式区隔

HTTP method

• GET：幂等，用于获取资源，不改变资源
• POST：非幂等，创建资源
• PUT：幂等，全量更新现有资源
• DELETE：幂等，用于删除资源
• PATCH：幂等，用于资源部分更新

HTTP Response Code

• 200：Ok，成功
• 201：Created，成功，并且创建了资源
• 202：Accepted，执行队列排队中
• 204：No Content，成功但是不返回任何内容，不包含消息正文
• 400：Bad Rquest，请求本身有错误，参数错误/缺失等
• 404：Not Found，资源未找到，可以是链接不正确，也可以是业务资源未找到

Best Practices

• URL中资源操作时使用名词，不使用动词，动词由Http Method表达概念，使用path parameters表达资源，如果需要表达某个特殊行为的时候使用POST+query parameters

  GET /website-creation/articles
  GET /website-creation/articles/{id}
  GET /website-creation/articles/documents/readme
  POST /website-creation/articles
  POST /user/login/message?action=send
  

• 使用正斜杠表达层级关系

  GET /website-creation/articles/{id}/tags/{tagId}
  

• 在URL使用连字符增加可读性

  GET /website-creation/articles/{id}/tags/{tagId}
  

• 使用query parameters表达过滤条件

  GET /website-creation/articles?offset=0&limit=10&name=spring
  

• 不要使用下划线

• 不要在URL末尾增加正斜杠产生歧义

• 不要使用大写字母

• 不要使用文件拓展名，使用Content-Type标识文件类型

最后

其实我们发现，如果严格遵守我们聊的这种RESTful API其实还是蛮烦的一件事情，但是好处是，如果你习惯了这种方式可以让你和前/后端在在对于API应该怎么定这个方面立于不败之地

然而，平心而论，我曾经在设设计的陷阱聊过，设计的目的是保证业务正常高效运作，包括目前阶段的高效以及后续阶段的高效，单纯只是这样而已，所以如果你们公司有自己的一套API设计方案，只要是符合REST基本原则的，就可以称之为是RESTful的，哪怕全部使用POST请求，哪怕HTTP状态只有200和400，都是没有问题的。完全不用担心不规范，我看过一些大厂的新代码，只用POST和GET处理所有请求，甚至多参数使用POST完成GET工作也并不罕见

前后端因为API设计发生争执，大多数情况下都是某一方对于某些写法不熟悉而已，那么作为后端，在对接新前端的时候尽量保证按照严格规范来，虽然有时候会稍微麻烦一些，对于前端来说，应该多熟悉一些不同的写法，比如POST使用query参数，使用POST进行获取操作，注意下path参数和query参数的调用等等，不用大惊小怪。熟悉之后，那么就可以选择双方都相对比较便利的写法啦

原文地址

原文链接