Files

lanyuanxiaoyao bc1ee612d9 refactor: 实现 ConversionEngine 协议转换引擎，替代旧 protocol 包

- 新增 ConversionEngine 核心引擎，支持 OpenAI 和 Anthropic 协议转换
- 添加 stream decoder/encoder 实现
- 更新 provider client 支持新引擎
- 补充单元测试和集成测试
- 更新 specs 文档

2026-04-20 13:02:28 +08:00

3.9 KiB

Raw Blame History

Unified Proxy Handler

ADDED Requirements

Requirement: 实现统一代理 Handler

系统 SHALL 实现统一的 ProxyHandler，替代现有的 OpenAIHandler 和 AnthropicHandler。

ProxyHandler SHALL 依赖 ConversionEngine、ProviderClient、RoutingService、StatsService。

Scenario: 从 URL 提取客户端协议

WHEN 收到 /{protocol}/v1/{path} 格式的请求
THEN SHALL 从 URL 第一段提取 protocol 作为 clientProtocol
THEN SHALL 剥离前缀得到 nativePath

Scenario: 协议前缀必须是已注册协议

WHEN 收到的 URL 前缀不是已注册的协议名称
THEN SHALL 返回 404 错误

Scenario: 接口类型识别

WHEN 提取 nativePath 后
THEN SHALL 通过 ConversionEngine.convertHttpRequest 内部调用 clientAdapter.detectInterfaceType(nativePath) 识别接口类型
THEN 未知路径 SHALL 使用透传模式

Requirement: 非流式请求处理流程

ProxyHandler SHALL 按以下流程处理非流式请求。

Scenario: 完整转换流程

WHEN 收到非流式请求
THEN SHALL 解析请求体为 JSON
THEN SHALL 调用 RoutingService.Route(modelName) 获取路由结果
THEN SHALL 从路由结果的 Provider.Protocol 获取 providerProtocol
THEN SHALL 构建 TargetProvider（base_url, api_key, model_name, adapter_config）
THEN SHALL 调用 engine.convertHttpRequest(body, clientProtocol, providerProtocol, provider)
THEN SHALL 调用 providerClient.Send(ctx, requestSpec)
THEN SHALL 调用 engine.convertHttpResponse(response, clientProtocol, providerProtocol, interfaceType)
THEN SHALL 将转换后的响应返回给客户端

Scenario: 路由失败处理

WHEN RoutingService.Route 返回错误
THEN SHALL 使用 clientProtocol 对应的 Adapter.encodeError 编码错误响应
THEN SHALL 返回适当的 HTTP 状态码

Scenario: 上游请求失败处理

WHEN ProviderClient.Send 返回错误
THEN SHALL 使用 clientProtocol 对应的 Adapter.encodeError 编码错误响应
THEN SHALL 包装原始错误信息

Requirement: 流式请求处理流程

ProxyHandler SHALL 按以下流程处理流式请求。

Scenario: 流式转换流程

WHEN 请求中 stream=true 或接口类型为 CHAT 且请求体含 stream:true
THEN SHALL 执行与非流式相同的前置处理（路由、构建 TargetProvider）
THEN SHALL 调用 engine.convertHttpRequest 获取 HTTPRequestSpec
THEN SHALL 调用 providerClient.SendStream(ctx, requestSpec) 获取流
THEN SHALL 调用 engine.createStreamConverter(clientProtocol, providerProtocol, provider)
THEN SHALL 设置响应 Header Content-Type: text/event-stream
THEN SHALL 对每个流 chunk 调用 converter.processChunk 并写入响应
THEN SHALL 在流结束时调用 converter.flush() 刷新缓冲

Scenario: 同协议透传流式

WHEN clientProtocol == providerProtocol
THEN SHALL 直接将上游 SSE 字节流写入响应
THEN SHALL NOT 做任何解析或转换

Scenario: 流式错误处理

WHEN 流过程中发生错误
THEN SHALL 记录错误日志
THEN SHALL 关闭响应流

Requirement: 统计记录

ProxyHandler SHALL 记录请求统计。

Scenario: 异步记录统计

WHEN 请求处理完成（成功或失败）
THEN SHALL 异步调用 StatsService.Record
THEN SHALL NOT 阻塞响应返回

Requirement: GET 请求透传

ProxyHandler SHALL 支持 GET 请求的扩展层接口代理。

Scenario: Models 接口<E68EA5><E58FA3>理

WHEN 收到 GET /{protocol}/v1/models 请求
THEN SHALL 执行路由和协议识别
THEN SHALL 调用 engine.convertHttpRequest（GET 请求 body 为空）
THEN SHALL 调用 providerClient.Send 发送请求
THEN SHALL 调用 engine.convertHttpResponse 转换响应格式
THEN SHALL 返回转换后的响应

3.9 KiB Raw Blame History Unescape Escape