API 响应

概述

客户端的每一次请求，服务器都必须给出响应。响应的内容可以是数据，也可以是错误信息。回应包括 HTTP 状态码 和 响应体 两部分。响应体一般是数据。

HTTP 状态码是一个三位数，表示服务器对客户端请求的处理结果。分为五类：

1xx：信息，服务器收到请求，需要请求者继续执行操作
2xx：成功，操作被成功接收并处理
3xx：重定向，需要进一步的操作以完成请求
4xx：客户端错误，请求包含语法错误或无法完成请求
5xx：服务器错误，服务器在处理请求的过程中发生了错误

常见状态码

1xx

API 一般不会返回 1xx 状态码，因为这些状态码表示服务器需要客户端继续操作，而 API 一般是被其他程序调用，不需要人工干预。

2xx

200 状态码表示操作成功，但是仍有一些精确的状态码。

GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content

200 状态码表示操作成功，但是没有返回数据。

201 状态码表示操作成功，且返回了新创建的资源。

204 状态码表示操作成功，表示资源已经不存在。

3xx

API 一般不会返回 3xx 状态码，因为他们代表重定向操作，它们可以由应用级别来返回。浏览器会直接跳转，API 不用考虑。

API 中主要是使用 303 See Other 状态码，表示 暂时重定向 操作成功，但是需要重定向到其他页面。302和307用于 GET 请求，303用于 POST 、 PUT 和 PATCH 请求。收到 303 状态码后，浏览器不会自动跳转，而是要求用户手动跳转。

303 See Other
location: /api/users/123

4xx

400 状态码表示客户端请求有语法错误，不能被服务器所理解。（Bad Request)

401 状态码表示请求未经授权。这个状态码必须和 WWW-Authenticate 报头域一起使用。(Unauthorized)

403 状态码表示服务器收到请求，但是拒绝提供服务。(Forbidden)

404 状态码表示服务器无法根据客户端的请求找到资源（网页）。(Not Found)

405 状态码表示客户端请求中的方法被禁止(不在权限范围内）。(Method Not Allowed)

410 状态码表示服务器上的某个资源被永久性的删除。(Gone)

415 状态码表示服务器无法处理请求附带的媒体格式。(Unsupported Media Type)

422 状态码表示当创建一个对象时，发生一个验证错误。(Unprocessable Entity)

429 状态码表示用户在给定的时间内发送了太多的请求。(Too Many Requests)

返回数据

不要返回纯文本

纯文本的返回值，不利于前端的解析，因为前端需要根据返回值的格式来解析数据。应该是返回 JSON 格式的数据。所以，服务器回应的 HTTP 头信息中，应该包含 Content-Type: application/json。客户端请求时，也要明确指定 Accept: application/json。

不要包装数据

不要在返回的数据中包装数据,保证 body 中直接就是数据，比如：

{
  "success": true,
  "data": {
    "id": 1,
    "name": "张三"
  }
}

针对不同操作，服务器向用户返回的结果应该符合下面的规范：

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

保证正确的状态码

发生错误时，服务器应该返回正确的状态码。比如，当用户请求不存在的资源时，服务器应该返回 404 状态码。而不能将状态码设置为 200，然后在返回的数据中包含错误信息。

❌

HTTP/1.1 200 OK
{
  "success": false,
  "error": {
    "message": "Not Found"
  }
}

✅

HTTP/1.1 404 Not Found
Content-Type: application/json
{
  "error": "Invalid API call",
  "message": "Not Found"
}