restful 架构详解

时间 2019-12-06

原文原文链接

场景：由于本身作的后台，一直有为前端提供接口，一直知道用的是restful框架，但是没有深刻理解，先整理以下。html

转载自：http://kb.cnblogs.com/page/512047/前端

http://kb.cnblogs.com/page/521718/java

1. 什么是RESTgit

　　REST全称是Representational State Transfer，中文意思是表述（编者注：一般译为表征）性状态转移。它首次出如今2000年Roy Fielding的博士论文中，Roy Fielding是HTTP规范的主要编写者之一。他在论文中提到：“我这篇文章的写做目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，获得一个功能强、性能好、适宜通讯的架构。REST指的是一组架构约束条件和原则。” 若是一个架构符合REST的约束条件和原则，咱们就称它为RESTful架构。github

　　REST自己并无创造新的技术、组件或服务，而隐藏在RESTful背后的理念就是使用Web的现有特征和能力，更好地使用现有Web标准中的一些准则和约束。虽然REST自己受Web技术的影响很深，可是理论上REST架构风格并非绑定在HTTP上，只不过目前HTTP是惟一与REST相关的实例。因此咱们这里描述的REST也是经过HTTP实现的REST。web

　　2. 理解RESTful算法

　　要理解RESTful架构，须要理解Representational State Transfer这个词组究竟是什么意思，它的每个词都有些什么涵义。下面咱们结合REST原则，围绕资源展开讨论，从资源的定义、获取、表述、关联、状态变迁等角度，列举一些关键概念并加以解释。数据库

资源与URI
统一资源接口
资源的表述
资源的连接
状态的转移

　　2. 1 资源与URIjson

　　REST全称是表述性状态转移，那究竟指的是什么的表述? 其实指的就是资源。任何事物，只要有被引用到的必要，它就是一个资源。资源能够是实体(例如手机号码)，也能够只是一个抽象概念(例如价值) 。下面是一些资源的例子：api

某用户的手机号码
某用户的我的信息
最多用户订购的GPRS套餐
两个产品之间的依赖关系
某用户能够办理的优惠套餐
某手机号码的潜在价值

　　要让一个资源能够被识别，须要有个惟一标识，在Web中这个惟一标识就是URI(Uniform Resource Identifier)。 URI既能够当作是资源的地址，也能够当作是资源的名称。若是某些信息没有使用URI来表示，那它就不能算是一个资源，只能算是资源的一些信息而已。URI的设计应该遵循可寻址性原则，具备自描述性，须要在形式上给人以直觉上的关联。这里以github网站为例，给出一些还算不错的URI：

https://github.com/git
https://github.com/git/git
https://github.com/git/git/blob/master/block-sha1/sha1.h
https://github.com/git/git/commit/e3af72cdafab5993d18fae056f87e1d675913d08
https://github.com/git/git/pulls
https://github.com/git/git/pulls?state=closed
https://github.com/git/git/compare/master…next

　　下面让咱们来看看URI设计上的一些技巧:

使用_或-来让URI可读性更好

　　曾经Web上的URI都是冰冷的数字或者无心义的字符串，但如今愈来愈多的网站使用_或-来分隔一些单词，让URI看上去更为人性化。例如国内比较出名的开源中国社区，它上面的新闻地址就采用这种风格，如http://www.oschina.net/news/38119/oschina-translate-reward-plan。

使用/来表示资源的层级关系

　　例如上述/git/git/commit/e3af72cdafab5993d18fae056f87e1d675913d08就表示了一个多级的资源，指的是git用户的git项目的某次提交记录，又例如/orders/2012/10能够用来表示2012年10月的订单记录。

使用?用来过滤资源

　　不少人只是把?简单的当作是参数的传递，很容易形成URI过于复杂、难以理解。能够把?用于对资源的过滤，例如/git/git/pulls用来表示git项目的全部推入请求，而/pulls?state=closed用来表示git项目中已经关闭的推入请求，这种URL一般对应的是一些特定条件的查询结果或算法运算结果。

,或;能够用来表示同级资源的关系

