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

API处理器架构说明

概述

本目录实现了基于依赖注入容器的API处理器架构，支持灵活的依赖管理和组合调用模式。

架构模式

1. 依赖注入容器模式

ProcessorDependencies

type ProcessorDependencies struct {
    WestDexService *westdex.WestDexService
    YushanService  *yushan.YushanService
    Validator      interfaces.RequestValidator
}

优势：

• 统一的依赖管理
• 类型安全的依赖注入
• 易于测试和mock
• 支持未来扩展新的服务

处理器函数签名

type ProcessorFunc func(ctx context.Context, params []byte, deps *ProcessorDependencies) ([]byte, error)

2. 组合处理器模式

CompositeProcessor

专门用于处理组合包（COMB系列）的处理器，支持：

• 动态注册其他处理器
• 批量调用多个处理器
• 结果组合和格式化

type CompositeProcessor struct {
    processors map[string]ProcessorFunc
    deps       *ProcessorDependencies
}

目录结构

processors/
├── dependencies.go          # 依赖容器定义
├── comb/
│   ├── comb_processor.go    # 组合处理器基类
│   └── comb298y_processor.go # COMB298Y组合处理器
├── flxg/                    # FLXG系列处理器
├── jrzq/                    # JRZQ系列处理器
├── qygl/                    # QYGL系列处理器
├── yysy/                    # YYSY系列处理器
└── ivyz/                    # IVYZ系列处理器

服务分配策略

WestDexService

• FLXG系列：使用WestDexService
• JRZQ系列：使用WestDexService
• IVYZ系列：使用WestDexService

YushanService

• QYGL系列：使用YushanService
• YYSY系列：使用YushanService

组合包（COMB）

• 调用多个其他处理器
• 组合结果并返回统一格式

使用示例

普通处理器

func ProcessFLXG0V3Bequest(ctx context.Context, params []byte, deps *ProcessorDependencies) ([]byte, error) {
    // 参数验证
    var paramsDto dto.FLXG0V3BequestReq
    if err := json.Unmarshal(params, &paramsDto); err != nil {
        return nil, fmt.Errorf("参数校验不正确: 解密后的数据格式错误")
    }
    
    if err := deps.Validator.ValidateStruct(paramsDto); err != nil {
        return nil, fmt.Errorf("参数校验不正确: %s", err.Error())
    }
    
    // 调用服务
    reqData := map[string]interface{}{
        "name":   paramsDto.Name,
        "idCard": paramsDto.IDCard,
        "mobile": paramsDto.Mobile,
    }
    
    respBytes, err := deps.WestDexService.CallAPI("FLXG0V3B", reqData)
    if err != nil {
        return nil, fmt.Errorf("调用外部服务失败: %s", err.Error())
    }
    
    return respBytes, nil
}

组合处理器

func ProcessCOMB298YRequest(ctx context.Context, params []byte, deps *ProcessorDependencies) ([]byte, error) {
    // 创建组合处理器
    compositeProcessor := NewCompositeProcessor(deps)
    
    // 注册需要调用的处理器
    compositeProcessor.RegisterProcessor("FLXG0V3B", flxg.ProcessFLXG0V3Bequest)
    compositeProcessor.RegisterProcessor("JRZQ8203", jrzq.ProcessJRZQ8203Request)
    
    // 调用并组合结果
    results := make(map[string]interface{})
    
    flxgResult, err := compositeProcessor.CallProcessor(ctx, "FLXG0V3B", params)
    if err != nil {
        return nil, fmt.Errorf("调用FLXG0V3B处理器失败: %s", err.Error())
    }
    results["flxg0v3b"] = string(flxgResult)
    
    // 返回组合结果
    return compositeProcessor.CombineResults(results)
}

扩展指南

添加新的服务依赖

1. 在 ProcessorDependencies 中添加新字段
2. 更新 NewProcessorDependencies 构造函数
3. 在 ApiRequestService 中注入新服务

添加新的处理器

1. 在对应目录下创建新的处理器文件
2. 实现 ProcessorFunc 接口
3. 在 RequestProcessors 映射中注册

添加新的组合包

1. 在 comb/ 目录下创建新的组合处理器
2. 使用 CompositeProcessor 基类
3. 注册需要调用的处理器并组合结果

优势

1. 解耦：处理器与具体服务实现解耦
2. 可测试：易于进行单元测试和集成测试
3. 可扩展：支持添加新的服务和处理器
4. 类型安全：编译时检查依赖关系
5. 组合支持：灵活的组合调用模式
6. 维护性：清晰的代码结构和职责分离