create-dp-koa 1.0.0

package/template/docs/ENTERPRISE_ANNOTATION_SYSTEM_GUIDE.md

@@ -0,0 +1,2069 @@
+# 🏢 企业级注解系统使用指南
+
+## 📋 目录
+
+- [系统概述](#系统概述)
+- [架构设计](#架构设计)
+- [核心组件](#核心组件)
+- [企业级注解](#企业级注解)
+- [使用示例](#使用示例)
+- [最佳实践](#最佳实践)
+- [配置管理](#配置管理)
+- [监控和告警](#监控和告警)
+- [安全审计](#安全审计)
+- [分布式追踪](#分布式追踪)
+- [故障排除](#故障排除)
+
+## 🎯 系统概述
+
+企业级注解系统是一个功能完整、可扩展的注解处理框架，专为企业级应用设计。它提供了性能监控、安全审计、分布式追踪、配置管理等核心功能，满足现代企业应用的各种需求。
+
+### ✨ 核心特性
+
+- **🔧 模块化架构**: 清晰的职责分离，易于扩展和维护
+- **🛡️ 企业级安全**: 完整的安全审计和合规性支持
+- **📊 性能监控**: 详细的性能指标和实时告警
+- **🔍 分布式追踪**: 跨服务请求追踪和性能分析
+- **⚙️ 配置管理**: 动态配置和环境变量管理
+- **📝 类型安全**: 完整的 TypeScript 支持
+- **🚀 高性能**: 优化的执行性能和内存使用
+
+## 🏗️ 架构设计
+
+### 整体架构图
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    企业级注解系统架构                           │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
+│  │   业务层    │  │   框架层    │  │   基础层    │          │
+│  │             │  │             │  │             │          │
+│  │ • 自定义注解 │  │ • 核心注解  │  │ • 装饰器    │          │
+│  │ • 业务逻辑  │  │ • 路由系统  │  │ • 元数据    │          │
+│  │ • 领域模型  │  │ • 中间件    │  │ • 反射系统  │          │
+│  └─────────────┘  └─────────────┘  └─────────────┘          │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
+│  │ 性能监控    │  │ 安全审计    │  │ 分布式追踪  │          │
+│  │             │  │             │  │             │          │
+│  │ • 执行时间  │  │ • 访问日志  │  │ • 请求追踪  │          │
+│  │ • 内存使用  │  │ • 合规检查  │  │ • 性能分析  │          │
+│  │ • CPU 使用  │  │ • 风险评估  │  │ • 服务依赖  │          │
+│  └─────────────┘  └─────────────┘  └─────────────┘          │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
+│  │ 配置管理    │  │ 日志系统    │  │ 告警系统    │          │
+│  │             │  │             │  │             │          │
+│  │ • 动态配置  │  │ • 结构化日志│  │ • 实时告警  │          │
+│  │ • 环境变量  │  │ • 日志级别  │  │ • 阈值监控  │          │
+│  │ • 配置验证  │  │ • 日志聚合  │  │ • 通知系统  │          │
+│  └─────────────┘  └─────────────┘  └─────────────┘          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 组件关系图
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│  注解装饰器      │    │  注解处理器      │    │  注解注册中心    │
+│                 │    │                 │    │                 │
+│ @EnterprisePerf │───▶│ EnterprisePerf  │───▶│ AnnotationReg   │
+│ @SecurityAudit  │    │ SecurityAudit   │    │                 │
+│ @DistributedTrac│    │ DistributedTrac  │    │                 │
+│ @ConfigMgmt     │    │ ConfigMgmt      │    │                 │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+         │                       │                       │
+         ▼                       ▼                       ▼
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│  注解执行器      │    │  注解初始化器    │    │  注解配置       │
+│                 │    │                 │    │                 │
+│ AnnotationExec  │◀───│ AnnotationInit  │◀───│ AnnotationConf  │
+│                 │    │                 │    │                 │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+## 🔧 核心组件
+
+### 1. 注解注册中心 (AnnotationRegistry)
+
+负责管理所有注解处理器的注册、查找和执行。
+
+```typescript
+import { annotationRegistry } from '@src/framework/decorator/processor/AnnotationRegistry';
+
+// 注册注解处理器
+annotationRegistry.registerProcessor(new EnterprisePerformanceProcessor());
+
+// 获取注解处理器
+const processor = annotationRegistry.getProcessor('EnterprisePerformance');
+
+// 获取所有处理器
+const allProcessors = annotationRegistry.getAllProcessors();
+```
+
+### 2. 注解执行器 (AnnotationExecutor)
+
+负责执行注解处理器的逻辑。
+
+```typescript
+import { AnnotationExecutor } from '@src/framework/decorator/processor/AnnotationProcessor';
+
+const executor = new AnnotationExecutor();
+await executor.execute(ctx, controller, methodName, callParams);
+```
+
+### 3. 注解系统初始化器 (AnnotationSystemInitializer)
+
+负责在应用启动时初始化整个注解系统。
+
+```typescript
+import { AnnotationSystemInitializer } from '@src/framework/decorator/processor/AnnotationSystemInitializer';
+
+// 在应用启动时调用
+AnnotationSystemInitializer.initialize();
+```
+
+## 🏢 企业级注解
+
+### 1. 企业级性能监控 (@EnterprisePerformance)
+
+提供详细的性能指标监控和告警功能。
+
+#### 配置选项
+
+```typescript
+interface PerformanceConfig {
+    maxExecutionTime?: number;        // 最大执行时间（毫秒）
+    maxMemoryUsage?: number;          // 最大内存使用（MB）
+    enableMetrics?: boolean;          // 是否启用指标收集
+    enableAlerts?: boolean;           // 是否启用告警
+    alertThresholds?: {                // 告警阈值
+        executionTime?: number;
+        memoryUsage?: number;
+        errorRate?: number;
+    };
+}
+```
+
+#### 使用示例
+
+```typescript
+import { EnterprisePerformance } from '@src/annotations/decorators/EnterprisePerformance';
+
+export class UserController {
+    @Get('/users')
+    @EnterprisePerformance({
+        maxExecutionTime: 1000,
+        maxMemoryUsage: 50,
+        enableMetrics: true,
+        enableAlerts: true,
+        alertThresholds: {
+            executionTime: 500,
+            memoryUsage: 30
+        }
+    })
+    async getUsers(@Query() query: any) {
+        // 业务逻辑
+        return { users: [] };
+    }
+}
+```
+
+#### 性能指标
+
+- **执行时间**: 方法执行的总时间
+- **内存使用**: RSS、堆使用、堆总计、外部内存
+- **CPU 使用**: 用户时间和系统时间
+- **请求大小**: 请求体大小
+- **响应大小**: 响应体大小
+
+### 2. 安全审计 (@SecurityAudit)
+
+提供完整的安全事件记录和合规性检查。
+
+#### 配置选项
+
+```typescript
+interface SecurityAuditConfig {
+    enableAudit?: boolean;             // 是否启用审计
+    logLevel?: 'info' | 'warn' | 'error'; // 日志级别
+    includeRequestData?: boolean;     // 是否包含请求数据
+    includeResponseData?: boolean;    // 是否包含响应数据
+    sensitiveFields?: string[];       // 敏感字段列表
+    complianceMode?: 'GDPR' | 'SOX' | 'HIPAA' | 'PCI-DSS'; // 合规模式
+    retentionDays?: number;           // 日志保留天数
+}
+```
+
+#### 使用示例
+
+```typescript
+import { SecurityAudit } from '@src/annotations/decorators/SecurityAudit';
+
+export class PaymentController {
+    @Post('/payments')
+    @SecurityAudit({
+        enableAudit: true,
+        logLevel: 'warn',
+        includeRequestData: true,
+        complianceMode: 'PCI-DSS',
+        sensitiveFields: ['cardNumber', 'cvv', 'amount']
+    })
+    async processPayment(@Body() payment: any) {
+        // 支付处理逻辑
+        return { success: true };
+    }
+}
+```
+
+#### 安全事件类型
+
+- **AUTHENTICATION**: 身份验证事件
+- **AUTHORIZATION**: 授权事件
+- **DATA_ACCESS**: 数据访问事件
+- **DATA_MODIFICATION**: 数据修改事件
+- **SYSTEM_ACCESS**: 系统访问事件
+
+#### 风险评估
+
+系统会根据以下因素计算风险评分（0-10分）：
+
+- HTTP 方法类型
+- 用户权限级别
+- IP 地址可疑性
+- 访问时间
+- 操作类型
+
+### 3. 分布式追踪 (@DistributedTracing)
+
+提供跨服务的请求追踪和性能分析。
+
+#### 配置选项
+
+```typescript
+interface TracingConfig {
+    enableTracing?: boolean;           // 是否启用追踪
+    traceIdHeader?: string;           // 追踪ID头名称
+    spanIdHeader?: string;            // Span ID头名称
+    parentSpanIdHeader?: string;      // 父Span ID头名称
+    samplingRate?: number;            // 采样率 (0-1)
+    exportToJaeger?: boolean;         // 是否导出到Jaeger
+    exportToZipkin?: boolean;         // 是否导出到Zipkin
+    customTags?: Record<string, string>; // 自定义标签
+}
+```
+
+#### 使用示例
+
+```typescript
+import { DistributedTracing } from '@src/annotations/decorators/DistributedTracing';
+
+export class OrderController {
+    @Get('/orders/:id')
+    @DistributedTracing({
+        enableTracing: true,
+        samplingRate: 1.0,
+        customTags: {
+            'service.version': '1.0.0',
+            'deployment.environment': 'production',
+            'business.unit': 'ecommerce'
+        }
+    })
+    async getOrder(@Params() params: any) {
+        // 订单查询逻辑
+        return { order: {} };
+    }
+}
+```
+
+#### 追踪信息
+
+- **Trace ID**: 请求的唯一标识
+- **Span ID**: 操作的唯一标识
+- **Parent Span ID**: 父操作的标识
+- **操作名称**: 控制器.方法名
+- **开始时间**: Span 开始时间
+- **结束时间**: Span 结束时间
+- **持续时间**: 操作执行时间
+- **标签**: 自定义元数据
+- **日志**: 操作过程中的日志
+
+### 4. 配置管理 (@ConfigManagement)
+
+提供动态配置和环境变量管理。
+
+#### 配置选项
+
+```typescript
+interface ConfigManagementConfig {
+    configKey?: string;               // 配置键名
+    defaultValue?: any;               // 默认值
+    required?: boolean;               // 是否必需
+    validationRules?: ValidationRule[]; // 验证规则
+    refreshInterval?: number;          // 刷新间隔
+    environment?: 'development' | 'staging' | 'production'; // 环境
+    fallbackConfig?: Record<string, any>; // 备用配置
+}
+```
+
+#### 验证规则
+
+```typescript
+interface ValidationRule {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'email' | 'url';
+    min?: number;                     // 最小值/长度
+    max?: number;                     // 最大值/长度
+    pattern?: RegExp;                 // 正则表达式
+    custom?: (value: any) => boolean; // 自定义验证
+    message?: string;                 // 错误消息
+}
+```
+
+#### 使用示例
+
+```typescript
+import { ConfigManagement } from '@src/annotations/decorators/ConfigManagement';
+
+export class ApiController {
+    @Get('/api/data')
+    @ConfigManagement({
+        configKey: 'api.timeout',
+        defaultValue: 30000,
+        required: true,
+        validationRules: [
+            { type: 'number', min: 1000, max: 300000 }
+        ]
+    })
+    @ConfigManagement({
+        configKey: 'feature.flags',
+        defaultValue: { newFeature: false },
+        validationRules: [
+            { type: 'object' },
+            { 
+                type: 'object',
+                custom: (value) => typeof value.newFeature === 'boolean'
+            }
+        ]
+    })
+    async getData(@Query() query: any) {
+        const config = this.ctx?.state.config;
+        const timeout = config['api.timeout'];
+        const featureFlags = config['feature.flags'];
+        
+        // 使用配置
+        return { data: [], timeout, featureFlags };
+    }
+}
+```
+
+## 📚 使用示例
+
+### 基础示例
+
+```typescript
+import { Get, Post, Body, Query } from '@src/framework/decorator/controller';
+import { Logging, Permission, RateLimit } from '@src/framework/decorator/processor/AnnotationDecorators';
+import { 
+    EnterprisePerformance, 
+    SecurityAudit, 
+    DistributedTracing, 
+    ConfigManagement 
+} from '@src/annotations/decorators/PerformanceMonitor';
+
+export class UserController {
+    @Get('/users')
+    @EnterprisePerformance({
+        maxExecutionTime: 1000,
+        enableMetrics: true
+    })
+    @SecurityAudit({
+        enableAudit: true,
+        logLevel: 'info'
+    })
+    @DistributedTracing({
+        enableTracing: true
+    })
+    @Logging()
+    async getUsers(@Query() query: any) {
+        return { users: [] };
+    }
+
+    @Post('/users')
+    @EnterprisePerformance({
+        maxExecutionTime: 2000,
+        enableAlerts: true
+    })
+    @SecurityAudit({
+        enableAudit: true,
+        logLevel: 'warn',
+        includeRequestData: true,
+        sensitiveFields: ['email', 'phone']
+    })
+    @Permission({ requiredPermission: 'user:create' })
+    @RateLimit({ maxRequests: 10, windowMs: 60000 })
+    @Logging()
+    async createUser(@Body() user: any) {
+        return { success: true };
+    }
+}
+```
+
+### 高级示例
+
+```typescript
+export class PaymentController {
+    @Post('/payments')
+    @EnterprisePerformance({
+        maxExecutionTime: 5000,
+        maxMemoryUsage: 100,
+        enableMetrics: true,
+        enableAlerts: true,
+        alertThresholds: {
+            executionTime: 3000,
+            memoryUsage: 80
+        }
+    })
+    @SecurityAudit({
+        enableAudit: true,
+        logLevel: 'warn',
+        includeRequestData: true,
+        includeResponseData: true,
+        complianceMode: 'PCI-DSS',
+        sensitiveFields: ['cardNumber', 'cvv', 'amount', 'account'],
+        retentionDays: 2555 // 7年
+    })
+    @DistributedTracing({
+        enableTracing: true,
+        samplingRate: 1.0,
+        customTags: {
+            'service.name': 'payment-service',
+            'operation.type': 'financial',
+            'security.level': 'high',
+            'compliance.standard': 'PCI-DSS'
+        }
+    })
+    @ConfigManagement({
+        configKey: 'payment.gateway.url',
+        defaultValue: 'https://api.payment.com',
+        required: true,
+        validationRules: [
+            { type: 'url' }
+        ]
+    })
+    @ConfigManagement({
+        configKey: 'payment.timeout',
+        defaultValue: 30000,
+        validationRules: [
+            { type: 'number', min: 5000, max: 60000 }
+        ]
+    })
+    @Permission({ requiredPermission: 'payment:process' })
+    @RateLimit({ maxRequests: 5, windowMs: 60000 })
+    @Logging()
+    async processPayment(@Body() payment: any) {
+        const config = this.ctx?.state.config;
+        const gatewayUrl = config['payment.gateway.url'];
+        const timeout = config['payment.timeout'];
+        
+        // 支付处理逻辑
+        const result = await this.callPaymentGateway(gatewayUrl, payment, timeout);
+        
+        return { success: true, transactionId: result.id };
+    }
+
+    private async callPaymentGateway(url: string, payment: any, timeout: number): Promise<any> {
+        // 模拟支付网关调用
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        return { id: 'txn_' + Date.now() };
+    }
+}
+```
+
+## 🎯 最佳实践
+
+### 1. 注解组合使用
+
+```typescript
+// ✅ 推荐：合理的注解组合
+@Get('/api/users')
+@EnterprisePerformance({ maxExecutionTime: 1000 })
+@SecurityAudit({ enableAudit: true })
+@DistributedTracing({ enableTracing: true })
+@Logging()
+async getUsers() { }
+
+// ❌ 不推荐：过多的注解
+@Get('/api/users')
+@EnterprisePerformance({ maxExecutionTime: 1000 })
+@SecurityAudit({ enableAudit: true })
+@DistributedTracing({ enableTracing: true })
+@ConfigManagement({ configKey: 'unnecessary' })
+@Permission({ requiredPermission: 'read' })
+@RateLimit({ maxRequests: 100 })
+@Logging()
+async getUsers() { }
+```
+
+### 2. 性能优化
+
+```typescript
+// ✅ 推荐：合理的性能阈值
+@EnterprisePerformance({
+    maxExecutionTime: 1000,  // 1秒
+    maxMemoryUsage: 50,      // 50MB
+    enableAlerts: true
+})
+
+// ❌ 不推荐：过于严格的阈值
+@EnterprisePerformance({
+    maxExecutionTime: 100,   // 100ms 太严格
+    maxMemoryUsage: 5,       // 5MB 太小
+    enableAlerts: true
+})
+```
+
+### 3. 安全配置
+
+```typescript
+// ✅ 推荐：完整的安全配置
+@SecurityAudit({
+    enableAudit: true,
+    logLevel: 'warn',
+    includeRequestData: true,
+    sensitiveFields: ['password', 'ssn', 'creditCard'],
+    complianceMode: 'GDPR'
+})
+
+// ❌ 不推荐：不完整的安全配置
+@SecurityAudit({
+    enableAudit: true
+    // 缺少其他重要配置
+})
+```
+
+### 4. 配置管理
+
+```typescript
+// ✅ 推荐：带验证的配置
+@ConfigManagement({
+    configKey: 'api.timeout',
+    defaultValue: 30000,
+    required: true,
+    validationRules: [
+        { type: 'number', min: 1000, max: 300000 }
+    ]
+})
+
+// ❌ 不推荐：无验证的配置
+@ConfigManagement({
+    configKey: 'api.timeout',
+    defaultValue: 30000
+    // 缺少验证规则
+})
+```
+
+## ⚙️ 配置管理
+
+### 环境变量配置
+
+```bash
+# 性能监控配置
+PERFORMANCE_ENABLED=true
+PERFORMANCE_SAMPLING_RATE=1.0
+PERFORMANCE_ALERT_THRESHOLD=1000
+
+# 安全审计配置
+SECURITY_AUDIT_ENABLED=true
+SECURITY_AUDIT_LOG_LEVEL=warn
+SECURITY_AUDIT_RETENTION_DAYS=90
+
+# 分布式追踪配置
+TRACING_ENABLED=true
+TRACING_SAMPLING_RATE=1.0
+JAEGER_ENDPOINT=http://jaeger:14268/api/traces
+ZIPKIN_ENDPOINT=http://zipkin:9411/api/v2/spans
+
+# 配置管理
+CONFIG_REFRESH_INTERVAL=60000
+CONFIG_CACHE_TTL=300000
+```
+
+### 配置文件
+
+```json
+{
+  "annotations": {
+    "enterprisePerformance": {
+      "enabled": true,
+      "samplingRate": 1.0,
+      "alertThresholds": {
+        "executionTime": 1000,
+        "memoryUsage": 50
+      }
+    },
+    "securityAudit": {
+      "enabled": true,
+      "logLevel": "warn",
+      "complianceMode": "GDPR",
+      "retentionDays": 90
+    },
+    "distributedTracing": {
+      "enabled": true,
+      "samplingRate": 1.0,
+      "exportToJaeger": true,
+      "exportToZipkin": false
+    }
+  }
+}
+```
+
+## 📊 监控和告警
+
+### 性能指标
+
+系统会自动收集以下性能指标：
+
+- **执行时间统计**: 平均值、最大值、最小值
+- **内存使用统计**: 堆使用、RSS、外部内存
+- **CPU 使用统计**: 用户时间、系统时间
+- **请求/响应大小**: 数据量统计
+- **错误率**: 失败请求比例
+
+### 告警规则
+
+```typescript
+// 性能告警配置
+const alertRules = {
+    executionTime: {
+        threshold: 1000,  // 1秒
+        severity: 'warning'
+    },
+    memoryUsage: {
+        threshold: 50,    // 50MB
+        severity: 'critical'
+    },
+    errorRate: {
+        threshold: 0.05,  // 5%
+        severity: 'warning'
+    }
+};
+```
+
+### 监控面板
+
+系统提供内置的监控面板，可以查看：
+
+- 实时性能指标
+- 历史趋势分析
+- 告警状态
+- 系统健康度
+
+## 🛡️ 安全审计
+
+### 审计日志格式
+
+```json
+{
+  "timestamp": "2024-01-01T12:00:00.000Z",
+  "userId": "user123",
+  "sessionId": "session456",
+  "ipAddress": "192.168.1.100",
+  "userAgent": "Mozilla/5.0...",
+  "method": "POST",
+  "url": "/api/payments",
+  "controller": "PaymentController",
+  "action": "processPayment",
+  "securityLevel": "CRITICAL",
+  "eventType": "DATA_MODIFICATION",
+  "riskScore": 8,
+  "complianceFlags": ["PCI-DSS_FINANCIAL_DATA"],
+  "requestData": {
+    "amount": 100.00,
+    "cardNumber": "[REDACTED]"
+  },
+  "responseData": {
+    "success": true,
+    "transactionId": "txn_123"
+  }
+}
+```
+
+### 合规性检查
+
+系统支持多种合规性标准：
+
+- **GDPR**: 欧盟通用数据保护条例
+- **SOX**: 萨班斯-奥克斯利法案
+- **HIPAA**: 健康保险可携性和责任法案
+- **PCI-DSS**: 支付卡行业数据安全标准
+
+### 风险评估
+
+系统会根据以下因素计算风险评分：
+
+1. **操作类型**: DELETE > PUT > POST > GET
+2. **用户权限**: 无权限 > 普通用户 > 管理员
+3. **IP 地址**: 可疑IP > 内网IP > 外网IP
+4. **访问时间**: 非工作时间 > 工作时间
+5. **数据敏感性**: 敏感数据 > 普通数据
+
+## 🔍 分布式追踪
+
+### 追踪上下文
+
+每个请求都会生成唯一的追踪上下文：
+
+```typescript
+interface TraceContext {
+    traceId: string;        // 请求的唯一标识
+    spanId: string;         // 当前操作的标识
+    parentSpanId?: string;  // 父操作的标识
+    baggage?: Record<string, string>; // 跨服务传递的数据
+}
+```
+
+### 服务依赖图
+
+系统会自动构建服务依赖关系图：
+
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│   Web API   │───▶│  User Svc   │───▶│  Database   │
+│             │    │             │    │             │
+└─────────────┘    └─────────────┘    └─────────────┘
+       │                   │
+       ▼                   ▼
+┌─────────────┐    ┌─────────────┐
+│  Payment Svc│    │  Email Svc  │
+│             │    │             │
+└─────────────┘    └─────────────┘
+```
+
+### 性能分析
+
+系统提供详细的性能分析：
+
+- **服务调用链**: 完整的请求路径
+- **瓶颈识别**: 最慢的服务和操作
+- **依赖分析**: 服务间的调用关系
+- **错误追踪**: 错误在调用链中的传播
+
+## 🔧 故障排除
+
+### 常见问题
+
+#### 1. 注解不生效
+
+**问题**: 注解装饰器没有执行
+
+**解决方案**:
+```typescript
+// 检查注解系统是否已初始化
+import { AnnotationSystemInitializer } from '@src/framework/decorator/processor/AnnotationSystemInitializer';
+
+if (!AnnotationSystemInitializer.isInitialized()) {
+    AnnotationSystemInitializer.initialize();
+}
+```
+
+#### 2. 性能监控数据不准确
+
+**问题**: 性能指标与实际不符
+
+**解决方案**:
+```typescript
+// 检查采样率配置
+@EnterprisePerformance({
+    enableMetrics: true,
+    samplingRate: 1.0  // 确保采样率为1.0
+})
+```
+
+#### 3. 安全审计日志过多
+
+**问题**: 审计日志产生过多噪音
+
+**解决方案**:
+```typescript
+// 调整日志级别和过滤条件
+@SecurityAudit({
+    logLevel: 'warn',  // 只记录警告和错误
+    includeRequestData: false,  // 不包含请求数据
+    sensitiveFields: ['password', 'ssn']  // 只关注敏感字段
+})
+```
+
+#### 4. 分布式追踪数据丢失
+
+**问题**: 追踪数据没有正确导出
+
+**解决方案**:
+```bash
+# 检查环境变量配置
+export JAEGER_ENDPOINT=http://jaeger:14268/api/traces
+export TRACING_SAMPLING_RATE=1.0
+export TRACING_ENABLED=true
+```
+
+### 调试技巧
+
+#### 1. 启用调试日志
+
+```typescript
+// 在注解处理器中添加调试日志
+console.log(`[${this.name}] 调试信息:`, {
+    methodName,
+    annotationData,
+    callParams
+});
+```
+
+#### 2. 检查注解注册状态
+
+```typescript
+import { annotationRegistry } from '@src/framework/decorator/processor/AnnotationRegistry';
+
+// 检查已注册的处理器
+console.log('已注册的处理器:', annotationRegistry.getRegisteredProcessors());
+
+// 检查特定处理器
+const processor = annotationRegistry.getProcessor('EnterprisePerformance');
+console.log('处理器状态:', processor);
+```
+
+#### 3. 验证配置
+
+```typescript
+// 验证配置是否正确加载
+@ConfigManagement({
+    configKey: 'debug.enabled',
+    defaultValue: false,
+    validationRules: [
+        { type: 'boolean' }
+    ]
+})
+async debugMethod() {
+    const config = this.ctx?.state.config;
+    console.log('配置状态:', config);
+}
+```
+
+### 性能优化建议
+
+#### 1. 合理设置采样率
+
+```typescript
+// 生产环境建议采样率
+@DistributedTracing({
+    samplingRate: 0.1  // 10% 采样率
+})
+
+// 开发环境可以设置更高采样率
+@DistributedTracing({
+    samplingRate: 1.0  // 100% 采样率
+})
+```
+
+#### 2. 优化内存使用
+
+```typescript
+// 定期清理过期数据
+setInterval(() => {
+    processor.cleanupExpiredSpans(3600000); // 清理1小时前的数据
+}, 300000); // 每5分钟清理一次
+```
+
+#### 3. 异步处理
+
+```typescript
+// 对于耗时的操作，使用异步处理
+async postProcess(ctx: Context, controller: any, methodName: string, response: any) {
+    // 异步处理，不阻塞响应
+    setImmediate(() => {
+        this.processAuditLog(ctx, controller, methodName, response);
+    });
+}
+```
+
+## 📈 自定义注解开发指南
+
+### 🎯 开发概述
+
+企业级注解系统提供了完整的自定义注解开发框架，支持开发者创建符合业务需求的专用注解。本章节将详细介绍如何从零开始开发自定义注解。
+
+### 📋 开发流程
+
+#### 1. 确定注解需求
+
+在开发自定义注解之前，需要明确以下问题：
+
+- **功能目标**: 注解要实现什么功能？
+- **执行时机**: 在方法执行前、后，还是两者都需要？
+- **配置参数**: 需要哪些可配置的参数？
+- **优先级**: 相对于其他注解的执行顺序？
+- **依赖关系**: 是否需要依赖其他服务或组件？
+
+#### 2. 设计注解接口
+
+```typescript
+// 定义注解配置接口
+export interface CustomAnnotationConfig {
+    // 基础配置
+    enabled?: boolean;
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    
+    // 业务特定配置
+    businessParam1?: string;
+    businessParam2?: number;
+    businessParam3?: boolean;
+    
+    // 高级配置
+    timeout?: number;
+    retryCount?: number;
+    fallbackValue?: any;
+}
+```
+
+#### 3. 实现注解处理器
+
+```typescript
+import { Context } from 'koa';
+import { AnnotationProcessor } from '@src/framework/decorator/processor/AnnotationProcessor';
+import { logger } from '@src/framework/utils/logger';
+
+/**
+ * 自定义注解处理器示例
+ * 实现业务特定的功能
+ */
+export class CustomAnnotationProcessor implements AnnotationProcessor {
+    readonly name = 'CustomAnnotation';
+    readonly priority = 20; // 设置优先级
+
+    private config: CustomAnnotationConfig = {};
+    private metrics: Map<string, any> = new Map();
+
+    constructor() {
+        this.initializeMetrics();
+    }
+
+    /**
+     * 前置处理方法
+     * 在控制器方法执行前调用
+     */
+    async process(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: CustomAnnotationConfig,
+        callParams: any[]
+    ): Promise<boolean> {
+        try {
+            // 合并配置
+            this.config = { ...this.config, ...annotationData };
+            
+            // 检查是否启用
+            if (!this.config.enabled) {
+                return true;
+            }
+
+            // 记录开始时间
+            const startTime = Date.now();
+            ctx.state.customAnnotationStartTime = startTime;
+
+            // 执行业务逻辑
+            await this.executeBusinessLogic(ctx, controller, methodName, callParams);
+
+            // 记录指标
+            this.recordMetrics(methodName, 'start', startTime);
+
+            logger.info(`[${this.name}] 开始处理: ${controller.constructor.name}.${methodName}`, {
+                config: this.config,
+                params: callParams
+            });
+
+            return true;
+
+        } catch (error) {
+            logger.error(`[${this.name}] 处理失败: ${controller.constructor.name}.${methodName}`, error);
+            
+            // 根据配置决定是否中断执行
+            if (this.config.enabled) {
+                ctx.status = 500;
+                ctx.body = { error: 'Custom annotation processing failed' };
+                return false;
+            }
+            
+            return true;
+        }
+    }
+
+    /**
+     * 后置处理方法
+     * 在控制器方法执行后调用
+     */
+    async postProcess(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        response: any
+    ): Promise<void> {
+        try {
+            if (!this.config.enabled) {
+                return;
+            }
+
+            const startTime = ctx.state.customAnnotationStartTime;
+            const endTime = Date.now();
+            const duration = startTime ? endTime - startTime : 0;
+
+            // 执行业务后置逻辑
+            await this.executePostBusinessLogic(ctx, controller, methodName, response);
+
+            // 记录指标
+            this.recordMetrics(methodName, 'end', endTime, duration);
+
+            // 记录日志
+            logger.info(`[${this.name}] 完成处理: ${controller.constructor.name}.${methodName}`, {
+                duration: `${duration}ms`,
+                response: this.sanitizeResponse(response)
+            });
+
+            // 清理上下文
+            delete ctx.state.customAnnotationStartTime;
+
+        } catch (error) {
+            logger.error(`[${this.name}] 后置处理失败: ${controller.constructor.name}.${methodName}`, error);
+        }
+    }
+
+    /**
+     * 执行业务逻辑
+     */
+    private async executeBusinessLogic(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        callParams: any[]
+    ): Promise<void> {
+        // 示例：数据验证
+        if (this.config.businessParam1) {
+            await this.validateData(ctx, callParams);
+        }
+
+        // 示例：权限检查
+        if (this.config.businessParam2) {
+            await this.checkPermissions(ctx, controller, methodName);
+        }
+
+        // 示例：缓存检查
+        if (this.config.businessParam3) {
+            await this.checkCache(ctx, methodName, callParams);
+        }
+
+        // 示例：外部服务调用
+        if (this.config.timeout) {
+            await this.callExternalService(ctx, this.config.timeout);
+        }
+    }
+
+    /**
+     * 执行后置业务逻辑
+     */
+    private async executePostBusinessLogic(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        response: any
+    ): Promise<void> {
+        // 示例：结果处理
+        await this.processResult(ctx, response);
+
+        // 示例：缓存更新
+        if (this.config.businessParam3) {
+            await this.updateCache(ctx, methodName, response);
+        }
+
+        // 示例：通知发送
+        await this.sendNotification(ctx, controller, methodName, response);
+    }
+
+    /**
+     * 数据验证
+     */
+    private async validateData(ctx: Context, callParams: any[]): Promise<void> {
+        // 实现数据验证逻辑
+        for (const param of callParams) {
+            if (param && typeof param === 'object') {
+                // 验证逻辑
+                if (!this.isValidData(param)) {
+                    throw new Error('Data validation failed');
+                }
+            }
+        }
+    }
+
+    /**
+     * 权限检查
+     */
+    private async checkPermissions(
+        ctx: Context,
+        controller: any,
+        methodName: string
+    ): Promise<void> {
+        // 实现权限检查逻辑
+        const user = ctx.state.user;
+        if (!user || !user.hasPermission(this.config.businessParam2)) {
+            throw new Error('Permission denied');
+        }
+    }
+
+    /**
+     * 缓存检查
+     */
+    private async checkCache(
+        ctx: Context,
+        methodName: string,
+        callParams: any[]
+    ): Promise<void> {
+        // 实现缓存检查逻辑
+        const cacheKey = this.generateCacheKey(methodName, callParams);
+        const cached = await this.getFromCache(cacheKey);
+        
+        if (cached) {
+            ctx.state.cachedResult = cached;
+        }
+    }
+
+    /**
+     * 外部服务调用
+     */
+    private async callExternalService(ctx: Context, timeout: number): Promise<void> {
+        // 实现外部服务调用逻辑
+        const result = await this.callWithTimeout('/api/external', timeout);
+        ctx.state.externalResult = result;
+    }
+
+    /**
+     * 结果处理
+     */
+    private async processResult(ctx: Context, response: any): Promise<void> {
+        // 实现结果处理逻辑
+        if (response && typeof response === 'object') {
+            // 处理响应数据
+            response.processedAt = new Date().toISOString();
+            response.processedBy = this.name;
+        }
+    }
+
+    /**
+     * 缓存更新
+     */
+    private async updateCache(
+        ctx: Context,
+        methodName: string,
+        response: any
+    ): Promise<void> {
+        // 实现缓存更新逻辑
+        const cacheKey = this.generateCacheKey(methodName, ctx.state.callParams);
+        await this.setCache(cacheKey, response, 300); // 5分钟过期
+    }
+
+    /**
+     * 发送通知
+     */
+    private async sendNotification(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        response: any
+    ): Promise<void> {
+        // 实现通知发送逻辑
+        const notification = {
+            controller: controller.constructor.name,
+            method: methodName,
+            timestamp: new Date().toISOString(),
+            success: response?.code === 0
+        };
+        
+        await this.sendToNotificationService(notification);
+    }
+
+    /**
+     * 记录指标
+     */
+    private recordMetrics(methodName: string, event: string, timestamp: number, duration?: number): void {
+        const key = `${methodName}_${event}`;
+        const metrics = this.metrics.get(key) || { count: 0, totalDuration: 0 };
+        
+        metrics.count++;
+        if (duration) {
+            metrics.totalDuration += duration;
+        }
+        
+        this.metrics.set(key, metrics);
+    }
+
+    /**
+     * 初始化指标
+     */
+    private initializeMetrics(): void {
+        // 初始化指标收集
+        this.metrics = new Map();
+    }
+
+    /**
+     * 工具方法
+     */
+    private isValidData(data: any): boolean {
+        // 实现数据验证逻辑
+        return data && typeof data === 'object';
+    }
+
+    private generateCacheKey(methodName: string, params: any[]): string {
+        return `${methodName}_${JSON.stringify(params)}`;
+    }
+
+    private async getFromCache(key: string): Promise<any> {
+        // 实现缓存获取逻辑
+        return null;
+    }
+
+    private async setCache(key: string, value: any, ttl: number): Promise<void> {
+        // 实现缓存设置逻辑
+    }
+
+    private async callWithTimeout(url: string, timeout: number): Promise<any> {
+        // 实现带超时的服务调用
+        return new Promise((resolve, reject) => {
+            setTimeout(() => resolve({ data: 'external result' }), 100);
+        });
+    }
+
+    private async sendToNotificationService(notification: any): Promise<void> {
+        // 实现通知发送逻辑
+        console.log('Sending notification:', notification);
+    }
+
+    private sanitizeResponse(response: any): any {
+        // 实现响应数据脱敏
+        if (response && typeof response === 'object') {
+            const sanitized = { ...response };
+            // 移除敏感信息
+            delete sanitized.password;
+            delete sanitized.token;
+            return sanitized;
+        }
+        return response;
+    }
+
+    /**
+     * 获取指标统计
+     */
+    getMetrics(): Map<string, any> {
+        return new Map(this.metrics);
+    }
+
+    /**
+     * 清理指标
+     */
+    clearMetrics(): void {
+        this.metrics.clear();
+    }
+}
+```
+
+#### 4. 创建注解装饰器
+
+```typescript
+import { createAnnotationDecorator } from '@src/framework/decorator/processor/AnnotationDecorators';
+import { CustomAnnotationConfig } from './CustomAnnotationProcessor';
+
+/**
+ * 自定义注解装饰器
+ * 提供类型安全的配置接口
+ */
+export function CustomAnnotation(config?: CustomAnnotationConfig) {
+    return createAnnotationDecorator('CustomAnnotation')(config);
+}
+
+/**
+ * 带默认配置的装饰器变体
+ */
+export function CustomAnnotationWithDefaults(config?: Partial<CustomAnnotationConfig>) {
+    const defaultConfig: CustomAnnotationConfig = {
+        enabled: true,
+        logLevel: 'info',
+        businessParam1: 'default',
+        businessParam2: 0,
+        businessParam3: false,
+        timeout: 5000,
+        retryCount: 3,
+        fallbackValue: null
+    };
+
+    return CustomAnnotation({ ...defaultConfig, ...config });
+}
+
+/**
+ * 简化版装饰器
+ */
+export function SimpleCustomAnnotation(enabled: boolean = true) {
+    return CustomAnnotation({ enabled });
+}
+```
+
+#### 5. 注册注解处理器
+
+```typescript
+// 方式1: 在注解配置文件中注册
+// src/framework/decorator/processor/AnnotationProcessorConfig.ts
+
+import { CustomAnnotationProcessor } from '@src/annotations/processors/CustomAnnotationProcessor';
+
+export function getAllAnnotationProcessors(): AnnotationProcessor[] {
+    return [
+        // ... 其他处理器
+        new CustomAnnotationProcessor()
+    ];
+}
+
+// 方式2: 动态注册
+// src/app.ts 或初始化文件中
+
+import { annotationRegistry } from '@src/framework/decorator/processor/AnnotationRegistry';
+import { CustomAnnotationProcessor } from '@src/annotations/processors/CustomAnnotationProcessor';
+
+// 在应用启动时注册
+annotationRegistry.registerProcessor(new CustomAnnotationProcessor());
+```
+
+#### 6. 使用自定义注解
+
+```typescript
+import { Get, Post, Body, Query } from '@src/framework/decorator/controller';
+import { Logging } from '@src/framework/decorator/processor/AnnotationDecorators';
+import { CustomAnnotation, CustomAnnotationWithDefaults } from '@src/annotations/decorators/CustomAnnotation';
+
+export class BusinessController {
+    
+    /**
+     * 基础使用
+     */
+    @Get('/business/basic')
+    @CustomAnnotation({
+        enabled: true,
+        logLevel: 'info',
+        businessParam1: 'test',
+        timeout: 3000
+    })
+    @Logging()
+    async getBasicData(@Query() query: any) {
+        return { data: 'basic data' };
+    }
+
+    /**
+     * 使用默认配置
+     */
+    @Post('/business/advanced')
+    @CustomAnnotationWithDefaults({
+        businessParam2: 100,
+        retryCount: 5
+    })
+    @Logging()
+    async createAdvancedData(@Body() data: any) {
+        return { success: true, data };
+    }
+
+    /**
+     * 简化使用
+     */
+    @Get('/business/simple')
+    @SimpleCustomAnnotation(true)
+    @Logging()
+    async getSimpleData() {
+        return { data: 'simple data' };
+    }
+}
+```
+
+### 🔧 高级开发技巧
+
+#### 1. 注解组合模式
+
+```typescript
+/**
+ * 组合多个注解功能
+ */
+export class CompositeAnnotationProcessor implements AnnotationProcessor {
+    readonly name = 'CompositeAnnotation';
+    readonly priority = 1;
+
+    private processors: AnnotationProcessor[] = [];
+
+    constructor() {
+        // 组合多个处理器
+        this.processors.push(new ValidationProcessor());
+        this.processors.push(new CacheProcessor());
+        this.processors.push(new MetricsProcessor());
+    }
+
+    async process(ctx: Context, controller: any, methodName: string, annotationData: any, callParams: any[]): Promise<boolean> {
+        // 按顺序执行所有处理器
+        for (const processor of this.processors) {
+            const result = await processor.process(ctx, controller, methodName, annotationData, callParams);
+            if (!result) {
+                return false; // 任何一个失败就中断
+            }
+        }
+        return true;
+    }
+
+    async postProcess(ctx: Context, controller: any, methodName: string, response: any): Promise<void> {
+        // 按相反顺序执行后置处理
+        for (let i = this.processors.length - 1; i >= 0; i--) {
+            const processor = this.processors[i];
+            if (processor.postProcess) {
+                await processor.postProcess(ctx, controller, methodName, response);
+            }
+        }
+    }
+}
+```
+
+#### 2. 条件执行注解
+
+```typescript
+/**
+ * 基于条件的注解处理器
+ */
+export class ConditionalAnnotationProcessor implements AnnotationProcessor {
+    readonly name = 'ConditionalAnnotation';
+    readonly priority = 15;
+
+    async process(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: { condition: (ctx: Context) => boolean; processor: AnnotationProcessor },
+        callParams: any[]
+    ): Promise<boolean> {
+        // 检查条件
+        if (annotationData.condition && annotationData.condition(ctx)) {
+            // 条件满足时执行处理器
+            return await annotationData.processor.process(ctx, controller, methodName, annotationData, callParams);
+        }
+        
+        return true; // 条件不满足时跳过
+    }
+}
+
+// 使用示例
+@ConditionalAnnotation({
+    condition: (ctx) => ctx.state.user?.isAdmin,
+    processor: new AdminOnlyProcessor()
+})
+async adminOnlyMethod() { }
+```
+
+#### 3. 异步注解处理器
+
+```typescript
+/**
+ * 支持异步操作的注解处理器
+ */
+export class AsyncAnnotationProcessor implements AnnotationProcessor {
+    readonly name = 'AsyncAnnotation';
+    readonly priority = 10;
+
+    private asyncOperations: Map<string, Promise<any>> = new Map();
+
+    async process(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: { asyncOperation: () => Promise<any> },
+        callParams: any[]
+    ): Promise<boolean> {
+        try {
+            // 启动异步操作
+            const operationKey = `${controller.constructor.name}.${methodName}`;
+            const operation = annotationData.asyncOperation();
+            
+            this.asyncOperations.set(operationKey, operation);
+            
+            // 不等待完成，继续执行控制器方法
+            return true;
+            
+        } catch (error) {
+            logger.error(`[${this.name}] 异步操作启动失败:`, error);
+            return true; // 异步操作失败不影响主流程
+        }
+    }
+
+    async postProcess(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        response: any
+    ): Promise<void> {
+        const operationKey = `${controller.constructor.name}.${methodName}`;
+        const operation = this.asyncOperations.get(operationKey);
+        
+        if (operation) {
+            try {
+                // 等待异步操作完成
+                const result = await operation;
+                logger.info(`[${this.name}] 异步操作完成:`, result);
+                
+                // 清理
+                this.asyncOperations.delete(operationKey);
+                
+            } catch (error) {
+                logger.error(`[${this.name}] 异步操作失败:`, error);
+            }
+        }
+    }
+}
+```
+
+#### 4. 注解链式调用
+
+```typescript
+/**
+ * 支持链式调用的注解处理器
+ */
+export class ChainableAnnotationProcessor implements AnnotationProcessor {
+    readonly name = 'ChainableAnnotation';
+    readonly priority = 5;
+
+    private chain: AnnotationProcessor[] = [];
+
+    addProcessor(processor: AnnotationProcessor): ChainableAnnotationProcessor {
+        this.chain.push(processor);
+        return this;
+    }
+
+    async process(ctx: Context, controller: any, methodName: string, annotationData: any, callParams: any[]): Promise<boolean> {
+        for (const processor of this.chain) {
+            const result = await processor.process(ctx, controller, methodName, annotationData, callParams);
+            if (!result) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    async postProcess(ctx: Context, controller: any, methodName: string, response: any): Promise<void> {
+        for (let i = this.chain.length - 1; i >= 0; i--) {
+            const processor = this.chain[i];
+            if (processor.postProcess) {
+                await processor.postProcess(ctx, controller, methodName, response);
+            }
+        }
+    }
+}
+
+// 使用示例
+const chainProcessor = new ChainableAnnotationProcessor()
+    .addProcessor(new ValidationProcessor())
+    .addProcessor(new CacheProcessor())
+    .addProcessor(new MetricsProcessor());
+
+annotationRegistry.registerProcessor(chainProcessor);
+```
+
+### 🧪 测试自定义注解
+
+#### 1. 单元测试
+
+```typescript
+import { CustomAnnotationProcessor } from '../CustomAnnotationProcessor';
+import { Context } from 'koa';
+
+describe('CustomAnnotationProcessor', () => {
+    let processor: CustomAnnotationProcessor;
+    let mockContext: Partial<Context>;
+
+    beforeEach(() => {
+        processor = new CustomAnnotationProcessor();
+        mockContext = {
+            state: {},
+            status: 200,
+            body: null
+        };
+    });
+
+    it('should process annotation successfully', async () => {
+        const config = {
+            enabled: true,
+            logLevel: 'info',
+            businessParam1: 'test'
+        };
+
+        const result = await processor.process(
+            mockContext as Context,
+            {},
+            'testMethod',
+            config,
+            [{ test: 'data' }]
+        );
+
+        expect(result).toBe(true);
+        expect(mockContext.state.customAnnotationStartTime).toBeDefined();
+    });
+
+    it('should handle disabled annotation', async () => {
+        const config = { enabled: false };
+
+        const result = await processor.process(
+            mockContext as Context,
+            {},
+            'testMethod',
+            config,
+            []
+        );
+
+        expect(result).toBe(true);
+        expect(mockContext.state.customAnnotationStartTime).toBeUndefined();
+    });
+
+    it('should record metrics correctly', async () => {
+        const config = { enabled: true };
+
+        await processor.process(mockContext as Context, {}, 'testMethod', config, []);
+        await processor.postProcess(mockContext as Context, {}, 'testMethod', {});
+
+        const metrics = processor.getMetrics();
+        expect(metrics.has('testMethod_start')).toBe(true);
+        expect(metrics.has('testMethod_end')).toBe(true);
+    });
+});
+```
+
+#### 2. 集成测试
+
+```typescript
+import request from 'supertest';
+import { app } from '../app';
+
+describe('Custom Annotation Integration', () => {
+    it('should work with custom annotation', async () => {
+        const response = await request(app)
+            .get('/business/basic')
+            .query({ test: 'data' })
+            .expect(200);
+
+        expect(response.body.data).toBeDefined();
+    });
+
+    it('should handle annotation errors gracefully', async () => {
+        const response = await request(app)
+            .post('/business/error')
+            .send({ invalid: 'data' })
+            .expect(500);
+
+        expect(response.body.error).toBeDefined();
+    });
+});
+```
+
+### 📚 最佳实践
+
+#### 1. 命名规范
+
+```typescript
+// ✅ 好的命名
+export class UserValidationProcessor implements AnnotationProcessor {
+    readonly name = 'UserValidation';
+}
+
+export function UserValidation(config?: UserValidationConfig) {
+    return createAnnotationDecorator('UserValidation')(config);
+}
+
+// ❌ 不好的命名
+export class Processor1 implements AnnotationProcessor {
+    readonly name = 'proc1';
+}
+```
+
+#### 2. 错误处理
+
+```typescript
+export class RobustAnnotationProcessor implements AnnotationProcessor {
+    readonly name = 'RobustAnnotation';
+    readonly priority = 10;
+
+    async process(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: any,
+        callParams: any[]
+    ): Promise<boolean> {
+        try {
+            // 主要逻辑
+            return await this.executeMainLogic(ctx, controller, methodName, annotationData, callParams);
+            
+        } catch (error) {
+            // 记录错误但不中断流程
+            logger.error(`[${this.name}] 处理失败:`, error);
+            
+            // 根据配置决定是否中断
+            if (annotationData?.strictMode) {
+                ctx.status = 500;
+                ctx.body = { error: 'Annotation processing failed' };
+                return false;
+            }
+            
+            return true; // 非严格模式下继续执行
+        }
+    }
+
+    private async executeMainLogic(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: any,
+        callParams: any[]
+    ): Promise<boolean> {
+        // 实现主要逻辑
+        return true;
+    }
+}
+```
+
+#### 3. 性能优化
+
+```typescript
+export class OptimizedAnnotationProcessor implements AnnotationProcessor {
+    readonly name = 'OptimizedAnnotation';
+    readonly priority = 10;
+
+    private cache = new Map<string, any>();
+    private metrics = new Map<string, number>();
+
+    async process(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: any,
+        callParams: any[]
+    ): Promise<boolean> {
+        const startTime = Date.now();
+        
+        try {
+            // 使用缓存避免重复计算
+            const cacheKey = this.generateCacheKey(methodName, annotationData);
+            let result = this.cache.get(cacheKey);
+            
+            if (!result) {
+                result = await this.computeResult(annotationData);
+                this.cache.set(cacheKey, result);
+            }
+            
+            // 记录性能指标
+            const duration = Date.now() - startTime;
+            this.recordMetric(methodName, duration);
+            
+            return result;
+            
+        } catch (error) {
+            logger.error(`[${this.name}] 处理失败:`, error);
+            return true;
+        }
+    }
+
+    private generateCacheKey(methodName: string, data: any): string {
+        return `${methodName}_${JSON.stringify(data)}`;
+    }
+
+    private async computeResult(data: any): Promise<boolean> {
+        // 模拟计算密集型操作
+        await new Promise(resolve => setTimeout(resolve, 10));
+        return true;
+    }
+
+    private recordMetric(methodName: string, duration: number): void {
+        const current = this.metrics.get(methodName) || 0;
+        this.metrics.set(methodName, current + duration);
+    }
+
+    // 定期清理缓存
+    startCleanupTimer(): void {
+        setInterval(() => {
+            this.cache.clear();
+            logger.info(`[${this.name}] 缓存已清理`);
+        }, 300000); // 5分钟
+    }
+}
+```
+
+### 🔍 调试技巧
+
+#### 1. 启用调试模式
+
+```typescript
+export class DebuggableAnnotationProcessor implements AnnotationProcessor {
+    readonly name = 'DebuggableAnnotation';
+    readonly priority = 10;
+
+    private debugMode = process.env.ANNOTATION_DEBUG === 'true';
+
+    async process(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: any,
+        callParams: any[]
+    ): Promise<boolean> {
+        if (this.debugMode) {
+            console.log(`[DEBUG] ${this.name} 开始处理:`, {
+                controller: controller.constructor.name,
+                method: methodName,
+                data: annotationData,
+                params: callParams
+            });
+        }
+
+        // 主要逻辑
+        const result = await this.executeLogic(ctx, controller, methodName, annotationData, callParams);
+
+        if (this.debugMode) {
+            console.log(`[DEBUG] ${this.name} 处理完成:`, { result });
+        }
+
+        return result;
+    }
+
+    private async executeLogic(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: any,
+        callParams: any[]
+    ): Promise<boolean> {
+        // 实现逻辑
+        return true;
+    }
+}
+```
+
+#### 2. 性能分析
+
+```typescript
+export class ProfiledAnnotationProcessor implements AnnotationProcessor {
+    readonly name = 'ProfiledAnnotation';
+    readonly priority = 10;
+
+    private profileData: Map<string, { count: number; totalTime: number; avgTime: number }> = new Map();
+
+    async process(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: any,
+        callParams: any[]
+    ): Promise<boolean> {
+        const startTime = process.hrtime.bigint();
+        
+        try {
+            const result = await this.executeLogic(ctx, controller, methodName, annotationData, callParams);
+            
+            // 记录性能数据
+            const endTime = process.hrtime.bigint();
+            const duration = Number(endTime - startTime) / 1000000; // 转换为毫秒
+            
+            this.recordProfile(methodName, duration);
+            
+            return result;
+            
+        } catch (error) {
+            logger.error(`[${this.name}] 处理失败:`, error);
+            return true;
+        }
+    }
+
+    private recordProfile(methodName: string, duration: number): void {
+        const current = this.profileData.get(methodName) || { count: 0, totalTime: 0, avgTime: 0 };
+        
+        current.count++;
+        current.totalTime += duration;
+        current.avgTime = current.totalTime / current.count;
+        
+        this.profileData.set(methodName, current);
+    }
+
+    getProfileData(): Map<string, any> {
+        return new Map(this.profileData);
+    }
+
+    printProfileReport(): void {
+        console.log('\n=== 注解性能分析报告 ===');
+        this.profileData.forEach((data, methodName) => {
+            console.log(`${methodName}:`, {
+                调用次数: data.count,
+                总耗时: `${data.totalTime.toFixed(2)}ms`,
+                平均耗时: `${data.avgTime.toFixed(2)}ms`
+            });
+        });
+        console.log('========================\n');
+    }
+}
+```
+
+### 📖 完整示例
+
+#### 业务注解示例：数据加密注解
+
+```typescript
+// 1. 配置接口
+export interface DataEncryptionConfig {
+    enabled?: boolean;
+    algorithm?: 'AES' | 'RSA' | 'DES';
+    key?: string;
+    fields?: string[];
+    encryptRequest?: boolean;
+    encryptResponse?: boolean;
+}
+
+// 2. 注解处理器
+export class DataEncryptionProcessor implements AnnotationProcessor {
+    readonly name = 'DataEncryption';
+    readonly priority = 5;
+
+    private encryptionService: EncryptionService;
+
+    constructor() {
+        this.encryptionService = new EncryptionService();
+    }
+
+    async process(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: DataEncryptionConfig,
+        callParams: any[]
+    ): Promise<boolean> {
+        if (!annotationData.enabled) return true;
+
+        try {
+            // 加密请求数据
+            if (annotationData.encryptRequest) {
+                await this.encryptRequestData(ctx, annotationData);
+            }
+
+            return true;
+        } catch (error) {
+            logger.error(`[${this.name}] 加密失败:`, error);
+            return false;
+        }
+    }
+
+    async postProcess(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        response: any
+    ): Promise<void> {
+        const annotationData = this.getAnnotationData(ctx);
+        if (!annotationData?.enabled) return;
+
+        try {
+            // 加密响应数据
+            if (annotationData.encryptResponse) {
+                await this.encryptResponseData(ctx, response, annotationData);
+            }
+        } catch (error) {
+            logger.error(`[${this.name}] 响应加密失败:`, error);
+        }
+    }
+
+    private async encryptRequestData(ctx: Context, config: DataEncryptionConfig): Promise<void> {
+        if (ctx.request.body && config.fields) {
+            for (const field of config.fields) {
+                if (ctx.request.body[field]) {
+                    ctx.request.body[field] = await this.encryptionService.encrypt(
+                        ctx.request.body[field],
+                        config.algorithm || 'AES',
+                        config.key
+                    );
+                }
+            }
+        }
+    }
+
+    private async encryptResponseData(
+        ctx: Context,
+        response: any,
+        config: DataEncryptionConfig
+    ): Promise<void> {
+        if (response && config.fields) {
+            for (const field of config.fields) {
+                if (response[field]) {
+                    response[field] = await this.encryptionService.encrypt(
+                        response[field],
+                        config.algorithm || 'AES',
+                        config.key
+                    );
+                }
+            }
+        }
+    }
+
+    private getAnnotationData(ctx: Context): DataEncryptionConfig | null {
+        // 从上下文中获取注解数据
+        return ctx.state.annotationData || null;
+    }
+}
+
+// 3. 装饰器
+export function DataEncryption(config?: DataEncryptionConfig) {
+    return createAnnotationDecorator('DataEncryption')(config);
+}
+
+// 4. 使用示例
+export class SecureController {
+    @Post('/secure/data')
+    @DataEncryption({
+        enabled: true,
+        algorithm: 'AES',
+        fields: ['password', 'ssn'],
+        encryptRequest: true,
+        encryptResponse: true
+    })
+    @Logging()
+    async handleSecureData(@Body() data: any) {
+        return {
+            message: 'Data processed securely',
+            data: data
+        };
+    }
+}
+```
+
+通过以上完整的自定义注解开发指南，开发者可以：
+
+1. **理解注解系统架构**：掌握注解处理器的工作原理
+2. **开发自定义注解**：从需求分析到实现部署的完整流程
+3. **应用最佳实践**：性能优化、错误处理、测试等
+4. **解决实际问题**：通过实际业务场景的注解开发
+
+这套开发指南为企业级注解系统的扩展提供了坚实的基础！
+
+## 🎉 总结
+
+企业级注解系统提供了完整的企业级应用支持，包括：
+
+- **🔧 完整的监控体系**: 性能、安全、追踪、配置
+- **🛡️ 企业级安全**: 审计、合规、风险评估
+- **📊 可观测性**: 指标、日志、追踪三位一体
+- **⚙️ 配置管理**: 动态配置、环境管理、验证
+- **🚀 高性能**: 优化的执行性能和资源使用
+- **📝 类型安全**: 完整的 TypeScript 支持
+- **🔍 易于调试**: 丰富的调试工具和日志
+
+通过合理使用这些注解，可以构建出符合企业级标准的应用程序，满足现代企业对可观测性、安全性和可维护性的要求。
+
+