　　有时候咱们须要表示同级资源的关系时，可使用,或;来进行分割。例如哪天github能够比较某个文件在随意两次提交记录之间的差别，或许可使用/git/git /block-sha1/sha1.h/compare/e3af72cdafab5993d18fae056f87e1d675913d08;bd63e61bdf38e872d5215c07b264dcc16e4febca做为URI。不过，如今github是使用…来作这个事情的，例如/git/git/compare/master…next。

　　2. 2 统一资源接口

　　RESTful架构应该遵循统一接口原则，统一接口包含了一组受限的预约义的操做，不论什么样的资源，都是经过使用相同的接口进行资源的访问。接口应该使用标准的HTTP方法如GET，PUT和POST，并遵循这些方法的语义。

　　若是按照HTTP方法的语义来暴露资源，那么接口将会拥有安全性和幂等性的特性，例如GET和HEAD请求都是安全的，不管请求多少次，都不会改变服务器状态。而GET、HEAD、PUT和DELETE请求都是幂等的，不管对资源操做多少次，结果老是同样的，后面的请求并不会产生比第一次更多的影响。

　　下面列出了GET，DELETE，PUT和POST的典型用法:

　　GET

安全且幂等
获取表示
变动时获取表示（缓存）

200（OK） - 表示已在响应中发出

204（无内容） - 资源有空表示
301（Moved Permanently） - 资源的URI已被更新
303（See Other） - 其余（如，负载均衡）
304（not modified）- 资源未更改（缓存）
400 （bad request）- 指代坏请求（如，参数错误）
404 （not found）- 资源不存在
406 （not acceptable）- 服务端不支持所需表示
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务端当前没法处理请求

　　POST

不安全且不幂等
使用服务端管理的（自动产生）的实例号建立资源
建立子资源
部分更新资源
若是没有被修改，则不过更新资源（乐观锁）

200（OK）- 若是现有资源已被更改

201（created）- 若是新资源被建立
202（accepted）- 已接受处理请求但还没有完成（异步处理）
301（Moved Permanently）- 资源的URI被更新
303（See Other）- 其余（如，负载均衡）
400（bad request）- 指代坏请求
404 （not found）- 资源不存在
406 （not acceptable）- 服务端不支持所需表示
409 （conflict）- 通用冲突
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
415 （unsupported media type）- 接受到的表示不受支持
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务当前没法处理请求

　　PUT

不安全但幂等
用客户端管理的实例号建立一个资源
经过替换的方式更新资源
若是未被修改，则更新资源（乐观锁）

200 （OK）- 若是已存在资源被更改

201 （created）- 若是新资源被建立
301（Moved Permanently）- 资源的URI已更改
303 （See Other）- 其余（如，负载均衡）
400 （bad request）- 指代坏请求
404 （not found）- 资源不存在
406 （not acceptable）- 服务端不支持所需表示
409 （conflict）- 通用冲突
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
415 （unsupported media type）- 接受到的表示不受支持
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务当前没法处理请求

　　DELETE

不安全但幂等
删除资源

200 （OK）- 资源已被删除

301 （Moved Permanently）- 资源的URI已更改
303 （See Other）- 其余，如负载均衡
400 （bad request）- 指代坏请求
404 （not found）- 资源不存在
409 （conflict）- 通用冲突
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务端当前没法处理请求

　　下面咱们来看一些实践中常见的问题:

POST和PUT用于建立资源时有什么区别?

　　POST和PUT在建立资源的区别在于，所建立的资源的名称(URI)是否由客户端决定。例如为个人博文增长一个java的分类，生成的路径就是分类名/categories/java，那么就能够采用PUT方法。不过不少人直接把POST、GET、PUT、DELETE直接对应上CRUD，例如在一个典型的rails实现的RESTful应用中就是这么作的。我认为，这是由于rails默认使用服务端生成的ID做为URI的缘故，而很多人就是经过rails实践REST的，因此很容易形成这种误解。

客户端不必定都支持这些HTTP方法吧?

