RESTful设计原则 HTTP状态码

4 周 ago

木它

2 minutes

1xx – 信息性状态码

这些状态码表示请求已被接收，继续处理。

100 Continue：表示到目前为止一切正常，客户端应继续请求。如果请求已经完成，则忽略此响应。
101 Switching Protocols：表示服务器正在根据客户端的请求切换协议。服务器将以Upgrade头部来指示所用的新协议。

2xx – 成功状态码

表示请求已成功被服务器接收、理解，并接受。

200 OK：请求成功。响应将根据请求的方法而有所不同。例如，GET请求的响应将包含请求的资源。
201 Created：请求成功，并且服务器创建了新的资源。通常用于POST请求，响应会包含新资源的URI。
202 Accepted：请求已被接受用于处理，但尚未完成。没有任何保证服务器会完成处理。
203 Non-Authoritative Information：服务器已成功处理请求，但返回的信息可能来自另一来源。
204 No Content：服务器成功处理了请求，但没有返回任何内容。通常用于更新操作。
205 Reset Content：告诉用户代理重置发送此请求的文档视图。
206 Partial Content：服务器成功处理了部分GET请求。用于支持断点续传。

3xx – 重定向状态码

表示要完成请求，需要进一步操作。

300 Multiple Choices：请求的资源有多种表示形式。用户或用户代理可以选择一个。
301 Moved Permanently：请求的资源已被永久移动到新的URI。响应应包含新的URI。
302 Found：请求的资源临时从不同的URI响应请求。与301不同，客户端应继续使用原始URI。
303 See Other：对请求的响应可以在另一个URI上找到，客户端应使用GET方法请求该资源。
304 Not Modified：资源未被修改，客户端可以继续使用缓存版本。
307 Temporary Redirect：请求的资源临时从不同的URI响应请求。客户端应继续使用原始URI。
308 Permanent Redirect：资源已被永久移动到新的URI，客户端应使用新的URI。

4xx – 客户端错误状态码

表示请求包含错误，阻止服务器处理。

400 Bad Request：请求格式不正确，服务器无法理解请求。
401 Unauthorized：请求需要用户验证。可能需要提供身份验证凭据。
402 Payment Required：保留状态码，用于将来可能的支付需求。
403 Forbidden：服务器理解请求但拒绝执行。通常是权限问题。
404 Not Found：请求的资源不存在。
405 Method Not Allowed：请求方法不支持该资源。例如，使用POST请求一个只读资源。
406 Not Acceptable：请求的资源无法使用请求的内容特性响应。
407 Proxy Authentication Required：客户端必须先通过代理进行身份验证。
408 Request Timeout：请求超时，服务器等待请求时超出了允许的时间。
409 Conflict：请求与资源的当前状态冲突。常用于并发更新。
410 Gone：请求的资源不再可用，并且没有可用的转发地址。
411 Length Required：服务器拒绝接受没有定义Content-Length头的请求。
412 Precondition Failed：服务器不满足请求中设置的某个前提条件。
413 Payload Too Large：请求实体过大，服务器无法处理。
414 URI Too Long：请求的URI过长，服务器无法处理。
415 Unsupported Media Type：请求的格式不受服务器支持。
416 Range Not Satisfiable：请求的范围无法满足。
417 Expectation Failed：服务器无法满足Expect请求头中的要求。
418 I’m a teapot：这个是一个愚人节笑话状态码，表示“我是一个茶壶”。

5xx – 服务器错误状态码

表示服务器在处理请求时发生了错误。

500 Internal Server Error：服务器遇到未预料的情况，无法完成请求。
501 Not Implemented：服务器不支持请求的功能。通常是因为服务器无法识别请求的方法。
502 Bad Gateway：服务器作为网关或代理，从上游服务器收到无效响应。
503 Service Unavailable：服务器当前无法处理请求，通常是由于过载或维护。
504 Gateway Timeout：服务器作为网关或代理，未能及时从上游服务器接收请求。
505 HTTP Version Not Supported：服务器不支持请求中使用的HTTP协议版本。

这些状态码帮助客户端理解请求的处理结果，并采取相应的后续操作。选择合适的状态码对于构建符合RESTful设计原则的API至关重要。

ASP.NET Core 中使用

在ASP.NET Core中，内置了多种结果类型（Result Types），用于在控制器中返回不同的HTTP响应。这些结果类型实现了IActionResult接口，可以帮助你更方便地返回合适的HTTP状态码和内容。以下是一些常用的内置结果类型：

成功结果类型

OkResult：返回HTTP 200 OK状态码，通常用于表示请求成功。

  return Ok();

OkObjectResult：返回HTTP 200 OK状态码，并包含一个对象作为响应体。

  return Ok(object);

CreatedResult：返回HTTP 201 Created状态码，并包含一个URI和对象作为响应体。

  return Created(uri, object);

CreatedAtRouteResult：返回HTTP 201 Created状态码，使用指定的路由名称和参数生成URI。

  return CreatedAtRoute("RouteName", routeValues, object);

NoContentResult：返回HTTP 204 No Content状态码，表示请求成功但没有内容返回。

  return NoContent();

重定向结果类型

RedirectResult：返回HTTP 302 Found状态码，重定向到指定的URL。

  return Redirect("https://example.com");

RedirectToActionResult：重定向到指定的控制器动作。

  return RedirectToAction("ActionName", "ControllerName");

RedirectToRouteResult：重定向到指定的路由。

  return RedirectToRoute("RouteName");

客户端错误结果类型

BadRequestResult：返回HTTP 400 Bad Request状态码，表示请求格式错误。

  return BadRequest();

BadRequestObjectResult：返回HTTP 400 Bad Request状态码，并包含错误信息。

  return BadRequest(errorObject);

UnauthorizedResult：返回HTTP 401 Unauthorized状态码，表示需要身份验证。

  return Unauthorized();

ForbidResult：返回HTTP 403 Forbidden状态码，表示服务器拒绝请求。

  return Forbid();

NotFoundResult：返回HTTP 404 Not Found状态码，表示资源未找到。

  return NotFound();

NotFoundObjectResult：返回HTTP 404 Not Found状态码，并包含错误信息。

  return NotFound(errorObject);

服务器错误结果类型

StatusCodeResult：返回指定的HTTP状态码。

  return StatusCode(500);

ObjectResult：返回指定的HTTP状态码，并包含一个对象作为响应体。

  return StatusCode(500, object);

这些内置结果类型使得在ASP.NET Core中处理HTTP响应变得更加简洁和直观。可以根据具体需求选择合适的结果类型来返回HTTP响应。