Rest学习

HTTP 状态码
消息（1字头）
成功（2字头）
重定向（3字头）
请求错误（4字头）
服务器错误（5,6字头）
开发REST API
问题一：如何组织URL
问题二：如何统一输出REST
问题三：如何处理错误
如何定义错误码
问题五：如何返回错误

HTTP 状态码

消息（1字头）

  • 100
    客户端应当继续发送请求。这个临时响应是用来通知客户端它的部分请求已经被服务器接收，且仍未被拒绝。客户端应当继续发送请求的剩余部分，或者如果请求已经完成，忽略这个响应。服务器必须在请求完成后向客户端发送一个最终响应。
  • 101
    服务器已经理解了客户端的请求，并将通过Upgrade 消息头通知客户端采用不同的协议来完成这个请求。在发送完这个响应最后的空行后，服务器将会切换到在Upgrade 消息头中定义的那些协议。
  • 102
    由WebDAV（RFC 2518）扩展的状态码，代表处理将被继续执行。

成功（2字头）

  • 200
    请求已成功，请求所希望的响应头或数据体将随此响应返回。
  • 201
    请求已经被实现，而且有一个新的资源已经依据请求的需要而建立，且其 URI 已经随Location 头信息返回。假如需要的资源无法及时建立的话，应当返回 '202 Accepted'。
  • 202
    服务器已接受请求，但尚未处理。正如它可能被拒绝一样，最终该请求可能会也可能不会被执行。在异步操作的场合下，没有比发送这个状态码更方便的做法了。
    返回202状态码的响应的目的是允许服务器接受其他过程的请求（例如某个每天只执行一次的基于批处理的操作），而不必让客户端一直保持与服务器的连接直到批处理操作全部完成。在接受请求处理并返回202状态码的响应应当在返回的实体中包含一些指示处理当前状态的信息，以及指向处理状态监视器或状态预测的指针，以便用户能够估计操作是否已经完成。
  • 203
    服务器已成功处理了请求，但返回的实体头部元信息不是在原始服务器上有效的确定集合，而是来自本地或者第三方的拷贝。当前的信息可能是原始版本的子集或者超集。例如，包含资源的元数据可能导致原始服务器知道元信息的超集。使用此状态码不是必须的，而且只有在响应不使用此状态码便会返回200 OK的情况下才是合适的。
  • 204
    服务器成功处理了请求，但不需要返回任何实体内容，并且希望返回更新了的元信息。响应可能通过实体头部的形式，返回新的或更新后的元信息。如果存在这些头部信息，则应当与所请求的变量相呼应。
    如果客户端是浏览器的话，那么用户浏览器应保留发送了该请求的页面，而不产生任何文档视图上的变化，即使按照规范新的或更新后的元信息应当被应用到用户浏览器活动视图中的文档。
    由于204响应被禁止包含任何消息体，因此它始终以消息头后的第一个空行结尾。
  • 205
    服务器成功处理了请求，且没有返回任何内容。但是与204响应不同，返回此状态码的响应要求请求者重置文档视图。该响应主要是被用于接受用户输入后，立即重置表单，以便用户能够轻松地开始另一次输入。
  • 206
    服务器已经成功处理了部分 GET 请求。类似于 FlashGet 或者迅雷这类的 HTTP下载工具都是使用此类响应实现断点续传或者将一个大文档分解为多个下载段同时下载。
  • 207
    由WebDAV(RFC 2518)扩展的状态码，代表之后的消息体将是一个XML消息，并且可能依照之前子请求数量的不同，包含一系列独立的响应代码。