　　的确有这种状况，特别是一些比较古老的基于浏览器的客户端，只能支持GET和POST两种方法。在实践上，客户端和服务端均可能须要作一些妥协。例如rails框架就支持经过隐藏参数_method=DELETE来传递真实的请求方法，而像Backbone这样的客户端MVC框架则容许传递_method传输和设置X-HTTP-Method-Override头来规避这个问题。

统一接口是否意味着不能扩展带特殊语义的方法?

　　统一接口并不阻止你扩展方法，只要方法对资源的操做有着具体的、可识别的语义便可，并可以保持整个接口的统一性。像WebDAV就对HTTP方法进行了扩展，增长了LOCK、UPLOCK等方法。而github的API则支持使用PATCH方法来进行issue的更新，例如:

　　PATCH /repos/:owner/:repo/issues/:number

　　不过，须要注意的是，像PATCH这种不是HTTP标准方法的，服务端须要考虑客户端是否可以支持的问题。

统一资源接口对URI有什么指导意义?

　　统一资源接口要求使用标准的HTTP方法对资源进行操做，因此URI只应该来表示资源的名称，而不该该包括资源的操做。通俗来讲，URI不该该使用动做来描述。例如，下面是一些不符合统一接口要求的URI:

GET /getUser/1
POST /createUser
PUT /updateUser/1
DELETE /deleteUser/1

　　若是GET请求增长计数器，这是否违反安全性?

　　安全性不表明请求不产生反作用，例如像不少API开发平台，都对请求流量作限制。像github，就会限制没有认证的请求每小时只能请求60次。但客户端不是为了追求反作用而发出这些GET或HEAD请求的，产生反作用是服务端“自做主张”的。另外，服务端在设计时，也不该该让反作用太大，由于客户端认为这些请求是不会产生反作用的。

直接忽视缓存可取吗?

　　即便你按各个动词的本来意图来使用它们，你仍能够轻易禁止缓存机制。最简单的作法就是在你的HTTP响应里增长这样一个报头： Cache-control: no-cache。可是，同时你也对失去了高效的缓存与再验证的支持(使用Etag等机制)。对于客户端来讲，在为一个REST式服务实现程序客户端时，也应该充分利用现有的缓存机制，以避免每次都从新获取表示。

响应代码的处理有必要吗?

　　HTTP的响应代码可用于应付不一样场合，正确使用这些状态代码意味着客户端与服务器能够在一个具有较丰富语义的层次上进行沟通。例如，201（“Created”）响应代码代表已经建立了一个新的资源，其URI在Location响应报头里。假如你不利用HTTP状态代码丰富的应用语义，那么你将错失提升重用性、加强互操做性和提高松耦合性的机会。若是这些所谓的RESTful应用必须经过响应实体才能给出错误信息，那么SOAP就是这样的了，它就可以知足了。

　　2. 3 资源的表述

　　上面提到，客户端经过HTTP方法能够获取资源，是吧? 不，确切的说，客户端获取的只是资源的表述而已。资源在外界的具体呈现，能够有多种表述(或成为表现、表示)形式，在客户端和服务端之间传送的也是资源的表述，而不是资源自己。例如文本资源能够采用html、xml、json等格式，图片可使用PNG或JPG展示出来。资源的表述包括数据和描述数据的元数据，例如，HTTP头“Content-Type” 就是这样一个元数据属性。

　　那么客户端如何知道服务端提供哪一种表述形式呢?

　　答案是能够经过HTTP内容协商，客户端能够经过Accept头请求一种特定格式的表述，服务端则经过Content-Type告诉客户端资源的表述形式。

　　以github为例，请求某组织资源的json格式的表述形式:

　　假如github也可以支持xml格式的表述格式，那么结果就是这样的:

　　下面咱们来看一些实践上常见的设计:

　　在URI里边带上版本号

　　有些API在URI里边带上版本号，例如:

http://api.example.com/1.0/foo
http://api.example.com/1.2/foo
http://api.example.com/2.0/foo

