HTTP 请求方法／状态码／错误处理／数据缓存

[Qingquan-Li]

本文整理来源以下资料： HTTP 接口设计指北 浏览器缓存机制

HTTP 请求方法

关于 HTTP Methods 语义的说明（http1.1）：

• OPTIONS 用于获取资源支持的所有 HTTP 方法
• HEAD 用于只获取请求某个资源返回的头信息
• GET 用于从服务器获取某个资源的信息
  • 完成请求后返回状态码 200 OK
  • 完成请求后需要返回被请求的资源详细信息
• POST 用于创建新资源
  • 创建完成后返回状态码 201 Created
  • 完成请求后需要返回被创建的资源详细信息
• PUT 用于完整的替换资源或者创建指定身份的资源，比如创建 id 为 123 的某个资源
  • 如果是创建了资源，则返回 201 Created
  • 如果是替换了资源，则返回 200 OK
  • 完成请求后需要返回被修改的资源详细信息
• PATCH 用于局部更新资源
  • 完成请求后返回状态码 200 OK
  • 完成请求后需要返回被修改的资源详细信息
• DELETE 用于删除某个资源
  • 完成请求后返回状态码 204 No Content

---

状态码

请求成功

• 200 OK : 请求执行成功并返回相应数据，如 GET 成功
• 201 Created : 对象创建成功并返回相应资源数据，如 POST 成功；创建完成后响应头中应该携带头标 Location ，指向新建资源的地址
• 202 Accepted : 接受请求，但无法立即完成创建行为，比如其中涉及到一个需要花费若干小时才能完成的任务。返回的实体中应该包含当前状态的信息，以及指向处理状态监视器或状态预测的指针，以便客户端能够获取最新状态。
• 204 No Content : 请求执行成功，不返回相应资源数据，如 PATCH ， DELETE 成功

重定向

重定向的新地址都需要在响应头 Location 中返回

• 301 Moved Permanently : 被请求的资源已永久移动到新位置
• 302 Found : 请求的资源现在临时从不同的 URI 响应请求
• 303 See Other : 对应当前请求的响应可以在另一个 URI 上被找到，客户端应该使用 GET 方法进行请求。比如在创建已经被创建的资源时，可以返回 303
• 307 Temporary Redirect : 对应当前请求的响应可以在另一个 URI 上被找到，客户端应该保持原有的请求方法进行请求

条件请求

• 304 Not Modified : 资源自从上次请求后没有再次发生变化，主要使用场景在于实现数据缓存
• 409 Conflict : 请求操作和资源的当前状态存在冲突。主要使用场景在于实现并发控制
• 412 Precondition Failed : 服务器在验证在请求的头字段中给出先决条件时，没能满足其中的一个或多个。主要使用场景在于实现并发控制

客户端错误

• 400 Bad Request : 请求体包含语法错误
• 401 Unauthorized : 需要验证用户身份，如果服务器就算是身份验证后也不允许客户访问资源，应该响应 403 Forbidden 。如果请求里有 Authorization 头，那么必须返回一个 WWW-Authenticate 头
• 403 Forbidden : 服务器拒绝执行
• 404 Not Found : 找不到目标资源
• 405 Method Not Allowed : 不允许执行目标方法，响应中应该带有 Allow 头，内容为对该资源有效的 HTTP 方法
• 406 Not Acceptable : 服务器不支持客户端请求的内容格式，但响应里会包含服务端能够给出的格式的数据，并在 Content-Type 中声明格式名称
• 410 Gone : 被请求的资源已被删除，只有在确定了这种情况是永久性的时候才可以使用，否则建议使用 404 Not Found
• 413 Payload Too Large : POST 或者 PUT 请求的消息实体过大
• 415 Unsupported Media Type : 服务器不支持请求中提交的数据的格式
• 422 Unprocessable Entity : 请求格式正确，但是由于含有语义错误，无法响应
• 428 Precondition Required : 要求先决条件，如果想要请求能成功必须满足一些预设的条件

服务端错误

• 500 Internal Server Error : 服务器遇到了一个未曾预料的状况，导致了它无法完成对请求的处理。
• 501 Not Implemented : 服务器不支持当前请求所需要的某个功能。
• 502 Bad Gateway : 作为网关或者代理工作的服务器尝试执行请求时，从上游服务器接收到无效的响应。
• 503 Service Unavailable : 由于临时的服务器维护或者过载，服务器当前无法处理请求。这个状况是临时的，并且将在一段时间以后恢复。如果能够预计延迟时间，那么响应中可以包含一个 Retry-After 头用以标明这个延迟时间（内容可以为数字，单位为秒；或者是一个 HTTP 协议指定的时间格式）。如果没有给出这个 Retry-After 信息，那么客户端应当以处理 500 响应的方式处理它。

501 与 405 的区别是：405 是表示服务端不允许客户端这么做，501 是表示客户端或许可以这么做，但服务端还没有实现这个功能

---

错误处理

在调用接口的过程中，可能出现下列几种错误情况：

• 服务器维护中，503 状态码

  HTTP/1.1 503 Service Unavailable
  Retry-After: 3600
  Content-Length: 41
  
  {"message": "Service In the maintenance"}

• 发送了无法转化的请求体，400 状态码

  HTTP/1.1 400 Bad Request
  Content-Length: 35
  
  {"message": "Problems parsing JSON"}

