cursor-init/docs/http-status-codes.md

# HTTP 状态码完整指南

## 概述

HTTP 状态码是服务器响应客户端请求时返回的三位数字代码，用于表示请求的处理结果。本文档详细列举了所有常见的HTTP状态码，以及在API开发中的最佳实践。

## 状态码分类

- **1xx (信息性)**: 请求已接收，继续处理
- **2xx (成功)**: 请求已成功被服务器接收、理解、并接受
- **3xx (重定向)**: 需要后续操作才能完成这一请求
- **4xx (客户端错误)**: 请求包含错误语法或无法被执行
- **5xx (服务器错误)**: 服务器无法完成明显有效的请求

---

## 1xx 信息性状态码

### 100 Continue

- **说明**: 继续，客户端应继续其请求
- **使用场景**: 大文件上传时的初始确认
- **处理建议**: 通常由HTTP库自动处理，开发者无需特殊处理

### 101 Switching Protocols

- **说明**: 切换协议，服务器根据客户端的请求切换协议
- **使用场景**: WebSocket握手、HTTP升级到HTTPS
- **处理建议**: 确保客户端支持新协议

### 102 Processing

- **说明**: 处理中，服务器已接收并正在处理请求
- **使用场景**: 长时间运行的请求
- **处理建议**: 告知客户端请求正在处理，避免超时

---

## 2xx 成功状态码

### 200 OK

- **说明**: 请求成功
- **使用场景**: GET、PUT、PATCH请求成功
- **返回内容**: 请求的资源或操作结果
- **示例响应**:

```json
{
    "code": 0,
    "message": "操作成功",
    "data": { "id": 1, "name": "用户" }
}
```

### 201 Created

- **说明**: 创建成功
- **使用场景**: POST请求成功创建资源
- **返回内容**: 新创建的资源信息
- **Header建议**: 添加`Location`头指向新资源
- **示例响应**:

```json
{
    "code": 0,
    "message": "创建成功",
    "data": { "id": 123, "name": "新用户" }
}
```

### 202 Accepted

- **说明**: 已接受，请求已被接受，但尚未处理完成
- **使用场景**: 异步任务、批量操作
- **返回内容**: 任务状态或追踪信息
- **示例响应**:

```json
{
    "code": 0,
    "message": "任务已提交",
    "data": { "taskId": "task-123", "status": "processing" }
}
```

### 204 No Content

- **说明**: 无内容，请求成功但无返回内容
- **使用场景**: DELETE请求成功、PUT更新成功
- **返回内容**: 空响应体
- **注意**: 不应返回JSON响应体

### 206 Partial Content

- **说明**: 部分内容
- **使用场景**: 文件断点续传、大文件分块下载
- **Header要求**: 必须包含`Content-Range`
- **处理建议**: 实现Range请求支持

---

## 3xx 重定向状态码

### 301 Moved Permanently

- **说明**: 永久重定向
- **使用场景**: URL结构永久性改变、API版本升级
- **Header要求**: 必须包含`Location`头
- **SEO影响**: 搜索引擎会更新索引

### 302 Found

- **说明**: 临时重定向
- **使用场景**: 临时维护、负载均衡
- **Header要求**: 必须包含`Location`头
- **注意**: 不会影响搜索引擎索引

### 304 Not Modified

- **说明**: 未修改，资源未发生变化
- **使用场景**: 缓存验证、条件请求
- **Header要求**: 配合`ETag`或`Last-Modified`
- **性能优化**: 减少带宽消耗

### 307 Temporary Redirect

- **说明**: 临时重定向（保持请求方法）
- **使用场景**: 确保POST/PUT等方法不被改变
- **与302区别**: 严格保持原始HTTP方法

### 308 Permanent Redirect

- **说明**: 永久重定向（保持请求方法）
- **使用场景**: API端点永久迁移，需保持HTTP方法
- **与301区别**: 严格保持原始HTTP方法

---

## 4xx 客户端错误状态码