　　若是咱们把版本号理解成资源的不一样表述形式的话，就应该只是用一个URL，并经过Accept头部来区分，仍是以github为例，它的Accept的完整格式是:application/vnd.github[.version].param[+json]

　　对于v3版本的话，就是Accept: application/vnd.github.v3。对于上面的例子，同理可使用使用下面的头部:

Accept: vnd.example-com.foo+json; version=1.0
Accept: vnd.example-com.foo+json; version=1.2
Accept: vnd.example-com.foo+json; version=2.0

　　使用URI后缀来区分表述格式

　　像rails框架，就支持使用/users.xml或/users.json来区分不一样的格式。这样的方式对于客户端来讲，无疑是更为直观，但混淆了资源的名称和资源的表述形式。我我的认为，仍是应该优先使用内容协商来区分表述格式。

　　如何处理不支持的表述格式

　　当服务器不支持所请求的表述格式，那么应该怎么办？若服务器不支持，它应该返回一个HTTP 406响应，表示拒绝处理该请求。下面以github为例，展现了一个请求XML表述资源的结果：

　　2. 4 资源的连接

　　咱们知道REST是使用标准的HTTP方法来操做资源的，但仅仅所以就理解成带CURD的Web数据库架构就太过于简单了。这种反模式忽略了一个核心概念：“超媒体即应用状态引擎（hypermedia as the engine of application state）”。超媒体是什么? 当你浏览Web网页时，从一个链接跳到一个页面，再从另外一个链接跳到另一个页面，就是利用了超媒体的概念：把一个个把资源连接起来.

　　要达到这个目的，就要求在表述格式里边加入连接来引导客户端。在《RESTful Web Services》一书中，做者把这种具备连接的特性成为连通性。下面咱们具体来看一些例子。

　　下面展现的是github获取某个组织下的项目列表的请求，能够看到在响应头里边增长Link头告诉客户端怎么访问下一页和最后一页的记录。而在响应体里边，用url来连接项目全部者和项目地址。

　　又例以下面这个例子，建立订单后经过连接引导客户端如何去付款。

　　上面的例子展现了如何使用超媒体来加强资源的连通性。不少人在设计RESTful架构时，使用不少时间来寻找漂亮的URI，而忽略了超媒体。因此，应该多花一些时间来给资源的表述提供连接，而不是专一于“资源的CRUD”。

　　2. 5 状态的转移

　　有了上面的铺垫，再讨论REST里边的状态转移就会很容易理解了。不过，咱们先来讨论一下REST原则中的无状态通讯原则。初看一下，好像自相矛盾了，既然无状态，何来状态转移一说?

　　其实，这里说的无状态通讯原则，并非说客户端应用不能有状态，而是指服务端不该该保存客户端状态。

　　2. 5.1 应用状态与资源状态

　　实际上，状态应该区分应用状态和资源状态，客户端负责维护应用状态，而服务端维护资源状态。客户端与服务端的交互必须是无状态的，并在每一次请求中包含处理该请求所需的一切信息。服务端不须要在请求间保留应用状态，只有在接受到实际请求的时候，服务端才会关注应用状态。这种无状态通讯原则，使得服务端和中介可以理解独立的请求和响应。在屡次请求中，同一客户端也再也不须要依赖于同一服务器，方便实现高可扩展和高可用性的服务端。

　　但有时候咱们会作出违反无状态通讯原则的设计，例如利用Cookie跟踪某个服务端会话状态，常见的像J2EE里边的JSESSIONID。这意味着，浏览器随各次请求发出去的Cookie是被用于构建会话状态的。固然，若是Cookie保存的是一些服务器不依赖于会话状态便可验证的信息（好比认证令牌），这样的Cookie也是符合REST原则的。

　　2. 5.2 应用状态的转移

　　状态转移到这里已经很好理解了， “会话”状态不是做为资源状态保存在服务端的，而是被客户端做为应用状态进行跟踪的。客户端应用状态在服务端提供的超媒体的指引下发生变迁。服务端经过超媒体告诉客户端当前状态有哪些后续状态能够进入。这些相似“下一页”之类的连接起的就是这种推动状态的做用——指引你如何从当前状态进入下一个可能的状态。