• 服务到期（比如付费的增值服务等）， 403 状态码

  HTTP/1.1 403 Forbidden
  Content-Length: 29
  
  {"message": "Service expired"}

• 因为某些原因不允许访问（比如被 ban ），403 状态码

  HTTP/1.1 403 Forbidden
  Content-Length: 29
  
  {"message": "Account blocked"}

• 权限不够，403 状态码

  HTTP/1.1 403 Forbidden
  Content-Length: 31
  
  {"message": "Permission denied"}

• 需要修改的资源不存在， 404 状态码

  HTTP/1.1 404 Not Found
  Content-Length: 32
  
  {"message": "Resource not found"}

• 缺少了必要的头信息，428 状态码

  HTTP/1.1 428 Precondition Required
  Content-Length: 35
  
  {"message": "Header User-Agent is required"}

• 发送了非法的资源，422 状态码

  HTTP/1.1 422 Unprocessable Entity
  Content-Length: 149
  
  {
    "message": "Validation Failed",
    "errors": [
      {
        "resource": "Issue",
        "field": "title",
        "code": "required"
      }
    ]
  }

所有的 error 哈希表都有 resource, field, code 字段，以便于定位错误，code 字段则用于表示错误类型：

• invalid: 某个字段的值非法，接口文档中会提供相应的信息
• required: 缺失某个必须的字段
• not_exist: 说明某个字段的值代表的资源不存在
• already_exist: 发送的资源中的某个字段的值和服务器中已有的某个资源冲突，常见于某些值全局唯一的字段，比如 @ 用的用户名（这个错误我有纠结，因为其实有 409 状态码可以表示，但是在修改某个资源时，很一般显然请求中不止是一种错误，如果是 409 的话，多种错误的场景就不合适了）

---

数据缓存

大部分接口应该在响应头中携带 Last-Modified, ETag, Vary, Date 信息，客户端可以在随后请求这些资源的时候，在请求头中使用 If-Modified-Since, If-None-Match 等请求头来确认资源是否经过修改。

如果资源没有进行过修改，那么就可以响应 304 Not Modified 并且不在响应实体中返回任何内容。

$ curl -i http://api.example.com/#{RESOURCE_URI}
HTTP/1.1 200 OK
Cache-Control: public, max-age=60
Date: Thu, 05 Jul 2012 15:31:30 GMT
Vary: Accept, Authorization
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT

Content

$ curl -i http://api.example.com/#{RESOURCE_URI} -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT"
HTTP/1.1 304 Not Modified
Cache-Control: public, max-age=60
Date: Thu, 05 Jul 2012 15:31:45 GMT
Vary: Accept, Authorization
Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT

$ curl -i http://api.example.com/#{RESOURCE_URI} -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
HTTP/1.1 304 Not Modified
Cache-Control: public, max-age=60
Date: Thu, 05 Jul 2012 15:31:55 GMT
Vary: Accept, Authorization
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT

Last-Modified/If-Modified-Since

Last-Modified/If-Modified-Since要配合Cache-Control使用。

• Last-Modified：标示这个响应资源的最后修改时间。web服务器在响应请求时，告诉浏览器资源的最后修改时间。
• If-Modified-Since：当资源过期时（使用Cache-Control标识的max-age），发现资源具有Last-Modified声明，则再次向web服务器请求时带上头 If-Modified-Since，表示请求时间。web服务器收到请求后发现有头If-Modified-Since 则与被请求资源的最后修改时间进行比对。若最后修改时间较新，说明资源又被改动过，则响应整片资源内容（写在响应消息包体内），HTTP 200；若最后修改时间较旧，说明资源无新修改，则响应HTTP 304 (无需包体，节省浏览)，告知浏览器继续使用所保存的cache。

Etag/If-None-Match

Etag/If-None-Match也要配合Cache-Control使用。

• Etag：web服务器响应请求时，告诉浏览器当前资源在服务器的唯一标识（生成规则由服务器觉得）。Apache中，ETag的值，默认是对文件的索引节（INode），大小（Size）和最后修改时间（MTime）进行Hash后得到的。
• If-None-Match：当资源过期时（使用Cache-Control标识的max-age），发现资源具有Etage声明，则再次向web服务器请求时带上头If-None-Match（Etag的值）。web服务器收到请求后发现有头If-None-Match 则与被请求资源的相应校验串进行比对，决定返回200或304。

既生Last-Modified何生Etag？

你可能会觉得使用Last-Modified已经足以让浏览器知道本地的缓存副本是否足够新，为什么还需要Etag（实体标识）呢？HTTP1.1中Etag的出现主要是为了解决几个Last-Modified比较难解决的问题：

• Last-Modified标注的最后修改只能精确到秒级，如果某些文件在1秒钟以内，被修改多次的话，它将不能准确标注文件的修改时间
• 如果某些文件会被定期生成，当有时内容并没有任何变化，但Last-Modified却改变了，导致文件没法使用缓存
• 有可能存在服务器没有准确获取文件修改时间，或者与代理服务器时间不一致等情形 Etag是服务器自动生成或者由开发者生成的对应资源在服务器端的唯一标识符，能够更加准确的控制缓存。Last-Modified与ETag是可以一起使用的，服务器会优先验证ETag，一致的情况下，才会继续比对Last-Modified，最后才决定是否返回304。

浏览器第一次请求：

浏览器再次请求：