### 400 Bad Request

- **说明**: 请求语法错误或参数无效
- **常见原因**:
    - JSON格式错误
    - 必需参数缺失
    - 参数类型不正确
    - 参数值超出范围
- **解决方法**:
    - 验证请求格式
    - 检查参数完整性
    - 使用参数验证库
- **示例响应**:

```json
{
    "code": 400,
    "message": "参数校验失败",
    "data": null,
    "errors": [
        { "field": "email", "message": "邮箱格式不正确" },
        { "field": "age", "message": "年龄必须大于0" }
    ]
}
```

### 401 Unauthorized

- **说明**: 未认证，需要身份验证
- **常见原因**:
    - 缺少认证信息
    - Token已过期
    - Token格式错误
    - 认证信息无效
- **解决方法**:
    - 提供有效的认证信息
    - 刷新过期的Token
    - 重新登录
- **Header建议**: 添加`WWW-Authenticate`头
- **示例响应**:

```json
{
    "code": 401,
    "message": "认证失败，请重新登录",
    "data": null
}
```

### 403 Forbidden

- **说明**: 禁止访问，已认证但无权限
- **常见原因**:
    - 权限不足
    - 资源被禁止访问
    - IP被封禁
    - 账户被冻结
- **解决方法**:
    - 联系管理员获取权限
    - 检查用户角色设置
    - 验证访问策略
- **示例响应**:

```json
{
    "code": 403,
    "message": "权限不足，无法访问该资源",
    "data": null
}
```

### 404 Not Found

- **说明**: 资源不存在
- **常见原因**:
    - URL路径错误
    - 资源已被删除
    - 资源ID不存在
    - API端点不存在
- **解决方法**:
    - 检查URL拼写
    - 验证资源是否存在
    - 确认API版本
- **示例响应**:

```json
{
    "code": 404,
    "message": "请求的资源不存在",
    "data": null
}
```

### 405 Method Not Allowed

- **说明**: 请求方法不被允许
- **常见原因**:
    - 使用了不支持的HTTP方法
    - GET请求用于需要POST的接口
- **Header要求**: 必须包含`Allow`头列出支持的方法
- **示例响应**:

```json
{
    "code": 405,
    "message": "不支持的请求方法",
    "data": null,
    "allowedMethods": ["GET", "POST"]
}
```

### 406 Not Acceptable

- **说明**: 不可接受，服务器无法返回客户端可接受的内容格式
- **常见原因**:
    - Accept头指定了不支持的格式
    - 内容协商失败
- **解决方法**: 调整Accept头或支持更多格式

### 409 Conflict

- **说明**: 冲突，请求与当前资源状态冲突
- **常见原因**:
    - 资源已存在
    - 并发修改冲突
    - 业务逻辑冲突
- **解决方法**:
    - 重新获取最新状态
    - 解决冲突后重试
- **示例响应**:

```json
{
    "code": 409,
    "message": "用户名已存在",
    "data": null
}
```

### 410 Gone

- **说明**: 资源已永久删除
- **使用场景**: 资源被主动删除且不会恢复
- **与404区别**: 明确表示资源曾经存在但已删除

### 411 Length Required

- **说明**: 需要Content-Length头
- **常见原因**: POST/PUT请求缺少Content-Length
- **解决方法**: 添加Content-Length头

### 412 Precondition Failed

- **说明**: 前置条件失败
- **使用场景**: 条件请求（If-Match、If-None-Match等）失败
- **常见原因**: ETag不匹配、条件不满足

### 413 Payload Too Large

- **说明**: 请求体过大
- **常见原因**:
    - 上传文件超出限制
    - JSON数据过大
- **解决方法**:
    - 减小文件大小
    - 分块上传
    - 调整服务器限制
- **示例响应**:

```json
{
    "code": 413,
    "message": "上传文件大小超出限制（最大10MB）",
    "data": null
}
```

### 414 URI Too Long