重定向（3字头）

  • 300
    被请求的资源有一系列可供选择的回馈信息，每个都有自己特定的地址和浏览器驱动的商议信息。用户或浏览器能够自行选择一个首选的地址进行重定向。
  • 301
    被请求的资源已永久移动到新位置，并且将来任何对此资源的引用都应该使用本响应返回的若干个 URI 之一。如果可能，拥有链接编辑功能的客户端应当自动把请求的地址修改为从服务器反馈回来的地址。除非额外指定，否则这个响应也是可缓存的。
    新的永久性的URI 应当在响应的 Location 域中返回。除非这是一个 HEAD 请求，否则响应的实体中应当包含指向新的 URI 的超链接及简短说明。
    如果这不是一个 GET 或者 HEAD 请求，因此浏览器禁止自动进行重定向，除非得到用户的确认，因为请求的条件可能因此发生变化。
  • 302
    请求的资源临时从不同的 URI响应请求。由于这样的重定向是临时的，客户端应当继续向原有地址发送以后的请求。只有在Cache-Control或Expires中进行了指定的情况下，这个响应才是可缓存的。
  • 303
    对应当前请求的响应可以在另一个 URI 上被找到，而且客户端应当采用 GET 的方式访问那个资源。这个方法的存在主要是为了允许由脚本激活的POST请求输出重定向到一个新的资源。这个新的 URI 不是原始资源的替代引用。同时，303响应禁止被缓存。当然，第二个请求（重定向）可能被缓存。
  • 304
    如果客户端发送了一个带条件的 GET 请求且该请求已被允许，而文档的内容（自上次访问以来或者根据请求的条件）并没有改变，则服务器应当返回这个状态码。304响应禁止包含消息体，因此始终以消息头后的第一个空行结尾。
    该响应必须包含以下的头信息：
    Date，除非这个服务器没有时钟。假如没有时钟的服务器也遵守这些规则，那么代理服务器以及客户端可以自行将 Date 字段添加到接收到的响应头中去（正如RFC 2068中规定的一样），缓存机制将会正常工作。
    ETag 和/或 Content-Location，假如同样的请求本应返回200响应。
    Expires, Cache-Control，和/或Vary，假如其值可能与之前相同变量的其他响应对应的值不同的话。
  • 305
    被请求的资源必须通过指定的代理才能被访问。Location 域中将给出指定的代理所在的 URI 信息，接收者需要重复发送一个单独的请求，通过这个代理才能访问相应资源。只有原始服务器才能建立305响应。
  • 306
    在最新版的规范中，306状态码已经不再被使用。
  • 307
    请求的资源临时从不同的URI 响应请求。

