# 错误码规范

::: info 错误码定义

本文档定义了 wwjcloud 框架的错误码规范，确保错误处理的一致性和可维护性。

:::

## 错误码分类

### 📋 错误码结构

错误码采用分层设计，便于分类和管理：

```typescript
interface ErrorCode {
  code: number;        // 错误码
  message: string;     // 错误消息
  category: string;    // 错误分类
}
```

### 🎯 错误码范围

- **1000-1999**：用户相关错误
- **2000-2999**：权限相关错误
- **3000-3999**：数据相关错误
- **4000-4999**：业务相关错误
- **5000-5999**：系统相关错误

## HTTP 状态码

### ✅ 成功状态码

```typescript
200: 'OK'                    // 请求成功
201: 'Created'               // 资源创建成功
204: 'No Content'            // 请求成功，无返回内容
```

### ❌ 客户端错误

```typescript
400: 'Bad Request'           // 请求参数错误
401: 'Unauthorized'          // 未授权访问
403: 'Forbidden'             // 禁止访问
404: 'Not Found'             // 资源不存在
409: 'Conflict'              // 资源冲突
422: 'Unprocessable Entity'  // 请求格式正确但语义错误
```

### 🔧 服务器错误

```typescript
500: 'Internal Server Error' // 服务器内部错误
502: 'Bad Gateway'           // 网关错误
503: 'Service Unavailable'   // 服务不可用
```

## 业务错误码

### 👤 用户相关错误 (1000-1999)

```typescript
// 用户认证
1001: '用户不存在'
1002: '用户名或密码错误'
1003: '用户已被禁用'

// 用户信息
1010: '用户名已存在'
1011: '邮箱已存在'
1012: '用户名格式不正确'
1013: '邮箱格式不正确'
```

### 🔐 权限相关错误 (2000-2999)

```typescript
// 权限验证
2001: '权限不足'
2002: '角色不存在'
2003: 'Token 无效'
2004: 'Token 已过期'

// 角色管理
2010: '角色名已存在'
2011: '角色已被使用'
```

### 💾 数据相关错误 (3000-3999)

```typescript
// 数据操作
3001: '数据不存在'
3002: '数据已存在'
3003: '数据状态错误'

// 数据库操作
3010: '数据库连接失败'
3011: '数据库查询失败'
```

### 🏢 业务相关错误 (4000-4999)

```typescript
// 会员管理
4001: '会员不存在'
4002: '会员状态错误'
4003: '会员等级不存在'

// 订单管理
4010: '订单不存在'
4011: '订单状态错误'
```

## 错误响应格式

### 📊 标准错误响应

```typescript
interface ErrorResponse {
  code: number;        // 错误码
  message: string;     // 错误消息
  data: {
    error_code: number;    // 业务错误码
    error_message: string; // 业务错误消息
  };
  timestamp: number;   // 时间戳
}
```

### 📝 错误响应示例

**参数验证错误：**
```json
{
  "code": 400,
  "message": "请求参数错误",
  "data": {
    "error_code": 1013,
    "error_message": "用户名格式不正确"
  },
  "timestamp": 1640995200
}
```

**权限不足错误：**
```json
{
  "code": 403,
  "message": "禁止访问",
  "data": {
    "error_code": 2001,
    "error_message": "权限不足"
  },
  "timestamp": 1640995200
}
```

## 错误处理实现

### 🔧 业务异常类

```typescript
export class BusinessException extends HttpException {
  constructor(
    private readonly errorCode: number,
    private readonly errorMessage: string,
    status: number = 400
  ) {
    super(errorMessage, status);
  }

  getErrorCode(): number {
    return this.errorCode;
  }

  getErrorMessage(): string {
    return this.errorMessage;
  }
}
```

### 📝 使用示例

```typescript
@Controller('api/members')
export class MemberController {
  @Post()
  async createMember(@Body() memberData: CreateMemberDto) {
    // 检查用户名是否存在
    const existingMember = await this.memberService.findByUsername(memberData.username);
    if (existingMember) {
      throw new BusinessException(1010, '用户名已存在');
    }

    // 创建会员
    const member = await this.memberService.create(memberData);
    return {
      code: 200,
      message: '创建成功',
      data: member,
      timestamp: Math.floor(Date.now() / 1000)
    };
  }
}
```

## 最佳实践

### ✅ 推荐做法

1. **统一错误码**：使用统一的错误码规范
2. **详细错误信息**：提供详细的错误信息
3. **错误分类**：按功能模块分类错误码
4. **错误日志**：记录错误日志便于排查

### ❌ 避免做法

1. **不要暴露敏感信息**：错误信息不要包含敏感数据
2. **不要返回不一致的格式**：保持错误响应格式一致
3. **不要忽略错误处理**：所有错误都要有相应的处理

## 下一步

::: tip 深入学习

1. **查看响应格式规范**：了解统一的响应格式
2. **阅读 API 设计规范**：了解 API 设计原则
3. **参考开发规范**：遵循开发规范

:::

::: warning 注意事项

- 严格遵循错误码规范
- 提供详细的错误信息
- 实现统一的错误处理
- 记录错误日志便于排查

::: 