- **说明**: URI过长
- **常见原因**: GET请求参数过多
- **解决方法**: 使用POST请求或减少参数

### 415 Unsupported Media Type

- **说明**: 不支持的媒体类型
- **常见原因**:
    - Content-Type不正确
    - 上传了不支持的文件格式
- **解决方法**: 检查Content-Type头
- **示例响应**:

```json
{
    "code": 415,
    "message": "不支持的文件格式，仅支持图片文件",
    "data": null,
    "supportedTypes": ["image/jpeg", "image/png", "image/gif"]
}
```

### 422 Unprocessable Entity

- **说明**: 无法处理的实体，语法正确但语义错误
- **常见原因**:
    - 业务逻辑验证失败
    - 数据关联性错误
    - 状态不允许操作
- **与400区别**: 语法正确但业务逻辑错误
- **示例响应**:

```json
{
    "code": 422,
    "message": "业务逻辑验证失败",
    "data": null,
    "errors": [{ "field": "endDate", "message": "结束日期不能早于开始日期" }]
}
```

### 423 Locked

- **说明**: 资源被锁定
- **使用场景**: WebDAV、文件编辑锁定
- **解决方法**: 等待锁定释放或强制解锁

### 429 Too Many Requests

- **说明**: 请求过于频繁
- **常见原因**:
    - 超出API调用频率限制
    - 防暴力破解保护
- **Header建议**:
    - `Retry-After`: 建议重试时间
    - `X-RateLimit-*`: 频率限制信息
- **解决方法**:
    - 降低请求频率
    - 实现指数退避重试
- **示例响应**:

```json
{
    "code": 429,
    "message": "请求过于频繁，请稍后重试",
    "data": null,
    "retryAfter": 60
}
```

---

## 5xx 服务器错误状态码

### 500 Internal Server Error

- **说明**: 服务器内部错误
- **常见原因**:
    - 代码异常未捕获
    - 数据库连接失败
    - 第三方服务异常
    - 配置错误
- **解决方法**:
    - 检查服务器日志
    - 修复代码bug
    - 验证配置正确性
- **开发环境响应**:

```json
{
    "code": 500,
    "message": "服务器内部错误",
    "data": null,
    "traceId": "req-123456",
    "details": "NullPointerException at line 42",
    "stack": "详细堆栈信息..."
}
```

- **生产环境响应**:

```json
{
    "code": 500,
    "message": "服务器内部错误，请稍后重试",
    "data": null,
    "traceId": "req-123456"
}
```

### 501 Not Implemented

- **说明**: 功能未实现
- **使用场景**: API端点规划但未开发
- **解决方法**: 等待功能开发完成

### 502 Bad Gateway

- **说明**: 网关错误
- **常见原因**:
    - 上游服务器响应无效
    - 代理服务器配置错误
    - 负载均衡器问题
- **解决方法**:
    - 检查上游服务状态
    - 验证代理配置
    - 重启相关服务

### 503 Service Unavailable

- **说明**: 服务不可用
- **常见原因**:
    - 服务器维护
    - 系统过载
    - 依赖服务不可用
- **Header建议**: 添加`Retry-After`头
- **解决方法**:
    - 等待维护完成
    - 扩容服务器
    - 修复依赖服务
- **示例响应**:

```json
{
    "code": 503,
    "message": "服务暂时不可用，系统维护中",
    "data": null,
    "retryAfter": 3600
}
```

### 504 Gateway Timeout

- **说明**: 网关超时
- **常见原因**:
    - 上游服务响应超时
    - 网络延迟过高
    - 处理时间过长
- **解决方法**:
    - 优化上游服务性能
    - 增加超时时间
    - 实现异步处理

### 505 HTTP Version Not Supported

- **说明**: HTTP版本不支持
- **解决方法**: 使用支持的HTTP版本

---

## API 错误处理最佳实践

### 1. 统一错误响应格式