请求错误（4字头）

  • 400
    语义有误，当前请求无法被服务器理解。除非进行修改，否则客户端不应该重复提交这个请求。
  • 401
    当前请求需要用户验证。该响应必须包含一个适用于被请求资源的 WWW-Authenticate 信息头用以询问用户信息。客户端可以重复提交一个包含恰当的 Authorization 头信息的请求。如果当前请求已经包含了 Authorization 证书，那么401响应代表着服务器验证已经拒绝了那些证书。如果401响应包含了与前一个响应相同的身份验证询问，且浏览器已经至少尝试了一次验证，那么浏览器应当向用户展示响应中包含的实体信息，因为这个实体信息中可能包含了相关诊断信息。
  • 402
    该状态码是为了将来可能的需求而预留的。
  • 403
    服务器已经理解请求，但是拒绝执行它。与401响应不同的是，身份验证并不能提供任何帮助，而且这个请求也不应该被重复提交。如果这不是一个 HEAD 请求，而且服务器希望能够讲清楚为何请求不能被执行，那么就应该在实体内描述拒绝的原因。当然服务器也可以返回一个404响应，假如它不希望让客户端获得任何信息。
  • 404
    请求失败，请求所希望得到的资源未被在服务器上发现。没有信息能够告诉用户这个状况到底是暂时的还是永久的。假如服务器知道情况的话，应当使用410状态码来告知旧资源因为某些内部的配置机制问题，已经永久的不可用，而且没有任何可以跳转的地址。404这个状态码被广泛应用于当服务器不想揭示到底为何请求被拒绝或者没有其他适合的响应可用的情况下。出现这个错误的最有可能的原因是服务器端没有这个页面。
  • 405
    请求行中指定的请求方法不能被用于请求相应的资源。该响应必须返回一个Allow 头信息用以表示出当前资源能够接受的请求方法的列表。
    鉴于 PUT，DELETE 方法会对服务器上的资源进行写操作，因而绝大部分的网页服务器都不支持或者在默认配置下不允许上述请求方法，对于此类请求均会返回405错误。
  • 406
    请求的资源的内容特性无法满足请求头中的条件，因而无法生成响应实体。
    除非这是一个 HEAD 请求，否则该响应就应当返回一个包含可以让用户或者浏览器从中选择最合适的实体特性以及地址列表的实体。实体的格式由 Content-Type 头中定义的媒体类型决定。浏览器可以根据格式及自身能力自行作出最佳选择。但是，规范中并没有定义任何作出此类自动选择的标准。
  • 407
    与401响应类似，只不过客户端必须在代理服务器上进行身份验证。代理服务器必须返回一个 Proxy-Authenticate 用以进行身份询问。客户端可以返回一个 Proxy-Authorization 信息头用以验证。
  • 408
    请求超时。客户端没有在服务器预备等待的时间内完成一个请求的发送。客户端可以随时再次提交这一请求而无需进行任何更改。

  • 409
    由于和被请求的资源的当前状态之间存在冲突，请求无法完成。这个代码只允许用在这样的情况下才能被使用：用户被认为能够解决冲突，并且会重新提交新的请求。该响应应当包含足够的信息以便用户发现冲突的源头。

  • 410
    被请求的资源在服务器上已经不再可用，而且没有任何已知的转发地址。这样的状况应当被认为是永久性的。如果可能，拥有链接编辑功能的客户端应当在获得用户许可后删除所有指向这个地址的引用。如果服务器不知道或者无法确定这个状况是否是永久的，那么就应该使用404状态码。除非额外说明，否则这个响应是可缓存的。
    410响应的目的主要是帮助网站管理员维护网站，通知用户该资源已经不再可用，并且服务器拥有者希望所有指向这个资源的远端连接也被删除。这类事件在限时、增值服务中很普遍。同样，410响应也被用于通知客户端在当前服务器站点上，原本属于某个个人的资源已经不再可用。当然，是否需要把所有永久不可用的资源标记为'410 Gone'，以及是否需要保持此标记多长时间，完全取决于服务器拥有者。

  • 411
    服务器拒绝在没有定义 Content-Length 头的情况下接受请求。在添加了表明请求消息体长度的有效 Content-Length 头之后，客户端可以再次提交该请求。
  • 412
    服务器在验证在请求的头字段中给出先决条件时，没能满足其中的一个或多个。这个状态码允许客户端在获取资源时在请求的元信息（请求头字段数据）中设置先决条件，以此避免该请求方法被应用到其希望的内容以外的资源上。
  • 413
    服务器拒绝处理当前请求，因为该请求提交的实体数据大小超过了服务器愿意或者能够处理的范围。此种情况下，服务器可以关闭连接以免客户端继续发送此请求。
  • 414
    请求的URI 长度超过了服务器能够解释的长度，因此服务器拒绝对该请求提供服务。这比较少见，通常的情况包括：
    本应使用POST方法的表单提交变成了GET方法，导致查询字符串（Query String）过长。
    重定向URI “黑洞”，例如每次重定向把旧的 URI 作为新的 URI 的一部分，导致在若干次重定向后 URI 超长。
  • 415
    对于当前请求的方法和所请求的资源，请求中提交的实体并不是服务器中所支持的格式，因此请求被拒绝。
  • 416
    如果请求中包含了 Range 请求头，并且 Range 中指定的任何数据范围都与当前资源的可用范围不重合，同时请求中又没有定义 If-Range 请求头，那么服务器就应当返回416状态码。
  • 417
    在请求头 Expect 中指定的预期内容无法被服务器满足，或者这个服务器是一个代理服务器，它有明显的证据证明在当前路由的下一个节点上，Expect 的内容无法被满足。
  • 422
    请求格式正确，但是由于含有语义错误，无法响应。
  • 423
    当前资源被锁定。
  • 424
    由于之前的某个请求发生的错误，导致当前请求失败，例如 PROPPATCH。
  • 425
    在WebDav Advanced Collections 草案中定义，但是未出现在《WebDAV 顺序集协议》（RFC 3658）中。
  • 426
    客户端应当切换到TLS/1.0。（RFC 2817）
  • 449
    由微软扩展，代表请求应当在执行完适当的操作后进行重试。