　 3.撰写合格的rest api

RFC一致性

　　REST API通常用来将某种资源和容许的对资源的操做暴露给外界，使调用者可以以正确的方式操做资源。这里，在输入输出的处理上，要符合HTTP/1.1（不久的未来，要符合HTTP/2.0）的RFC，保证接口的一致性。这里主要讲输入的method/headers和输出的status code。

　　Methods

　　HTTP协议提供了不少methods来操做数据：

GET: 获取某个资源，GET操做应该是幂等（idempotence）的，且无反作用。
POST: 建立一个新的资源。
PUT: 替换某个已有的资源。PUT操做虽然有反作用，但其应该是幂等的。
PATCH（RFC5789）: 修改某个已有的资源。
DELETE：删除某个资源。DELETE操做有反作用，但也是幂等的。

　　幂等在HTTP/1.1中定义以下：

Methods can also have the property of "idempotence" in that (aside from error or expiration issues) the side-effects of N > 0 identical requests is the same as for a single request.

　　简单说来就是一个操做符合幂等性，那么相同的数据和参数下，执行一次或屡次产生的效果（反作用）是同样的。

　　如今大多的REST framwork对HTTP methods都有正确的支持，有些旧的framework可能未必对PATCH有支持，须要注意。若是本身手写REST API，必定要注意区分POST/PUT/PATCH/DELETE的应用场景。

　　Headers

　　不少REST API犯的比较大的一个问题是：不怎么理会request headers。对于REST API，有一些HTTP headers很重要：

Accept：服务器须要返回什么样的content。若是客户端要求返回"application/xml"，而服务器端只能返回"application/json"，那么最好返回status code 406 not acceptable（RFC2616），固然，返回application/json也并不违背RFC的定义。一个合格的REST API须要根据Accept头来灵活返回合适的数据。
If-Modified-Since/If-None-Match：若是客户端提供某个条件，那么当这条件知足时，才返回数据，不然返回304 not modified。好比客户端已经缓存了某个数据，它只是想看看有没有新的数据时，会用这两个header之一，服务器若是不理不睬，依旧作足全套功课，返回200 ok，那就既不专业，也不高效了。
If-Match：在对某个资源作PUT/PATCH/DELETE操做时，服务器应该要求客户端提供If-Match头，只有客户端提供的Etag与服务器对应资源的Etag一致，才进行操做，不然返回412 precondition failed。这个头很是重要，下文详解。

　　Status Code

　　不少REST API犯下的另外一个错误是：返回数据时不遵循RFC定义的status code，而是一概200 ok + error message。这么作在client + API都是同一公司所为还凑合可用，但一旦把API暴露给第三方，不但贻笑大方，还会留下诸多互操做上的隐患。

　　安全性

　　前面说过，REST API承前启后，是系统暴露给外界的接口，因此，其安全性很是重要。安全并单单不意味着加密解密，而是一致性（integrity），机密性（confidentiality）和可用性（availibility）。

　　请求数据验证

　　咱们从数据流入REST API的第一步 —— 请求数据的验证 —— 来保证安全性。你能够把请求数据验证当作一个巨大的漏斗，把没必要要的访问通通过滤在第一线：

Request headers是否合法：若是出现了某些不应有的头，或者某些必须包含的头没有出现或者内容不合法，根据其错误类型一概返回4xx。好比说你的API须要某个特殊的私有头（e.g. X-Request-ID），那么凡是没有这个头的请求一概拒绝。这能够防止各种漫无目的的webot或crawler的请求，节省服务器的开销。
Request URI和Request body是否合法：若是请求带有了不应有的数据，或者某些必须包含的数据没有出现或内容不合法，一概返回4xx。好比说，API只容许querystring中含有query，那么"?sort=desc"这样的请求须要直接被拒绝。有很多攻击会在querystring和request body里作文章，最好的对应策略是，过滤全部含有不应出现的数据的请求。

　　数据完整性验证

