# 状态码规范

URL: https://caijiao.org/koa/error/status-code
Source: docs/koa/error/status-code.md
Description: 状态码规范是指应用中如何合理地使用 HTTP 状态码来表示请求的处理结果。它帮助开发人员和客户端更清晰地理解请求的状态以及如何处理不同的响应。

在开发 Web 应用时，合理使用 HTTP 状态码对于确保客户端和服务器之间的通信清晰有效至关重要。状态码帮助客户端理解请求的成功与失败，以及如何处理返回的数据。本文将介绍一些常用的 HTTP 状态码及其使用规范。

## 常见的 HTTP 状态码

### 2xx: 成功响应

这些状态码表示请求已经成功处理。最常见的状态码是 `200 OK`，它表示请求成功且响应包含请求的数据。

- **200 OK**：请求成功，返回所请求的数据。
- **201 Created**：请求成功且服务器创建了新资源，通常用于 POST 请求。
- **202 Accepted**：请求已被接受，但尚未处理。通常用于异步操作。
- **204 No Content**：请求成功，但没有返回数据。适用于 DELETE 请求或不需要返回主体的请求。

### 3xx: 重定向响应

这些状态码表示客户端需要采取进一步的操作才能完成请求。

- **301 Moved Permanently**：资源已被永久移动到新的 URL。客户端应使用新的 URL 进行请求。
- **302 Found**：资源暂时移动，客户端应使用新的 URL，但未来的请求仍可能使用旧的 URL。
- **304 Not Modified**：资源未被修改，客户端可以继续使用缓存的版本。

### 4xx: 客户端错误

这些状态码表示请求存在问题，通常是由于客户端的错误导致的。

- **400 Bad Request**：请求无效，通常由于缺少必要的参数或格式不正确。
- **401 Unauthorized**：请求未通过身份验证，客户端需要提供凭证（如登录信息）。
- **403 Forbidden**：服务器理解请求但拒绝执行，通常表示权限问题。
- **404 Not Found**：请求的资源不存在。
- **405 Method Not Allowed**：请求方法不允许（例如，尝试用 GET 请求修改数据）。

### 5xx: 服务器错误

这些状态码表示请求有效，但服务器在处理请求时出现了问题，通常是服务器端的错误。

- **500 Internal Server Error**：服务器发生了未处理的错误，无法完成请求。
- **502 Bad Gateway**：作为网关或代理的服务器收到无效响应。
- **503 Service Unavailable**：服务器当前无法处理请求，通常是由于过载或维护。
- **504 Gateway Timeout**：网关或代理服务器没有及时收到响应。

## 状态码的最佳实践

1. **适当使用 2xx 状态码**：对于成功的请求，确保返回正确的状态码。例如，使用 `200 OK` 表示成功，使用 `201 Created` 表示创建成功。
2. **正确使用 4xx 状态码**：对于客户端错误，确保使用恰当的状态码。例如，`400 Bad Request` 适用于请求格式错误，`404 Not Found` 适用于资源未找到。
3. **服务器错误使用 5xx 状态码**：当服务器发生内部错误时，使用 `500 Internal Server Error`，并根据具体错误信息返回有用的调试信息。
4. **避免使用 2xx 状态码进行错误处理**：即使请求成功，若发生错误（例如验证失败），应使用 `400` 或 `401` 等合适的状态码，而不是让错误信息通过 `200 OK` 状态返回。
5. **尽量避免使用 `204 No Content`**：`204 No Content` 表示请求成功但没有返回内容，适用于不需要返回响应体的操作，但要确保客户端能正确处理这种状态。

## 状态码与 RESTful API

在 RESTful API 中，状态码的使用是确保 API 清晰和一致的关键。正确的状态码能够帮助开发者快速理解 API 的行为，简化客户端与服务器之间的通信。以下是一些 RESTful API 中常见的状态码用法：

- **POST 请求**：通常使用 `201 Created` 来表示资源已成功创建。
- **GET 请求**：如果请求成功并返回数据，使用 `200 OK`；如果资源未找到，使用 `404 Not Found`。
- **PUT 请求**：成功更新资源时使用 `200 OK` 或 `204 No Content`（如果不需要返回数据）。
- **DELETE 请求**：成功删除资源时使用 `200 OK` 或 `204 No Content`。

## 状态码规范总结

通过合理使用 HTTP 状态码，能够使客户端和服务器之间的通信更具规范性和一致性。每个状态码都有其特定的含义，能够帮助开发者和用户快速理解请求的处理结果和后续操作。遵循状态码规范，不仅能提升 API 的可用性，还能增强应用的可维护性。