服务器错误（5,6字头）

  • 500
    服务器遇到了一个未曾预料的状况，导致了它无法完成对请求的处理。一般来说，这个问题都会在服务器端的源代码出现错误时出现。
  • 501
    服务器不支持当前请求所需要的某个功能。当服务器无法识别请求的方法，并且无法支持其对任何资源的请求。
  • 502
    作为网关或者代理工作的服务器尝试执行请求时，从上游服务器接收到无效的响应。
  • 503
    由于临时的服务器维护或者过载，服务器当前无法处理请求。这个状况是临时的，并且将在一段时间以后恢复。如果能够预计延迟时间，那么响应中可以包含一个 Retry-After 头用以标明这个延迟时间。如果没有给出这个 Retry-After 信息，那么客户端应当以处理500响应的方式处理它。
  • 504
    作为网关或者代理工作的服务器尝试执行请求时，未能及时从上游服务器（URI标识出的服务器，例如HTTP、FTP、LDAP）或者辅助服务器（例如DNS）收到响应。
  • 505
    服务器不支持，或者拒绝支持在请求中使用的 HTTP 版本。这暗示着服务器不能或不愿使用与客户端相同的版本。响应中应当包含一个描述了为何版本不被支持以及服务器支持哪些协议的实体。
  • 506
    由《透明内容协商协议》（RFC 2295）扩展，代表服务器存在内部配置错误：被请求的协商变元资源被配置为在透明内容协商中使用自己，因此在一个协商处理中不是一个合适的重点。
  • 507
    服务器无法存储完成请求所必须的内容。这个状况被认为是临时的。
  • 509
    服务器达到带宽限制。这不是一个官方的状态码，但是仍被广泛使用。
  • 510
    获取资源所需要的策略并没有没满足。
  • 600
    源站没有返回响应头部，只返回实体内容

开发REST API

使用REST虽然非常简单，但是，设计一套合理的REST框架却需要仔细考虑很多问题。

问题一：如何组织URL

在实际工程中，一个Web应用既有REST，还有MVC，可能还需要集成其他第三方系统。如何组织URL？
一个简单的方法是通过固定的前缀区分。例如，/static/开头的URL是静态资源文件，类似的，/api/开头的URL就是REST API，其他URL是普通的MVC请求。
使用不同的子域名也可以区分，但对于中小项目来说配置麻烦。随着项目的扩大，将来仍然可以把单域名拆成多域名。

问题二：如何统一输出REST

如果每个异步函数都编写下面这样的代码： 

  1. // 设置Content-Type:
  2. ctx.response.type = 'application/json';
  3. // 设置Response Body:
  4. ctx.response.body = {
  5.     products: products
  6. };

很显然，这样的重复代码很容易导致错误，例如，写错了字符串'application/json'，或者漏写了ctx.response.type = 'application/json'，都会导致浏览器得不到JSON数据。

问题三：如何处理错误

这个问题实际上有两部分。
第一，当REST API请求出错时，我们如何返回错误信息？
第二，当客户端收到REST响应后，如何判断是成功还是错误？
这两部分还必须统一考虑。
REST架构本身对错误处理并没有统一的规定。实际应用时，各种各样的错误处理机制都有。有的设计得比较合理，有的设计得不合理，导致客户端尤其是手机客户端处理API简直就是噩梦。
在涉及到REST API的错误时，我们必须先意识到，客户端会遇到两种类型的REST API错误。
一类是类似403，404，500等错误，这些错误实际上是HTTP请求可能发生的错误。REST请求只是一种请求类型和响应类型均为JSON的HTTP请求，因此，这些错误在REST请求中也会发生。
针对这种类型的错误，客户端除了提示用户“出现了网络错误，稍后重试”以外，并无法获得具体的错误信息。
另一类错误是业务逻辑的错误，例如，输入了不合法的Email地址，试图删除一个不存在的Product，等等。这种类型的错误完全可以通过JSON返回给客户端，这样，客户端可以根据错误信息提示用户“Email不合法”等，以便用户修复后重新请求API。
问题的关键在于客户端必须能区分出这两种类型的错误。
第一类的错误实际上客户端可以识别，并且我们也无法操控HTTP服务器的错误码。
第二类的错误信息是一个JSON字符串，例如： 

  1. {
  2.     "code": "10000",
  3.     "message": "Bad email address"
  4. }

但是HTTP的返回码应该用啥？
有的Web应用使用200，这样客户端在识别出第一类错误后，如果遇到200响应，则根据响应的JSON判断是否有错误。这种方式对于动态语言（例如，JavaScript，Python等）非常容易： 

  1. var result = JSON.parse(response.data);
  2. if (result.code) {
  3.     // 有错误:
  4.     alert(result.message);
  5. } else {
  6.     // 没有错误
  7. }

但是，对于静态语言（例如，Java）就比较麻烦，很多时候，不得不做两次序列化： 

  1. APIError err = objectMapper.readValue(jsonString, APIError.class);
  2. if (err.code == null) {
  3.     // 没有错误，还需要重新转换:
  4.     User user = objectMapper.readValue(jsonString, User.class);
  5. } else {
  6.     // 有错误:
  7. }

