create-dp-koa 1.0.0

package/template/docs/ENTERPRISE_ERROR_HANDLING_GUIDE.md

@@ -0,0 +1,357 @@
+# 企业级异常处理系统文档
+
+## 概述
+
+本文档描述了 dp-koa-framework 框架的企业级异常处理系统，该系统完全符合企业开发规范，提供了完整的错误分类、安全防护、监控告警和标准化响应功能。
+
+## 架构设计
+
+### 设计原则
+
+1. **分层架构**：框架层完全独立，不依赖业务层实现
+2. **安全优先**：敏感信息自动过滤，防止信息泄露
+3. **标准化**：统一的错误码和响应格式
+4. **可观测性**：完整的日志记录和监控告警
+5. **环境适配**：开发/生产环境差异化处理
+
+### 核心组件
+
+```mermaid
+graph TD
+    A[异常发生] --> B[错误分类和标准化]
+    B --> C[安全信息过滤]
+    C --> D[结构化日志记录]
+    D --> E{严重程度检查}
+    E -->|high/critical| F[触发告警]
+    E -->|low/medium| G[记录日志]
+    F --> H[构建标准化响应]
+    G --> H
+    H --> I[设置安全响应头]
+    I --> J[返回错误响应]
+```
+
+## 错误分类系统
+
+### 错误分类枚举
+
+```typescript
+enum ErrorCategory {
+    VALIDATION = 'VALIDATION_ERROR',           // 验证错误
+    AUTHENTICATION = 'AUTH_ERROR',             // 认证错误
+    AUTHORIZATION = 'AUTHZ_ERROR',             // 授权错误
+    BUSINESS_LOGIC = 'BUSINESS_ERROR',         // 业务逻辑错误
+    DATABASE = 'DATABASE_ERROR',               // 数据库错误
+    EXTERNAL_SERVICE = 'EXTERNAL_SERVICE_ERROR', // 外部服务错误
+    SYSTEM = 'SYSTEM_ERROR',                   // 系统错误
+    NETWORK = 'NETWORK_ERROR',                 // 网络错误
+    UNKNOWN = 'UNKNOWN_ERROR'                  // 未知错误
+}
+```
+
+### 错误码定义
+
+```typescript
+enum ErrorCode {
+    // 4xx 客户端错误
+    INVALID_REQUEST = 'E400001',              // 无效请求
+    VALIDATION_FAILED = 'E400002',            // 验证失败
+    UNAUTHORIZED = 'E401001',                 // 未授权
+    FORBIDDEN = 'E403001',                    // 禁止访问
+    NOT_FOUND = 'E404001',                    // 资源不存在
+    METHOD_NOT_ALLOWED = 'E405001',           // 方法不允许
+    CONFLICT = 'E409001',                     // 冲突
+    
+    // 5xx 服务器错误
+    INTERNAL_ERROR = 'E500001',               // 内部错误
+    DATABASE_ERROR = 'E500002',               // 数据库错误
+    EXTERNAL_SERVICE_ERROR = 'E500003',       // 外部服务错误
+    SERVICE_UNAVAILABLE = 'E503001',          // 服务不可用
+    TIMEOUT = 'E504001'                       // 超时
+}
+```
+
+## 安全防护
+
+### 敏感信息过滤
+
+系统自动过滤以下敏感字段：
+- `password` - 密码
+- `token` - 令牌
+- `secret` - 密钥
+- `key` - 密钥
+- `auth` - 认证信息
+- `credential` - 凭据
+
+### URL 安全过滤
+
+- 支持相对路径和完整URL的安全过滤
+- 自动移除查询参数中的敏感信息
+- 容错处理，确保系统稳定性
+
+### 安全响应头
+
+```typescript
+// 防止信息泄露
+ctx.set('X-Content-Type-Options', 'nosniff');
+ctx.set('X-Frame-Options', 'DENY');
+ctx.set('X-XSS-Protection', '1; mode=block');
+
+// 移除可能泄露信息的头
+ctx.remove('X-Powered-By');
+ctx.remove('Server');
+```
+
+## 日志记录
+
+### 结构化日志格式
+
+```json
+{
+  "timestamp": "2025-10-25T23:01:31.441Z",
+  "level": "ERROR",
+  "category": "default",
+  "message": "企业级异常处理",
+  "service": "dp-koa-framework",
+  "version": "1.0.0",
+  "environment": "development",
+  "error": {
+    "category": "DATABASE_ERROR",
+    "code": "E500002",
+    "message": "数据库操作失败",
+    "stack": "...",
+    "statusCode": 500,
+    "severity": "high"
+  },
+  "request": {
+    "method": "POST",
+    "url": "/api/users?token=***REDACTED***",
+    "userAgent": "Mozilla/5.0...",
+    "ip": "127.0.0.1",
+    "requestId": "req-123456",
+    "userId": "user-789"
+  },
+  "context": {
+    "timestamp": "2025-10-25T23:01:31.441Z",
+    "environment": "development",
+    "service": "dp-koa-framework",
+    "version": "1.0.0"
+  }
+}
+```
+
+## 监控告警
+
+### 告警触发条件
+
+- **Critical** 级别错误：系统级错误，需要立即处理
+- **High** 级别错误：严重错误，需要及时处理
+
+### 告警信息
+
+```json
+{
+  "alert": {
+    "level": "high",
+    "category": "DATABASE_ERROR",
+    "code": "E500002",
+    "message": "数据库操作失败",
+    "timestamp": "2025-10-25T23:01:31.441Z"
+  },
+  "request": {
+    "method": "POST",
+    "url": "/api/users?token=***REDACTED***",
+    "ip": "127.0.0.1",
+    "requestId": "req-123456"
+  }
+}
+```
+
+## 标准化响应
+
+### 响应格式
+
+#### 生产环境响应
+```json
+{
+  "success": false,
+  "error": {
+    "code": "E500002",
+    "category": "DATABASE_ERROR",
+    "message": "数据库操作失败",
+    "timestamp": "2025-10-25T23:01:31.441Z",
+    "requestId": "req-123456"
+  }
+}
+```
+
+#### 开发环境响应
+```json
+{
+  "success": false,
+  "error": {
+    "code": "E500002",
+    "category": "DATABASE_ERROR",
+    "message": "数据库操作失败",
+    "timestamp": "2025-10-25T23:01:31.441Z",
+    "requestId": "req-123456"
+  },
+  "debug": {
+    "stack": "Error: ER_ACCESS_DENIED_ERROR...",
+    "originalError": { ... }
+  }
+}
+```
+
+## 错误处理流程
+
+### 1. 异常捕获
+```typescript
+try {
+    await next();
+} catch (err) {
+    // 异常处理逻辑
+}
+```
+
+### 2. 错误分类
+- 根据错误类型自动分类
+- 设置对应的错误码和状态码
+- 确定错误严重程度
+
+### 3. 安全过滤
+- 过滤敏感信息
+- 安全化URL参数
+- 保护系统信息
+
+### 4. 日志记录
+- 记录结构化日志
+- 包含完整上下文信息
+- 支持日志分析和监控
+
+### 5. 告警触发
+- 严重错误自动告警
+- 可集成外部告警系统
+- 支持多种告警方式
+
+### 6. 响应构建
+- 构建标准化响应
+- 环境差异化处理
+- 设置安全响应头
+
+## 使用示例
+
+### 业务层抛出异常
+
+```typescript
+// 验证错误
+throw new Error('ValidationError: 用户名不能为空');
+
+// 认证错误
+const authError = new Error('UnauthorizedError');
+authError.status = 401;
+throw authError;
+
+// 业务逻辑错误
+const businessError = new Error('NotFoundError');
+businessError.status = 404;
+throw businessError;
+```
+
+### 框架层自动处理
+
+框架层会自动：
+1. 识别错误类型
+2. 分类和标准化
+3. 安全过滤
+4. 记录日志
+5. 触发告警（如需要）
+6. 返回标准化响应
+
+## 配置说明
+
+### 环境变量
+
+- `NODE_ENV`: 环境标识（development/production）
+- `npm_package_version`: 应用版本号
+
+### 敏感字段配置
+
+可在 `sanitizeErrorForLogging` 函数中自定义敏感字段列表：
+
+```typescript
+const sensitiveFields = [
+    'password', 'token', 'secret', 'key', 
+    'auth', 'credential', 'ssn', 'creditCard'
+];
+```
+
+## 最佳实践
+
+### 1. 错误抛出
+- 使用标准的错误类型
+- 设置合适的HTTP状态码
+- 提供清晰的错误信息
+
+### 2. 日志监控
+- 定期检查错误日志
+- 关注严重错误告警
+- 分析错误趋势和模式
+
+### 3. 安全防护
+- 定期审查敏感字段列表
+- 确保生产环境不泄露调试信息
+- 监控异常访问模式
+
+### 4. 性能优化
+- 避免在错误处理中执行耗时操作
+- 合理设置告警阈值
+- 优化日志记录性能
+
+## 扩展说明
+
+### 自定义错误分类
+
+可以通过修改 `classifyAndStandardizeError` 函数来添加自定义错误分类：
+
+```typescript
+if (error.name === 'CustomBusinessError') {
+    return {
+        category: ErrorCategory.BUSINESS_LOGIC,
+        code: ErrorCode.CUSTOM_BUSINESS_ERROR,
+        statusCode: 400,
+        severity: 'medium',
+        message: '自定义业务错误'
+    };
+}
+```
+
+### 集成外部告警系统
+
+可以在 `triggerErrorAlert` 函数中集成外部告警系统：
+
+```typescript
+// 钉钉告警
+await sendDingTalkAlert(errorInfo);
+
+// 企业微信告警
+await sendWeChatAlert(errorInfo);
+
+// 邮件告警
+await sendEmailAlert(errorInfo);
+```
+
+## 总结
+
+企业级异常处理系统提供了：
+
+✅ **完整的错误分类和标准化**  
+✅ **强大的安全防护机制**  
+✅ **结构化的日志记录**  
+✅ **智能的监控告警**  
+✅ **标准化的响应格式**  
+✅ **环境适配能力**  
+✅ **高度可扩展性**  
+
+该系统完全符合企业开发规范，能够满足企业级应用的严格要求，为系统的稳定性和可维护性提供了强有力的保障。
+
+