tyapi-server/internal/domains/api/services/processors/OPTIONS_USAGE.md

# 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 传递给所有子处理器，无需额外配置。