有的Web应用对正确的REST响应使用200，对错误的REST响应使用400，这样，客户端即是静态语言，也可以根据HTTP响应码判断是否出错，出错时直接把结果反序列化为APIError对象。
两种方式各有优劣。我们选择第二种，200表示成功响应，400表示失败响应。

但是，要注意，绝不能混合其他HTTP错误码。例如，使用401响应“登录失败”，使用403响应“权限不够”。这会使客户端无法有效识别HTTP错误码和业务错误，其原因在于HTTP协议定义的错误码十分偏向底层，而REST API属于“高层”协议，不应该复用底层的错误码。

如何定义错误码

REST架构本身同样没有标准的错误码定义一说，因此，有的Web应用使用数字1000、1001……作为错误码，例如Twitter和新浪微博，有的Web应用使用字符串作为错误码，例如YouTube。到底哪一种比较好呢？

我们强烈建议使用字符串作为错误码。原因在于，使用数字作为错误码时，API提供者需要维护一份错误码代码说明表，并且，该文档必须时刻与API发布同步，否则，客户端开发者遇到一个文档上没有写明的错误码，就完全不知道发生了什么错误。

使用字符串作为错误码，最大的好处在于不用查表，根据字面意思也能猜个八九不离十。例如，YouTube API如果返回一个错误authError，基本上能猜到是因为认证失败。

我们定义的REST API错误格式如下： 

  1. {
  2.     "code": "错误代码",
  3.     "message": "错误描述信息"
  4. }

其中，错误代码命名规范为_大类:子类_，例如，口令不匹配的登录错误代码为auth:bad_password，用户名不存在的登录错误代码为auth:user_not_found。这样，客户端既可以简单匹配某个类别的错误，也可以精确匹配某个特定的错误。

问题五：如何返回错误

如果一个REST异步函数想要返回错误，一个直观的想法是调用ctx.rest()： 

  1. user = processLogin(username, password);
  2. if (user != null) {
  3.     ctx.rest(user);
  4. } else {
  5.     ctx.response.status = 400;
  6.     ctx.rest({
  7.         code: 'auth:user_not_found',
  8.         message: 'user not found'
  9.     });
  10. }

这种方式不好，因为控制流程会混乱，而且，错误只能在Controller函数中输出。
更好的方式是异步函数直接用throw语句抛出错误，让middleware去处理错误： 

  1. user = processLogin(username, password);
  2. if (user != null) {
  3.     ctx.rest(user);
  4. } else {
  5.     throw new APIError('auth:user_not_found', 'user not found');
  6. }

这种方式可以在异步函数的任何地方抛出错误，包括调用的子函数内部。
我们只需要稍稍改写一个middleware就可以处理错误： 

  1. module.exports = {
  2.     APIError: function (code, message) {
  3.         this.code = code || 'internal:unknown_error';
  4.         this.message = message || '';
  5.     },
  6.     restify: (pathPrefix) => {
  7.         pathPrefix = pathPrefix || '/api/';
  8.         return async (ctx, next) => {
  9.             if (ctx.request.path.startsWith(pathPrefix)) {
  10.                 // 绑定rest()方法:
  11.                 ctx.rest = (data) => {
  12.                     ctx.response.type = 'application/json';
  13.                     ctx.response.body = data;
  14.                 }
  15.                 try {
  16.                     await next();
  17.                 } catch (e) {
  18.                     // 返回错误:
  19.                     ctx.response.status = 400;
  20.                     ctx.response.type = 'application/json';
  21.                     ctx.response.body = {
  22.                         code: e.code || 'internal:unknown_error',
  23.                         message: e.message || ''
  24.                     };
  25.                 }
  26.             } else {
  27.                 await next();
  28.             }
  29.         };
  30.     }
  31. };

这个错误处理的好处在于，不但简化了Controller的错误处理（只需要throw，其他不管），并且，在遇到非APIError的错误时，自动转换错误码为internal:unknown_error。
受益于async/await语法，我们在middleware中可以直接用try…catch捕获异常。如果是callback模式，就无法用try…catch捕获，代码结构将混乱得多。
最后，顺便把APIError这个对象export出去。

【推广】 免费学中医，健康全家人
原文地址：https://www.cnblogs.com/luolei/p/6821d7e790fa721f72774040bd56d86b.html