v0.1

internal/domains/api/services/processors/OPTIONS_USAGE.md

@@ -0,0 +1,195 @@
+# Options 使用指南
+
+## 概述
+
+Options 机制允许在 API 调用时传递额外的配置选项，这些选项会传递给所有处理器（包括组合包处理器和子处理器），实现灵活的配置控制。
+
+## 架构设计
+
+```
+ApiCallCommand.Options → api_application_service → api_request_service → 所有处理器
+                                                      ↓
+                                              组合包处理器 → 子处理器
+```
+
+## Options 字段说明
+
+```go
+type ApiCallOptions struct {
+    Json        bool   `json:"json,omitempty"`        // 是否返回JSON格式
+    Debug       bool   `json:"debug,omitempty"`       // 调试模式
+    Timeout     int    `json:"timeout,omitempty"`     // 超时时间(秒)
+    RetryCount  int    `json:"retry_count,omitempty"` // 重试次数
+    Async       bool   `json:"async,omitempty"`       // 异步处理
+    Priority    int    `json:"priority,omitempty"`    // 优先级(1-10)
+    Cache       bool   `json:"cache,omitempty"`       // 是否使用缓存
+    Compress    bool   `json:"compress,omitempty"`    // 是否压缩响应
+    Encrypt     bool   `json:"encrypt,omitempty"`     // 是否加密响应
+    Validate    bool   `json:"validate,omitempty"`    // 是否严格验证
+    LogLevel    string `json:"log_level,omitempty"`   // 日志级别
+}
+```
+
+## 使用示例
+
+### 1. 普通处理器中使用 Options
+
+```go
+func ProcessYYSY4B37Request(ctx context.Context, params []byte, deps *processors.ProcessorDependencies) ([]byte, error) {
+    // ... 参数验证 ...
+    
+    reqData := map[string]interface{}{
+        "mobile": paramsDto.Mobile,
+    }
+
+    // 使用 Options 调整请求参数
+    if deps.Options != nil {
+        if deps.Options.Timeout > 0 {
+            reqData["timeout"] = deps.Options.Timeout
+        }
+        
+        if deps.Options.RetryCount > 0 {
+            reqData["retry_count"] = deps.Options.RetryCount
+        }
+        
+        if deps.Options.Debug {
+            reqData["debug"] = true
+        }
+    }
+
+    return deps.YushanService.CallAPI("YYSY4B37", reqData)
+}
+```
+
+### 2. 组合包处理器中使用 Options
+
+```go
+func ProcessCOMB298YRequest(ctx context.Context, params []byte, deps *processors.ProcessorDependencies) ([]byte, error) {
+    // ... 参数验证 ...
+    
+    // 根据 Options 调整组合策略
+    if deps.Options != nil {
+        if deps.Options.Priority > 0 {
+            // 高优先级时调整处理策略
+            fmt.Printf("组合包处理优先级: %d\n", deps.Options.Priority)
+        }
+        
+        if deps.Options.Debug {
+            fmt.Printf("组合包调试模式开启\n")
+        }
+    }
+
+    // Options 会自动传递给所有子处理器
+    return deps.CombService.ProcessCombRequest(ctx, params, deps, "COMB298Y")
+}
+```
+
+### 3. 客户端调用示例
+
+```json
+{
+  "data": "加密的请求数据",
+  "options": {
+    "debug": true,
+    "timeout": 30,
+    "retry_count": 3,
+    "priority": 5,
+    "cache": true,
+    "log_level": "debug"
+  }
+}
+```
+
+## 最佳实践
+
+### 1. 空值检查
+始终检查 `deps.Options` 是否为 `nil`，避免空指针异常：
+
+```go
+if deps.Options != nil {
+    // 使用 Options
+}
+```
+
+### 2. 默认值处理
+为 Options 字段提供合理的默认值：
+
+```go
+timeout := 30 // 默认30秒
+if deps.Options != nil && deps.Options.Timeout > 0 {
+    timeout = deps.Options.Timeout
+}
+```
+
+### 3. 验证选项值
+对 Options 中的值进行验证：
+
+```go
+if deps.Options != nil {
+    if deps.Options.Priority < 1 || deps.Options.Priority > 10 {
+        return nil, fmt.Errorf("优先级必须在1-10之间")
+    }
+}
+```
+
+### 4. 日志记录
+在调试模式下记录 Options 信息：
+
+```go
+if deps.Options != nil && deps.Options.Debug {
+    log.Printf("处理器选项: %+v", deps.Options)
+}
+```
+
+## 扩展性
+
+### 1. 添加新的 Options 字段
+在 `ApiCallOptions` 结构体中添加新字段：
+
+```go
+type ApiCallOptions struct {
+    // ... 现有字段 ...
+    CustomField string `json:"custom_field,omitempty"` // 自定义字段
+}
+```
+
+### 2. 处理器特定选项
+可以为特定处理器创建专门的选项结构：
+
+```go
+type YYSYOptions struct {
+    ApiCallOptions
+    YYSYSpecific bool `json:"yysy_specific,omitempty"`
+}
+```
+
+## 注意事项
+
+1. **性能影响**: Options 传递会增加少量性能开销，但影响微乎其微
+2. **向后兼容**: 新增的 Options 字段应该使用 `omitempty` 标签
+3. **安全性**: 敏感配置不应该通过 Options 传递
+4. **文档化**: 新增 Options 字段时应该更新文档
+
+## 调试技巧
+
+### 1. 启用调试模式
+```json
+{
+  "options": {
+    "debug": true,
+    "log_level": "debug"
+  }
+}
+```
+
+### 2. 查看 Options 传递
+在处理器中添加日志：
+
+```go
+if deps.Options != nil {
+    log.Printf("处理器 %s 收到选项: %+v", "YYSY4B37", deps.Options)
+}
+```
+
+### 3. 组合包调试
+组合包处理器会自动将 Options 传递给所有子处理器，无需额外配置。