team/tyapi-server

Fork 0

Files

liangzai 357639462a v0.1

2025-07-28 01:46:39 +08:00

4.9 KiB

Raw Blame History

Options 使用指南

概述

Options 机制允许在 API 调用时传递额外的配置选项，这些选项会传递给所有处理器（包括组合包处理器和子处理器），实现灵活的配置控制。

架构设计

ApiCallCommand.Options → api_application_service → api_request_service → 所有处理器
                                                      ↓
                                              组合包处理器 → 子处理器

Options 字段说明

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

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

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. 客户端调用示例

{
  "data": "加密的请求数据",
  "options": {
    "debug": true,
    "timeout": 30,
    "retry_count": 3,
    "priority": 5,
    "cache": true,
    "log_level": "debug"
  }
}

最佳实践

1. 空值检查

始终检查 deps.Options 是否为 nil，避免空指针异常：

if deps.Options != nil {
    // 使用 Options
}

2. 默认值处理

为 Options 字段提供合理的默认值：

timeout := 30 // 默认30秒
if deps.Options != nil && deps.Options.Timeout > 0 {
    timeout = deps.Options.Timeout
}

3. 验证选项值

对 Options 中的值进行验证：

if deps.Options != nil {
    if deps.Options.Priority < 1 || deps.Options.Priority > 10 {
        return nil, fmt.Errorf("优先级必须在1-10之间")
    }
}

4. 日志记录

在调试模式下记录 Options 信息：

if deps.Options != nil && deps.Options.Debug {
    log.Printf("处理器选项: %+v", deps.Options)
}

扩展性

1. 添加新的 Options 字段

在 ApiCallOptions 结构体中添加新字段：

type ApiCallOptions struct {
    // ... 现有字段 ...
    CustomField string `json:"custom_field,omitempty"` // 自定义字段
}

2. 处理器特定选项

可以为特定处理器创建专门的选项结构：

type YYSYOptions struct {
    ApiCallOptions
    YYSYSpecific bool `json:"yysy_specific,omitempty"`
}

注意事项

性能影响: Options 传递会增加少量性能开销，但影响微乎其微
向后兼容: 新增的 Options 字段应该使用 omitempty 标签
安全性: 敏感配置不应该通过 Options 传递
文档化: 新增 Options 字段时应该更新文档

调试技巧

1. 启用调试模式

{
  "options": {
    "debug": true,
    "log_level": "debug"
  }
}

2. 查看 Options 传递

在处理器中添加日志：

if deps.Options != nil {
    log.Printf("处理器 %s 收到选项: %+v", "YYSY4B37", deps.Options)
}

3. 组合包调试

组合包处理器会自动将 Options 传递给所有子处理器，无需额外配置。

4.9 KiB Raw Blame History