```json
{
    "code": 400,
    "message": "用户友好的错误描述",
    "data": null,
    "traceId": "req-uuid-123",
    "timestamp": "2024-01-01T12:00:00Z",
    "errors": [
        {
            "field": "email",
            "message": "邮箱格式不正确",
            "code": "INVALID_EMAIL_FORMAT"
        }
    ]
}
```

### 2. 错误码设计原则

- **HTTP状态码**: 表示HTTP层面的处理结果
- **业务错误码**: 表示具体的业务错误类型
- **错误消息**: 提供用户友好的错误描述
- **错误详情**: 开发环境提供详细信息，生产环境保护敏感信息

### 3. 常见业务错误码映射

| 业务场景         | HTTP状态码 | 业务错误码 | 错误消息             |
| ---------------- | ---------- | ---------- | -------------------- |
| 参数校验失败     | 400        | 1001       | 参数校验失败         |
| 用户名或密码错误 | 400        | 1002       | 用户名或密码错误     |
| Token无效        | 401        | 1003       | 认证失败，请重新登录 |
| 权限不足         | 403        | 1004       | 权限不足             |
| 资源不存在       | 404        | 1005       | 请求的资源不存在     |
| 资源已存在       | 409        | 1006       | 资源已存在           |
| 请求频率限制     | 429        | 1007       | 请求过于频繁         |
| 系统错误         | 500        | 2001       | 系统内部错误         |
| 数据库错误       | 500        | 2002       | 数据存储错误         |
| 第三方服务错误   | 502        | 2003       | 外部服务错误         |

### 4. 错误日志记录

```typescript
// 错误日志应包含的信息
{
  timestamp: "2024-01-01T12:00:00Z",
  level: "ERROR",
  message: "用户登录失败",
  traceId: "req-uuid-123",
  userId: "user-456",
  ip: "192.168.1.100",
  userAgent: "Mozilla/5.0...",
  path: "/api/login",
  method: "POST",
  statusCode: 400,
  errorCode: 1002,
  errorType: "BUSINESS_ERROR",
  stack: "错误堆栈信息...",
  requestBody: { /* 脱敏后的请求数据 */ },
  context: { /* 其他上下文信息 */ }
}
```

### 5. 客户端错误处理建议

```typescript
// 客户端错误处理示例
async function handleApiError(error: ApiError) {
    const { status, data } = error.response;

    switch (status) {
        case 400:
            // 显示参数错误信息
            showValidationErrors(data.errors);
            break;
        case 401:
            // 清除本地token，跳转登录页
            clearToken();
            redirectToLogin();
            break;
        case 403:
            // 显示权限不足提示
            showPermissionDenied();
            break;
        case 404:
            // 显示资源不存在
            showNotFound();
            break;
        case 429:
            // 实现指数退避重试
            await retryWithBackoff();
            break;
        case 500:
        case 502:
        case 503:
        case 504:
            // 显示系统错误，建议稍后重试
            showSystemError(data.message);
            break;
        default:
            // 显示通用错误信息
            showGenericError();
    }
}
```

### 6. 监控和告警

- **4xx错误**: 监控客户端错误趋势，可能表示API设计问题
- **5xx错误**: 立即告警，表示系统问题需要紧急处理
- **特定错误码**: 针对业务关键错误设置专门监控
- **错误率阈值**: 设置错误率阈值告警

---

## 总结

正确使用HTTP状态码是RESTful API设计的重要组成部分。遵循标准的状态码使用规范，结合清晰的错误消息和完善的错误处理机制，能够显著提升API的可用性和开发体验。

### 关键原则

1. **语义明确**: 状态码应准确反映请求的处理结果
2. **一致性**: 相同类型的错误应使用相同的状态码
3. **用户友好**: 错误消息应易于理解且可操作
4. **安全性**: 生产环境不暴露敏感系统信息
5. **可追踪**: 每个错误都应有唯一标识便于追踪
6. **可监控**: 重要错误应有相应的监控和告警机制

正确实施这些错误处理策略将大大提升系统的健壮性和可维护性。