　　REST API每每须要对backend的数据进行修改。修改是个很可怕的操做，咱们既要保证正常的服务请求可以正确处理，还须要防止各类潜在的攻击，如replay。数据完整性验证的底线是：保证要修改的数据和服务器里的数据是一致的 —— 这是经过Etag来完成。

　　Etag能够认为是某个资源的一个惟一的版本号。当客户端请求某个资源时，该资源的Etag一同被返回，而当客户端须要修改该资源时，须要经过"If-Match"头来提供这个Etag。服务器检查客户端提供的Etag是否和服务器同一资源的Etag相同，若是相同，才进行修改，不然返回412 precondition failed。

　　使用Etag能够防止错误更新。好比A拿到了Resource X的Etag X1，B也拿到了Resource X的Etag X1。B对X作了修改，修改后系统生成的新的Etag是X2。这时A也想更新X，因为A持有旧的Etag，服务器拒绝更新，直至A从新获取了X后才能正常更新。

　　Etag相似一把锁，是数据完整性的最重要的一道保障。Etag能把绝大多数integrity的问题扼杀在摇篮中，固然，race condition仍是存在的：若是B的修改还未进入数据库，而A的修改请求正好经过了Etag的验证时，依然存在一致性问题。这就须要在数据库写入时作一致性写入的前置检查。

　　访问控制

　　REST API须要清晰定义哪些操做可以公开访问，哪些操做须要受权访问。通常而言，若是对REST API的安全性要求比较高，那么，全部的API的全部操做均需获得受权。

　　在HTTP协议之上处理受权有不少方法，如HTTP BASIC Auth，OAuth，HMAC Auth等，其核心思想都是验证某个请求是由一个合法的请求者发起。Basic Auth会把用户的密码暴露在网络之中，并不是最安全的解决方案，OAuth的核心部分与HMAC Auth差很少，只不过多了不少与token分发相关的内容。这里咱们主要讲讲HMAC Auth的思想。

　　回到Security的三个属性：一致性，机密性，和可用性。HMAC Auth保证一致性：请求的数据在传输过程当中未被修改，所以能够安全地用于验证请求的合法性。

　　HMAC主要在请求头中使用两个字段：Authorization和Date（或X-Auth-Timestamp）。Authorization字段的内容由":"分隔成两部分，":"前是access-key，":"后是HTTP请求的HMAC值。在API受权的时候通常会为调用者生成access-key和access-secret，前者能够暴露在网络中，后者必须安全保存。当客户端调用API时，用本身的access-secret按照要求对request的headers/body计算HMAC，而后把本身的access-key和HMAC填入Authorization头中。服务器拿到这个头，从数据库（或者缓存）中取出access-key对应的secret，按照相同的方式计算HMAC，若是其与Authorization header中的一致，则请求是合法的，且未被修改过的；不然不合法。

GET /photos/puppy.jpg HTTP/1.1
Host: johnsmith.s3.amazonaws.com
Date: Mon, 26 Mar 2007 19:37:58 +0000

Authorization: AWS AKIAIOSFODNN7EXAMPLE:frJIUN8DYpKDtOLCwo//yllqDzg=

（Amazon HMAC图示）

　　在作HMAC的时候，request headers中的request method，request URI，Date/X-Auth-Timestamp等header会被计算在HMAC中。将时间戳计算在HMAC中的好处是能够防止replay攻击。客户端和服务器之间的UTC时间正常来讲误差很小，那么，一个请求携带的时间戳，和该请求到达服务器时服务器的时间戳，中间差异太大，超过某个阈值（好比说120s），那么能够认为是replay，服务器主动丢弃该请求。

　　使用HMAC能够很大程度上防止DOS攻击 —— 无效的请求在验证HMAC阶段就被丢弃，最大程度保护服务器的计算资源。

　　HTTPS

　　HMAC Auth尽管在保证请求的一致性上很是安全，能够用于鉴别请求是否由合法的请求者发起，但请求的数据和服务器返回的响应都是明文传输，对某些要求比较高的API来讲，安全级别还不够。这时候，须要部署HTTPS。在其之上再加一层屏障。